tsconfig, and Moving JavaScript Across

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24// This is the real configuration, not an illustration. Every sample in this
// course is checked with exactly these options.
//
// {
//   "compilerOptions": {
//     "strict": true,
//     "target": "es2022",
//     "module": "esnext",
//     "moduleResolution": "bundler",
//     "moduleDetection": "force",
//     "lib": ["es2023", "dom"],
//
//     "noUncheckedIndexedAccess": true,
//     "exactOptionalPropertyTypes": true,
//     "noImplicitOverride": true,
//     "noFallthroughCasesInSwitch": true,
//
//     "skipLibCheck": true
//   }
// }
//
// The first block is the baseline any project should have. The second is the
// four extras worth arguing for. skipLibCheck is a build-speed concession.
export {};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38// strictNullChecks — lesson 08. null and undefined become real types.
function initial(name: string | null): string {
  return name === null ? '?' : name[0]!;
}

// noImplicitAny — lesson 01. Parameters must be annotated.
function double(n: number): number {
  return n * 2;
}

// strictFunctionTypes — lesson 06. Parameters checked contravariantly.
type Handler = (value: string) => void;
const handler: Handler = (value) => console.log(value.length);

// strictPropertyInitialization — class fields must be assigned.
class Account {
  balance: number;
  constructor(initial: number) {
    this.balance = initial;
  }
}

// strictBindCallApply — bind, call and apply are type-checked.
const bound = double.bind(null, 21);

// useUnknownInCatchVariables — lesson 12. A caught value is unknown.
function attempt(): string {
  try {
    throw new Error('x');
  } catch (error) {
    return error instanceof Error ? error.message : 'unknown';
  }
}

// alwaysStrict — the emitted code is in strict mode.
console.log(initial('Ada'), initial(null));
console.log(handler('text') ?? 'void', bound());
console.log(new Account(100).balance, attempt());

1
2
3
4
5
6
7
8
9
10
11
12function describe(n: number): string {
  switch (n) {
    case 1:
      return 'one';
    case 2:
      return 'two';
    default:
      return 'many';
  }
}

console.log(describe(1), describe(2), describe(9));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// This course targets es2022, so all of this survives essentially as written:
// class fields, private fields, optional chaining, nullish coalescing, and
// async/await.
class Counter {
  #count = 0;
  step = 1;

  bump(): number {
    this.#count += this.step;
    return this.#count;
  }
}

async function main(): Promise<string> {
  const counter = new Counter();
  counter.bump();
  counter.bump();
  const label: string | undefined = undefined;
  return `${label ?? 'count'}: ${counter.bump()}`;
}

console.log(await main());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19// This course targets es2022, so all of this survives essentially as written:
// class fields, private fields, optional chaining, nullish coalescing, and
// async/await.
class Counter {
    #count = 0;
    step = 1;
    bump() {
        this.#count += this.step;
        return this.#count;
    }
}
async function main() {
    const counter = new Counter();
    counter.bump();
    counter.bump();
    const label = undefined;
    return `${label ?? 'count'}: ${counter.bump()}`;
}
console.log(await main());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// tsc --noEmit
//   Check everything, write nothing. This is your CI gate and what your
//   editor is doing continuously. The command you will use most.
//
// tsc
//   Check and emit JavaScript. Used when the compiler IS your build, which is
//   typical for a published library.
//
// tsc --watch --noEmit
//   The same check, incremental, on file save. Useful in a second terminal.
//
// Everything else — bundlers, and Node's own type stripping — erases types
// without checking them. That division is deliberate: stripping is fast and
// mechanical, checking is slow and thorough. Do both, at different times.
export {};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16// {
//   "compilerOptions": {
//     "allowJs": true,       // .js files are part of the project
//     "checkJs": false,      // but do not check them yet
//     "strict": true,        // on from the start, for the .ts files you add
//     "target": "es2022",
//     "module": "preserve",
//     "moduleResolution": "bundler",
//     "outDir": "dist"
//   },
//   "include": ["src/**/*"]
// }
//
// At this point `tsc --noEmit` passes trivially, because nothing is checked.
// That is fine — you now have the harness. Commit it.
export {};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20// At the top of a single .js file:
//
//   // @ts-check
//
// The compiler now checks that file with your strict settings, using JSDoc for
// the types it cannot infer:
//
//   /**
//    * @param {string} name
//    * @param {number} [times]
//    * @returns {string}
//    */
//   function repeat(name, times = 1) {
//     return name.repeat(times);
//   }
//
// This is a real intermediate step, not a stunt. You get genuine checking with
// zero renames and no build changes, which means you can do it to one file
// during an afternoon and ship it.
export {};

1
2
3
4
5
6
7
8
9
10
11
12function strict(value: number): string {
  return String(value);
}

// @ts-expect-error passing a string here is deliberate, to show suppression
const wrong = strict('12.5');
console.log('suppressed, and it happens to work at run time:', wrong);

// The important difference: if the error goes away, @ts-expect-error itself
// becomes an error, so it cannot outlive the problem it was suppressing.
// @ts-ignore would silently do nothing forever.
console.log('the suppression is self-cleaning');

1
2
3
4
5
6
7
8
9
10
11
12// Once the codebase is .ts and compiling:
//
//   1. checkJs: true            — for any .js files that remain
//   2. noUncheckedIndexedAccess — expect a burst of errors around arr[i]
//   3. exactOptionalPropertyTypes — expect errors around object spreads
//   4. noImplicitOverride       — mechanical, mostly automated by an editor
//   5. verbatimModuleSyntax     — forces explicit `import type`
//
// One flag per pull request. Each one is a bounded, reviewable change, and if
// one turns out to be too disruptive you can drop it without unpicking the
// others.
export {};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32// For an application built with a bundler or a framework:
//
// {
//   "compilerOptions": {
//     "strict": true,
//     "target": "es2022",
//     "lib": ["es2023", "dom", "dom.iterable"],
//     "module": "preserve",
//     "moduleResolution": "bundler",
//     "moduleDetection": "force",
//     "noEmit": true,
//
//     "noUncheckedIndexedAccess": true,
//     "exactOptionalPropertyTypes": true,
//     "noImplicitOverride": true,
//     "noFallthroughCasesInSwitch": true,
//     "verbatimModuleSyntax": true,
//
//     "skipLibCheck": true,
//     "isolatedModules": true,
//     "resolveJsonModule": true
//   },
//   "include": ["src"]
// }
//
// For code Node runs directly, change module and moduleResolution to
// "nodenext" and write .js extensions in your imports.
//
// For a published library, drop noEmit and add:
//   "declaration": true, "declarationMap": true, "sourceMap": true,
//   "outDir": "dist", "rootDir": "src"
export {};