67 | Next: Project Tour ▶ 68 |
69 | -------------------------------------------------------------------------------- /notes/01-project-tour.md: -------------------------------------------------------------------------------- 1 |2 | ◀ Back: Intro 3 |
4 | 5 | --- 6 | 7 | # Project tour and getting started 8 | 9 | In this workshop we'll be working in the context of a simplified Slack app 10 | 11 |  12 | 13 | As we begin the course, it's written entirely in JavaScript, and is comprised of a few mostly stateless React components. 14 | 15 | The web client for this app lives in [`src/`](../src/), and is roughly organized as 16 | 17 | ```bash 18 | src/ # web client 19 | data/ # data layer 20 | ui/ # react components 21 | utils/ # low-level utilities 22 | index.js # entry point 23 | ``` 24 | 25 | There's a API and database in this project as well, but we won't be changing them during the workshop. 26 | 27 | The database comes from your [`db.json`](../db.json) file, and the API code is located in the [`server/`](../server/) folder. 28 | 29 | **One thing you _absolutely will_ want to look at is the API documentation, which can be found in your [`API_EXAMPLES.http`](API_EXAMPLES.http) file**. 30 | 31 | --- 32 | 33 |34 | Next: Recent TS Language Features ▶ 35 |
36 | -------------------------------------------------------------------------------- /notes/02-recent-ts-features.md: -------------------------------------------------------------------------------- 1 |2 | ◀ Back: Project Tour 3 |
4 | 5 | --- 6 | 7 | # TS 3.7 -> 4.1: Quick Summary 8 | 9 | ## Modern JS Language Features 10 | 11 | ### Optional Chaining (3.7) 12 | 13 | Stops running expression if a null or undefined is encountered 14 | 15 | - 🚧 **Warning:** adds complexity. Beware of multiple optional links in a single expression 16 | - 🚧 **Warning:** not appropriate to just “power through” nullish values 17 | - 🚧 **Warning:** only short-circuits the expression in question, not any other compound expressions joined by operators 18 | 19 | ### Nullish Coalescing (3.7) 20 | 21 | Useful for fallback defaults, where a user-supplied 0 or ‘’ would have been treated improperly 22 | 23 | - 🚧 **Warning:** not the same as ||, due to falsy values that aren’t nullish 24 | 25 | ### ECMAScript Private Fields (3.8) 26 | 27 | ```js 28 | class Foo { 29 | #bar; 30 | } 31 | ``` 32 | 33 | - “hard private” (undetectable from the outside) 34 | - Cannot be overridden by subclasses 35 | - Use WeakMap under the hood, so might perform differently compared to public class fields (not a problem unless you’re on a really hot path) 36 | 37 | ### Namespace exports (3.8) 38 | 39 | ```ts 40 | export * as utils from './utils.mjs'; 41 | ``` 42 | 43 | ### Inference of class field types (4.0) 44 | 45 | Types for class fields that are assigned in constructor are inferred, and no longer need an explicit type declaration 46 | 47 | ## Tuple Types 48 | 49 | ### Variadic tuple types (4.0) 50 | 51 | ```ts 52 | type StrStrNumNumBool = [...Strings, ...Numbers, boolean]; 53 | ``` 54 | 55 | ### Labeled tuple types (4.0) 56 | 57 | ```ts 58 | function foo(x: [first: string, second: number]) {} 59 | ``` 60 | 61 | ## More powerful type aliases and interfaces 62 | 63 | ### Recursive type aliases (3.7) 64 | 65 | JSON can now be typed in a single type alias! 66 | 67 | ### Recursive conditional types (4.1) 68 | 69 | ```ts 70 | type ElementType144 | Next: App vs. Library Concerns ▶ 145 |
146 | -------------------------------------------------------------------------------- /notes/03-app-vs-library-concerns.md: -------------------------------------------------------------------------------- 1 |2 | Next: Recent TS Language Features ▶ 3 |
4 | 5 | --- 6 | 7 | # TypeScript: App vs. Library Concerns 8 | 9 | ## Myths (almost always) 10 | 11 | - ❌ "No more runtime errors" 12 | - ❌ "My code will run measurably faster" 13 | 14 | ## Most TS Codebases 15 | 16 | - **Improved developer experience**, including in-editor docs for your dependencies 17 | - **Reduced need to "drill into” files** to understand how adjacent code works 18 | - **Micro “rigor” that adds up to macro benefits** 19 | I can type things well-enough and let the system help me when I cross the threshold beyond which I “remember” what’s going on, and what types a particular value could be 20 | - Developers can encode more of their intent 21 | - More formalized and stable contracts “between things” (i.e., one component to another) 22 | - **Coloring inside the lines** 23 | > - Stay on the public API surface of your dependencies 24 | > - Catch incomplete refactorings 25 | > - Some subset of runtime errors moved to compile time 26 | > - Using an ES2020 feature while needing to support ES2017 27 | > - Momentarily forgetting about browser or node APIs 28 | 29 | ## (mostly) App-specific concerns 30 | 31 | - More richness when working with data 32 | - Better encapsulation tools, to facilitate maintaining lazy loading boundaries 33 | - Improved “major version upgrade” story for typed libraries 34 | 35 | ## (mostly) Library-specific concerns 36 | 37 | - Create and maintain a deliberate public API surface 38 | ...while still being able to create a private API surface to use between modules or components 39 | - Keep your users on track (i.e., enums allow you to signal allowed value sets better than `number`) 40 | - SemVer (deprecations, breakage) 41 | - API Docs 42 | 43 | --- 44 | 45 |46 | Next: Mike's Professional-Grade TS Setup ▶ 47 |
48 | -------------------------------------------------------------------------------- /notes/04-mikes-ts-setup.md: -------------------------------------------------------------------------------- 1 |2 | ◀ Back: App vs. Library Concerns 3 |
4 | 5 | --- 6 | 7 | # Mike's "bare bones" TS setup 8 | 9 | In this part of the workshop, we'll create a new small library from nothing, so you can see how Mike's "lots of value out of few tools" approach keeps things nice and simple. 10 | 11 | ## Getting Started 12 | 13 | First, create a new directory and enter it 14 | 15 | ```sh 16 | mkdir my-lib 17 | cd my-lib 18 | ``` 19 | 20 | Then, create a `.gitignore` file 21 | 22 | ```sh 23 | npx gitignore node 24 | ``` 25 | 26 | and a package.json file 27 | 28 | ```sh 29 | yarn init --yes 30 | ``` 31 | 32 | Make a few direct modifications to your `package.json` file as follows 33 | 34 | ```diff 35 | --- a/package.json 36 | +++ b/package.json 37 | @@ -1,6 +1,13 @@ 38 | { 39 | "name": "my-lib", 40 | "version": "1.0.0", 41 | - "main": "index.js", 42 | + "main": "dist/index.js", 43 | + "types": "dist/index.d.ts", 44 | + "scripts": { 45 | + "build": "tsc", 46 | + "dev": "yarn build --watch --preserveWatchOutput", 47 | + "lint": "eslint src --ext js,ts", 48 | + "test": "jest" 49 | + }, 50 | "license": "MIT" 51 | } 52 | ``` 53 | 54 | This ensures that TS and non-TS consumers alike can use this library, and that we can run the following commands 55 | 56 | ```sh 57 | yarn build # build the project 58 | yarn dev # build, and rebuild when source is changed 59 | yarn lint # run the linter 60 | yarn test # run tests 61 | ``` 62 | 63 | Pin the node and yarn versions to their current stable releases using volta 64 | 65 | ```sh 66 | volta pin node yarn 67 | ``` 68 | 69 | this will add `node` and `yarn` versions to your `package.json` automatically. 70 | 71 | Next, initialize the git repository 72 | 73 | ```sh 74 | git init 75 | ``` 76 | 77 | ## TypeScript Compiler 78 | 79 | install typescript as a development dependency. We'll only need this at build 80 | time, because not all consumers of this library may be using TypeScript 81 | themselves. 82 | 83 | ```sh 84 | yarn add -D typescript 85 | ``` 86 | 87 | ## Setting up your tsconfig 88 | 89 | Create a default `tsconfig.json` 90 | 91 | ```sh 92 | yarn tsc --init 93 | ``` 94 | 95 | and ensure the following values are set: 96 | 97 | ```diff 98 | "compilerOptions": { 99 | + "outDir": "dist", 100 | + "rootDirs": ["src"], 101 | }, 102 | + "include": ["src"] 103 | ``` 104 | 105 | We want to make sure that the `src/` folder is where our source code lives, that it's treated as a root directory, and that the compiled output is in the `dist/` folder. 106 | 107 | Next, make sure that the TS compiler creates Node-friendly CommonJS modules, and that we target the ES2018 language level (Node 10, allowing for features like `async` and `await`). 108 | 109 | ```diff 110 | "compilerOptions": { 111 | + "module": "commonjs", 112 | + "target": "ES2018", 113 | } 114 | ``` 115 | 116 | Let's make sure two potentially problematic features are _disabled_. We'll talk later about why these are not great for a library. 117 | 118 | ```diff 119 | "compilerOptions": { 120 | + "esModuleInterop": false, 121 | + "skipLibCheck": false 122 | } 123 | ``` 124 | 125 | Make sure that the compiler outputs ambient type information in addition to the JavaScript 126 | 127 | ```diff 128 | "compilerOptions": { 129 | + "declaration": true, 130 | } 131 | ``` 132 | 133 | And finally, let's make sure that we set up an "extra strict" type-checking configuration 134 | 135 | ```diff 136 | "compilerOptions": { 137 | /** 138 | * "strict": true, 139 | * ------------------- 140 | * - noImplicitAny 141 | * - strictNullChecks 142 | * - strictFunctionTypes 143 | * - strictBindCallApply 144 | * - strictPropertyInitialization 145 | * - noImplicitThis 146 | * - alwaysStrict 147 | */ 148 | + "strict": true, 149 | + "noUnusedLocals": true, 150 | + "noImplicitReturns": true, 151 | + "stripInternal": true, 152 | + "types": [], 153 | + "forceConsistentCasingInFileNames": true, 154 | } 155 | ``` 156 | 157 | We'll go in to more detail later about what some of these options mean, and why I suggest setting them this way. 158 | 159 | Finally, please create a folder for your source code, and create an empty `index.ts` file within it 160 | 161 | ```sh 162 | mkdir src 163 | touch src/index.ts 164 | ``` 165 | 166 | Open `src/index.ts` and set its contents to the following 167 | 168 | ```ts 169 | /** 170 | * @packageDocumentation A small library for common math functions 171 | */ 172 | 173 | /** 174 | * Calculate the average of three numbers 175 | * 176 | * @param a - first number 177 | * @param b - second number 178 | * @param c - third number 179 | * 180 | * @public 181 | */ 182 | export function avg(a: number, b: number, c: number): number { 183 | return sum3(a, b, c) / 3; 184 | } 185 | 186 | /** 187 | * Calculate the sum of three numbers 188 | * 189 | * @param a - first number 190 | * @param b - second number 191 | * @param c - third number 192 | * 193 | * @beta 194 | */ 195 | export function sum3(a: number, b: number, c: number): number { 196 | return sum2(a, sum2(b, c)); 197 | } 198 | 199 | /** 200 | * Calculate the sum of two numbers 201 | * 202 | * @param a - first number 203 | * @param b - second number 204 | * 205 | * @internal 206 | */ 207 | export function sum2(a: number, b: number): number { 208 | const sum = a + b; 209 | return sum; 210 | } 211 | ``` 212 | 213 | This is obviously convoluted, but it'll serve our purposes for looking at some interesting behavior later. 214 | 215 | Let's make sure that things are working so far by trying to build this project. 216 | 217 | ```sh 218 | rm -rf dist # clear away any old compiled output 219 | yarn build # build the project 220 | ls dist # list the contents of the dist/ folder 221 | ``` 222 | 223 | You should see something like 224 | 225 | ```sh 226 | index.d.ts index.js 227 | ``` 228 | 229 | ## Linting 230 | 231 | Install eslint as a development dependency 232 | 233 | ```sh 234 | yarn add -D eslint 235 | ``` 236 | 237 | and go through the process of creating a starting point ESLint config file 238 | 239 | ```sh 240 | yarn eslint --init 241 | ``` 242 | 243 | When asked, please answer as follows for the choices presented to you: 244 | 245 |742 | Next: ...What have I done? ▶ 743 |
744 | -------------------------------------------------------------------------------- /notes/05-what-have-I-done.md: -------------------------------------------------------------------------------- 1 |2 | ◀ Back: Mike's Professional-Grade TS Setup 3 |
4 | 5 | --- 6 | 7 | # What have I done? 8 | 9 | Let's look closely at what we just did, and make sure we understand all of the parts that make up the whole 10 | 11 | ## In my `tsconfig.json` what exactly is "strict"? 12 | 13 | The source of truth is [here](https://github.com/microsoft/TypeScript/blob/dc8952d308c9de815e95bdb96727a9cbaedc9adb/src/compiler/commandLineParser.ts#L594), and it's important to know that this is a moving target 14 | 15 | ### `noImplicitAny` 16 | 17 | - “Default to explicit” instead of “default to loose” 18 | - This is not in any way restrictive, it only requires that we be explicit about `any` 19 | 20 | ### `noImplicitThis` 21 | 22 | - There are certain places where `this` is important and non-inferrable 23 | > Example: addEventListener 24 | > 25 | > ```ts 26 | > my_element.addEventListener('click', function (e) { 27 | > // logs the className of my_element 28 | > console.log(this.className); 29 | > // logs `true` 30 | > console.log(e.currentTarget === this); 31 | > }); 32 | > ``` 33 | 34 | ### `alwaysStrict` 35 | 36 | - JS “use strict” 37 | - necessary for modern JS language features 38 | 39 | ### `strictBindCallApply` 40 | 41 | - Bind, call, apply used to return very loosely-typed functions. 42 | - No good reasons I'm aware of to disable this 43 | 44 | ### `strictNullChecks` 45 | 46 | - Without this enabled, primitive types allow `null` values 47 | - Leaving this disabled makes truthy/falsy type guards much less useful 48 | - This is asking for runtime errors that could otherwise be caught at build time 49 | 50 | ### `strictFunctionTypes` 51 | 52 | - Some common-sense loopholes around matching function arguments during type-checking function values 53 | - [example](https://www.typescriptlang.org/play?#code/IYIwzgLgTsDGEAJYBthjAgggOwJYFthkEBvAKAUoQAcBXEZXWBUSGeBKAU2ABMB7bMgCeCZFwDmYAFwJstfCC5QA3GQC+ZFGgwBhYIi4APCF2y8MOAkVIUq4qQgC8CACxqqNWlCgAKAJSksIJg-OIAdMj8Er4A5HQ+sf6amtroCAAi0QjGpuaWeITE5J4OGC7udpQgwFAA1gFBIWFckdFxtQBmSSlkZLxc2txiXIidAIyyvkayVkWBTgB8CABu-Li8agNDXCNjAExTM5nRC8trG1uDqMPiYwDMR7L6EGer65tkE84InfsqlAA9ICEABRHz8KAIADuuAgAAsEABaJFsJgQABitGw8FwggAKsJqFwwF99j8JgCEMCEAB5Opkin3Kk08FQSFAA) 54 | > ```ts 55 | > abstract class Animal { 56 | > public abstract readonly legs: number; 57 | > } 58 | > class Cat extends Animal { 59 | > legs = 4; 60 | > purr() { 61 | > console.log('purr'); 62 | > } 63 | > } 64 | > class Dog extends Animal { 65 | > legs = 4; 66 | > bark() { 67 | > console.log('arf'); 68 | > } 69 | > } 70 | > 71 | > declare let f1: (x: Animal) => void; 72 | > declare let f2: (x: Dog) => void; 73 | > declare let f3: (x: Cat) => void; 74 | > 75 | > // Error with --strictFunctionTypes 76 | > f1 = f2; 77 | > f2 = f1; // Always ok 78 | > f2 = f3; // Always error 79 | > ``` 80 | 81 | ### `strictPropertyInitialization` 82 | 83 | - Holds you to your promises around class fields really being “always there” vs. “sometimes undefined” 84 | 85 | ## Even more strict 86 | 87 | ### `noUnusedLocals` 88 | 89 | - Busts you on unused local variables 90 | - Better to have TS detect this rather than a linter 91 | 92 | ### `noUnusedParameters` 93 | 94 | - Function arguments you don’t use need to be prefixed with \_ 95 | - I love this during the “exploration” phase of development b/c it highlights opportunities to simplify API surface 96 | 97 | ### `noImplicitReturns` 98 | 99 | - If any code paths return something explicitly, all code paths must return something explicitly 100 | 101 | ### `noFallthroughCasesInSwitch` 102 | 103 | - I’m ok with this one as being _disabled_, as I find case fall-throughs to be useful, important and easy (enough) to notice while reading code 104 | 105 | ### `types` 106 | 107 | - Instead of pulling in all @types/\*, specify exactly what should be available 108 | - **NOTE:** this is nuanced, and only affects global scope (i.e., window, process) and auto-import. 109 | - _Why I care:_ I don’t want types used exclusively in things like tests to be quite so readily available for accidental use in “app code” 110 | 111 | ### `stripInternal` (most important for libraries) 112 | 113 | - Sometimes you need type information to only be available within a codebase. 114 | - `@internal` JSdoc tag surgically strips out type information for respective symbols 115 | 116 | ## Don't go viral 117 | 118 | There are some compiler options that I _really dislike_ when used in libraries, because they have a high probability of "infecting" any consumer and depriving them from making choices about their own codebase 119 | 120 | ### `allowSyntheticDefaultImports` 121 | 122 | Allows you to import CommonJS modules as if they’re ES modules with a default export 123 | 124 | ### `esModuleInterop` 125 | 126 | Adds some runtime support for CJS/ESM interop, and enables allowSyntheticDefaultImports 127 | 128 | ### `skipDefaultLibCheck` 129 | 130 | This effectively ignores potential breaking changes that stem from your node_modules types mixing with your own types. Particularly if you’re building a library, you need to know that if you “hide” this problem they’ll still “feel” it (and probably need to “skip” too) 131 | 132 | ### But sometimes we need these, right? 133 | 134 | I have never found a good reason to enable these options in well-structured TS code. 135 | 136 | `allowSyntheticDefaultImports` and `esModuleInterop` aim to allow patterns like 137 | 138 | ```ts 139 | import fs from 'fs'; 140 | ``` 141 | 142 | in situations where `fs` doesn't actually expose an ES module `export default`. It exports a _namespace_ of filesystem-related functions. Thankfully, even with these flags _both_ disabled, we can still use a namespace import: 143 | 144 | ```ts 145 | import * as fs from 'fs'; 146 | ``` 147 | 148 | Now there are rare situations where some CommonJS code exports a single non-namespace thing in a way like 149 | 150 | ```ts 151 | // calculator.ts 152 | module.exports = function add(a, b) { 153 | return a + b; 154 | }; 155 | ``` 156 | 157 | add is definitely not a namespace, and 158 | 159 | ```ts 160 | import * as add from './calculator'; 161 | ``` 162 | 163 | WILL NOT WORK. There's a TS-specific pattern that _will work_ though -- it's a little weird, but it doesn't require turning any compiler options on 164 | 165 | ```ts 166 | import add = require('./calculator'); 167 | ``` 168 | 169 | ### Is Mike asking me to take on tech debt? 170 | 171 | You may be thinking "these don't look like ES modules", and "won't the TS team standardize on ES modules later?" 172 | 173 | The answer is: _yes_, but you should think about this the same way that you think about a "legacy" version of Node.js that you need to support 174 | 175 | - You shouldn't break consumers yet 176 | - Apps should be the first to adopt new things, followed by libraries that are more conservative 177 | 178 | TS modules predate ES modules, but there’s tons of code out there that already uses TS module stuff, and this is one of the most easy to codemod kinds of “tech debt” to incur. 179 | 180 | --- 181 | 182 |183 | Next: Converting to TypeScript ▶ 184 |
185 | ``` 186 | -------------------------------------------------------------------------------- /notes/06-converting-to-ts.md: -------------------------------------------------------------------------------- 1 |2 | ◀ Back: ...What have I done? 3 |
4 | 5 | --- 6 | 7 | # Converting to TypeScript 8 | 9 | In my [TS Fundamentals Course (v2)](https://drive.google.com/file/d/170oHzpLNeprUa-TMmOAnSU4caEFDSb3e/view) we discuss a procedure for progressively converting a codebase from JS to TS. 10 | 11 |12 | 13 |  14 | 15 |
16 |17 | 18 |  19 | 20 |
21 |22 | 23 |  24 | 25 |
26 |27 | 28 |  29 | 30 |
31 | 32 | Putting aside that the last image above is a bit redundant (with `"strict"` enabling `"strictNullChecks"`, `"strictFunctionTypes"` and `""strictNullChecks"` already), there's a lot of work to unpack here 33 | 34 | Realistically, this should be done in separate steps for a large codebase 35 | 36 | For example: 37 | 38 | - 3.1) strict mode 39 | 40 | ```diff 41 | --- a/tsconfig.json 42 | +++ b/tsconfig.json 43 | "compilerOptions": { 44 | + "strict": true, 45 | } 46 | ``` 47 | 48 | - 3.2) more strict mode 49 | 50 | ```diff 51 | --- a/tsconfig.json 52 | +++ b/tsconfig.json 53 | "compilerOptions": { 54 | + "noUnusedLocals": true, 55 | + "noImplicitReturns": true, 56 | + "stripInternal": true, 57 | + "types": [], 58 | + "forceConsistentCasingInFileNames": true 59 | } 60 | ``` 61 | 62 | - 3.3) TS-specific linting 63 | 64 | ```diff 65 | --- a/.eslintrc 66 | +++ b/.eslintrc 67 | + "parser": "@typescript-eslint/parser", 68 | "extends": [ 69 | + "prettier/@typescript-eslint", 70 | + "plugin:@typescript-eslint/recommended", 71 | + "plugin:@typescript-eslint/recommended-requiring-type-checking" 72 | ], 73 | ``` 74 | 75 | - 3.4) Even more strict mode 76 | 77 | ```diff 78 | --- a/.eslintrc 79 | +++ b/.eslintrc 80 | "rules": { 81 | + "@typescript-eslint/no-unsafe-assignment": "off", 82 | + "@typescript-eslint/no-unsafe-return": "off", 83 | + "@typescript-eslint/no-explicit-any": "off" 84 | } 85 | ``` 86 | 87 | There are steps beyond this conversion that are important in order to mitigate some other risks. We'll get into those later 88 | 89 | # CHALLENGE: Follow steps 1 and 2 to convert the workshop chat app from JS to ts 90 | 91 | ## Some Quick Tricks 92 | 93 | ```sh 94 | # rename all JSX files in src/ to TSX 95 | find src -name '*.jsx' -exec bash -c 'git mv "$0" "${0%.jsx}.tsx"' "{}" \; 96 | # rename all JS files in src/ to TS 97 | find src -name '*.js' -exec bash -c 'git mv "$0" "${0%.js}.ts"' "{}" \; 98 | # rename all JSX files in src/ to TSX 99 | find tests -name '*.jsx' -exec bash -c 'git mv "$0" "${0%.jsx}.tsx"' "{}" \; 100 | # rename all JSX files in src/ to TSX 101 | find tests -name '*.jsx.snap' -exec bash -c 'git mv "$0" "${0%.jsx.snap}.tsx.snap"' "{}" \; 102 | # rename all JS files in tests/ to TS 103 | find tests -name '*.js' -exec bash -c 'git mv "$0" "${0%.js}.ts"' "{}" \; 104 | ``` 105 | 106 | and don't forget to make this small change to [`/index.html`](/index.html) 107 | 108 | ```diff 109 | --- a/index.html 110 | +++ b/index.html 111 | @@ -8,6 +8,6 @@ 112 | 113 | 114 | 115 | - 116 | + 117 | 118 |