docs: information about updating TypeScript version (#13810)

denoland · Mar 3, 2022 · 1db7566 · 1db7566
1 parent e8c4775
commit 1db7566
Showing 1 changed file with 119 additions and 0 deletions.
diff --git a/tools/update_typescript.md b/tools/update_typescript.md
@@ -0,0 +1,119 @@
+# Updating the version of TypeScript
+
+This document provides an overview of how to update the version of TypeScript
+that is built into the Deno CLI.
+
+## Pre-flight checklist
+
+- [ ] git and a local clone of this repository
+- [ ] An npm package manager installed and available
+
+## Background information
+
+The TypeScript engine (`/cli/tsc/00_typescript.js`) provides type checking and
+transformation services for the Deno CLI.
+
+During the build (`/cli/build.rs`) the TypeScript engine, and integration code
+(`/cli/tsc/99_main_compiler.js`) are loaded into a V8 isolate, which in turn
+loads several of the baseline type libraries (`/cli/dts/*.d.ts`) as well as type
+libraries provided by extensions (`/ext/*`). This isolate is then snapshotted
+and included in the build of the CLI. This becomes the _COMPILER_ snapshot.
+
+There are a few type libraries that are not loaded into the isolate, as they are
+not "default" libraries at runtime, but we want to make them available to be
+loaded dynamically for a user. They are built into the binary as text resources
+during the build process.
+
+Because Deno often supports web standards in advance of TypeScript supporting
+them, we find ourselves in the undesirable situation of having to "patch" the
+published type libraries included with TypeScript. Also, to allow TypeScript to
+access any type libraries that aren't included with the distribution, we have to
+patch the list in the TypeScript, so they are available to users.
+
+While in theory a lot of this process could be automated, things can and do
+change in both Deno and TypeScript, and often you don't know that they have
+changed until you try to go through the process. Because updates to TypeScript
+are relatively infrequent, and the process requires a decent amount of
+contextual awareness, it is the author's opinion that it is best to spend the
+10-15 minutes updating by hand to ensure that everything works as expected.
+
+## Updating
+
+1. If not present, create an empty npm project outside of the source tree of
+   Deno. (e.g. `ts`, which will be used in this example).
+2. Install the version of TypeScript you want to update to inside the empty
+   project. (e.g. `npm i typescript@latest`).
+
+   - TypeScript usually updates the `beta` and `rc` release tags as well, but
+     you will want to check that, to make sure you are getting the version you
+     expect.
+
+3. Copy `ts/node_modules/typescript/lib/typescript.js` to
+   `deno/cli/tsc/00_typescript.js`.
+4. Copy `ts/node_modules/typescript/lib/*.d.ts` to `deno/cli/dts/`.
+5. Delete `deno/cli/dts/protocol.d.ts`, `deno/cli/dts/tsserverlibrary.d.ts`,
+   `deno/cli/dts/typescriptServices.d.ts` as they are not included in the CLI in
+   any fashion.
+6. Analyze the diff to `deno/cli/dts`:
+
+   - A lot of the diff will be line termination differences which git will
+     normalize when committed.
+   - Notice any `lib.es*.d.ts` files that have been added. Yearly, TypeScript
+     will usually add the new ES target in the first release post the new year.
+     Also, as standards reach Stage 3, they usually get added to
+     `lib.esnext.*.d.ts` files.
+   - Remove any "dead" lib files. Currently TypeScript includes
+     `lib.esnext.promise.d.ts`, `lib.esnext.string.d.ts`,
+     `lib.esnext.weakref.d.ts` which contain definitions that were ratified and
+     are now included in the other libs and aren't even referenced by
+     `lib.esnext.d.ts` or within the TypeScript compiler. 🤷
+   - Revert/merge any changes to lib files that provide forward support. This is
+     the "hardest" thing, because you need to assess if the updated version of
+     TypeScript now includes the type definitions that we forward support.
+     Currently there are three:
+
+     - `lib.es2021.intl.d.ts` contains additional `Intl` APIs that were ratified
+       and included, but for some reason never added to the TypeScript libs. PR
+       https://github.com/microsoft/TypeScript/pull/47254 has been sitting there
+       for 15 months without being merged for some reason. 🤷 You will likely
+       need to revert the deletion of this code from `lib.es2021.intl.d.ts`.
+     - `lib.esnext.array.d.ts` contains additional array APIs. These likely will
+       be moved to ES2022 at some point, but currently only the
+       `Array.prototype.at` has been added. You will likely need to revert the
+       deletion of the lib from `lib.esnext.d.ts`.
+     - We add `lib.dom.asynciterables.d.ts` because for some reason TypeScript
+       has not built these into the libraries. (See:
+       https://github.com/microsoft/TypeScript/issues/29867)
+
+7. Based on the changes to the lib files, you will need to edit the map of lib
+   names to files in the TypeScript compiler (`deno/cli/tsc/00_typescript.js`).
+   The map is currently named `libEntries` and will look a bit like this:
+
+   ```js
+   var libEntries = [
+     // JavaScript only
+     ["es5", "lib.es5.d.ts"],
+     ["es6", "lib.es2015.d.ts"],
+     ["es2015", "lib.es2015.d.ts"],
+     ["es7", "lib.es2016.d.ts"],
+     // ...
+   ];
+   ```
+
+   You will want to make sure this matches what is on disk. TypeScript often
+   maps `esnext.*` values to the ratified version of them to ensure they are
+   less "breaking" so you will want to make sure, like for `esnext.array` that
+   it points at `lib.esnext.array.d.ts`. You will also want to revert the
+   deletion of `dom.asynciterables`.
+
+8. For any new lib files that were added, but not included in the snapshot (e.g.
+   `lib.es####.full.d.ts`) add them to `STATIC_ASSETS` in `deno/cli/tsc.rs`.
+9. For any new lib files that will be loaded as part of the snapshot, (e.g.
+   `lib.es####.d.ts`) add them to `libs` in `deno/cli/build.rs`.
+10. For any APIs that we might have had forward support for but now are part of
+    the libs, edit `deno/cli/tests/unit/esnext_test.ts` to remove the tests, so
+    we are only testing our modifications.
+11. Do a build and test for the changes. Specifically `esnext_test.ts` should
+    pass and is an indicator that something isn't right.
+12. Commit your changes and submit the PR.
+13. Pat yourself on the back for a job well done.