Convert examples to Markdown

Author: threehams

.storybook/addons.js

@@ -0,0 +1,2 @@
+// import '@storybook/addon-actions/register';
+import "@storybook/addon-links/register";

.storybook/config.js

@@ -0,0 +1,17 @@
+import React from "react";
+import { configure } from "@storybook/react";
+import { addDecorator } from "@storybook/react";
+
+// automatically import all files ending in *.stories.js
+configure(require.context("../stories", true, /\.stories\.tsx$/), module);
+
+const styles = {
+  fontFamily: "Open Sans, sans-serif",
+  fontSize: "1rem",
+  maxWidth: 1000,
+  paddingLeft: 20,
+  paddingRight: 20,
+  margin: "0 auto",
+};
+const LayoutDecorator = storyFn => <div style={styles}>{storyFn()}</div>;
+addDecorator(LayoutDecorator);

.storybook/preview-head.html

@@ -0,0 +1,4 @@
+<link
+  href="https://fonts.googleapis.com/css?family=Open+Sans:400,600&display=swap"
+  rel="stylesheet"
+/>

.storybook/webpack.config.js

@@ -0,0 +1,20 @@
+const path = require("path");
+const MonacoWebpackPlugin = require("monaco-editor-webpack-plugin");
+const MONACO_DIR = path.resolve(__dirname, "./node_modules/monaco-editor");
+const util = require("util");
+
+module.exports = async ({ config }) => {
+  config.module.rules.push({
+    test: /\.tsx?$/,
+    use: ["babel-loader"],
+  });
+  config.module.rules.push({
+    test: /\.css$/,
+    use: ["style-loader", "css-loader"],
+    include: MONACO_DIR,
+  });
+  config.plugins.push(new MonacoWebpackPlugin());
+  config.resolve.extensions = [".ts", ".tsx", ".js"];
+  config.externals = { "@microsoft/typescript-etw": "FakeModule" };
+  return config;
+};

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: ["@babel/env", "@babel/react", "@babel/typescript"],
+};

examples/array-element-access.md

@@ -0,0 +1,40 @@
+This seems wrong...
+
+```tsx
+const array = [0, 1];
+array[0];
+array[1];
+array[2]; // hey! this should be an error!
+```
+
+but just like objects are mutable in TS, so are arrays.
+Imagine this case:
+
+```tsx
+const pushToArray = <T extends any>(arr: T[], element: T): T[] => {
+  arr.push(element);
+  return arr;
+};
+
+const arr = [0, 1];
+pushToArray(arr, 2); // now arr[2] exists
+arr[2]; // if TS showed an error here, it would be extremely annoying
+```
+
+TypeScript would have to do a lot more work to analyze your code to figure
+out safe array access - and it's just not a common enough case to be worth
+the cost.
+
+However, tuple types exist, which have a known length that can never change.
+Checking access on these is cheap, so use `as const` to change from number[]
+(array of numbers of any length) to [number, number] (array of numbers with
+a length of 2).
+(you'll see the term "const context" floating around: it means "immutable")
+
+```tsx
+const tuple = [0, 1] as const;
+
+tuple[0];
+tuple[1];
+tuple[2]; // correctly an error
+```

examples/array-element-access.ts

@@ -1,19 +1,20 @@
-export {};
-// diagnostic codes: ts2339, ts2741
+diagnostic codes: ts2339, ts2741
 
-// possibly related: control flow analysis
-// https://github.com/Microsoft/TypeScript/issues/9998
+## Related Issues
 
-// Sometimes, you need to initialize an object and add properties
-// one by one, often with a check each time.
+[Issue #9998: Tradeoffs in Control Flow Analysis](https://github.com/Microsoft/TypeScript/issues/9998)
 
+## The Problem
+
+Sometimes, you need to initialize an object and add properties one by one, often with a check each time.
+
+```tsx
 interface Result {
   name?: string;
   value: string | number;
 }
 
-let buildResult;
-buildResult = (name?: string) => {
+const startWithEmpty = (name?: string) => {
   const result = {};
   // error, this property doesn't exist on {}
   if (name) {
@@ -22,32 +23,42 @@ buildResult = (name?: string) => {
   result.value = 1;
 };
 
-buildResult = (name?: string) => {
+const addType = (name?: string) => {
   const result: Result = {}; // error, missing property "value"
   if (name) {
     result.name = name;
   }
   result.value = 1;
 };
 
-buildResult = (name?: string): Result => {
+const addAssertion = (name?: string): Result => {
   const result = {} as Result;
   if (name) {
     result.name = name;
   }
   result.value = 1; // comment out this line: note, no error
   return result;
 };
+```
+
+## Why does this happen?
+
+## What do I do about it?
+
+For simple cases, just have two returns.
 
-// for simple cases, just have two returns
+```tsx
 buildResult = (name?: string): Result => {
   if (name) {
     return { name, value: 1 };
   }
   return { value: 1 };
 };
+```
 
-// ...or redefine a variable
+...or redefine a variable.
+
+```tsx
 buildResult = (name?: string): Result => {
   let result: Result;
   if (name) {
@@ -57,36 +68,37 @@ buildResult = (name?: string): Result => {
   }
   return result;
 };
+```
+
+...or use a utility.
+
+```tsx
+// remember keys + entries and open types:
+// https://github.com/Microsoft/TypeScript/pull/12253#issuecomment-263132208
+const keys = Object.keys as <T>(o: T) => Extract<keyof T, string>[];
+const entries = Object.entries as <
+  T extends { [key: string]: any },
+  K extends keyof T
+>(
+  o: T,
+) => [keyof T, T[K]][];
 
-// or use a utility
 const filterNulls = <T extends { [key: string]: any }, K>(
-  obj: T
+  obj: T,
 ): { [K in keyof T]: T[K] extends any ? T[K] : null } => {
-  return entries(obj).reduce(
-    (acc, [key, value]) => {
-      // == null matches null or undefined
-      if (value != null) {
-        acc[key] = value;
-      }
-      return acc;
-    },
-    {} as T
-  );
+  return entries(obj).reduce((acc, [key, value]) => {
+    // == null matches null or undefined
+    if (value != null) {
+      acc[key] = value;
+    }
+    return acc;
+  }, {} as T);
 };
 
 buildResult = (name?: string): Result => {
   return filterNulls({
     name: name,
-    value: 1
+    value: 1,
   });
 };
-
-// remember keys + entries and open types:
-// https://github.com/Microsoft/TypeScript/pull/12253#issuecomment-263132208
-const keys = Object.keys as <T>(o: T) => (Extract<keyof T, string>)[];
-const entries = Object.entries as <
-  T extends { [key: string]: any },
-  K extends keyof T
->(
-  o: T
-) => [keyof T, T[K]][];
+```