docs: information about updating TypeScript version (denoland#13810)

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.