|
3 | 3 | "compilerOptions": { |
4 | 4 | "rootDir": "src/", |
5 | 5 | "target": "es6", |
| 6 | + |
| 7 | + // What we would IDEALLY like to do is compile against type declarations corresponding to |
| 8 | + // precisely what is available in BOTH the "Widely Available" Baseline |
| 9 | + // (https://web.dev/baseline) AND the latest Node.js LTS, since jsdiff supports both. |
| 10 | + // Alas, there is no way to do this. As of configuring the settings below (7th |
| 11 | + // April 2026)... |
| 12 | + // 1. there is simply no way to tell TypeScript to use the intersection of two sets of |
| 13 | + // global type declarations (i.e. to only let us use stuff supported by both |
| 14 | + // environments). At best, we can minimise how many global type declarations we include |
| 15 | + // by keeping the "lib" and "types" arrays below minimal, and ideally avoiding including |
| 16 | + // anything in them that is either browser-specific or Node-specific. |
| 17 | + // 2. jsdiff actually uses some stuff that is both "Widely Available" and available in Node, |
| 18 | + // but not part of *any* ECMAScript spec. These include `TextDecoder`, which has its own |
| 19 | + // dedicated spec, and `setTimeout`, which is (weirdly!) part of the HTML standard, not |
| 20 | + // the ECMAScript spec (although Node has its own, identical-ish implementation). |
| 21 | + // Consequently setting `"lib": ["esnext"]` will not suffice to let jsdiff compile; to |
| 22 | + // get to a tsconfig that actually works, we MUST include "dom" in the "lib" array |
| 23 | + // and/or use the @types/node type declaration module by including "node" in the |
| 24 | + // "types" array. |
| 25 | + // Obviously, both available solutions to point 2 above are unsatisfactory, due to point 1. |
| 26 | + // If we include "dom" in the "lib" array, then if we use browser-specific features in our |
| 27 | + // TypeScript code (that won't work in Node), TypeScript will not warn us about it at |
| 28 | + // compilation time. If we instead use `types: ["node"]`, the converse problem will exist. |
| 29 | + // |
| 30 | + // Faced with two unsatisfactory options, we reluctantly choose one. But it means we |
| 31 | + // absolutely cannot rely on TypeScript to catch if we use a global that isn't actually |
| 32 | + // available in all our supported environments, and so must rely on tests and vigilance. |
6 | 33 | "lib": [ |
7 | | - "es2022" |
| 34 | + "es2023", "dom" |
8 | 35 | ], |
| 36 | + "types": [], |
| 37 | + |
9 | 38 | "declaration": true, |
10 | 39 | "skipLibCheck": true, |
11 | 40 |
|
|
0 commit comments