Typescript Helper

TypeScript Helper

Use TypeScript to make program contracts explicit, then validate data where static types end. Choose compiler and module settings from the actual runtime or bundler instead of applying one universal configuration.

Current status

Verified 2026-08-03.

TypeScript reports typical 8–12x full-build improvements for the native 7.0 compiler. Treat that as an official benchmark range, not a universal guarantee. The experimental --checkers and --builders controls trade memory for concurrency; do not make them default without measuring the project.

Always inspect the selected toolchain. A bare tsc on PATH can resolve to the 6.x compatibility bridge even when a package also has the native compiler installed; run from the package that declares @typescript/native, then use the explicit native-compiler path when both are present. This matters with isolated workspace linkers because the repository root may not own the package's compiler dependency. This monorepo's scripts/checks/compliance-check.ts enforces the same PATH=node_modules/@typescript/native/bin:$PATH tsc form:

cd packages/<package-that-declares-typescript-native>
PATH=node_modules/@typescript/native/bin:$PATH tsc --version
PATH=node_modules/@typescript/native/bin:$PATH tsc --showConfig

Read references/releases-and-migration.md before a TypeScript 6 or 7 upgrade. Read references/configuration.md when creating or reviewing a tsconfig. Read references/modules-and-runtimes.md for Node, Bun, bundler, ESM, and CommonJS decisions. Read references/type-safety.md for narrowing, generics, validation, and exhaustiveness. Read references/tooling.md for ESLint and execution tooling.

Project-safe commands

Type-check through the project configuration or build graph:

cd packages/<package-that-declares-typescript-native>
PATH=node_modules/@typescript/native/bin:$PATH tsc -p tsconfig.json --noEmit
PATH=node_modules/@typescript/native/bin:$PATH tsc -b

Passing source filenames to tsc bypasses project configuration historically. TypeScript 7 errors when a config is present unless that bypass is made explicit with --ignoreConfig. Do not use tsc file.ts as the normal project check.

In this monorepo, prefer its focused Turbo task over invoking a different compiler configuration:

bunx turbo run typecheck --filter=<package>

Model the runtime

Do not rank Node, Bun, tsx, or ts-node as universally fastest. Select based on runtime semantics, transformation support, type-checking needs, and repository conventions.

Strict baseline

Start with strict; add checks that reflect the project's boundary and indexing risks. The exact set enabled by strict can grow between releases.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedSideEffectImports": true,
    "types": []
  }
}

• noUncheckedIndexedAccess adds undefined to undeclared index-signature lookups.
• exactOptionalPropertyTypes distinguishes absence from a present undefined value.
• An explicit types list prevents accidental global-type inclusion and is required during the TypeScript 7 migration because 7.0 defaults it to [].
• skipLibCheck is a deliberate compatibility and performance trade-off, not a correctness baseline. Do not use it to hide an upgrade failure.

Validate external data

Static annotations do not validate JSON, environment variables, HTTP bodies, database rows, cache values, or deserialized files. Keep these values unknown until parsed.

import { z } from "zod";

const User = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
});

type User = z.infer<typeof User>;

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${encodeURIComponent(id)}`);
  if (!response.ok) {
    throw new Error(`User request failed: ${response.status}`);
  }
  return User.parse(await response.json());
}

Do not assign response.json() directly to a domain type. Do not use a type assertion to manufacture a branded ID; validate and construct it through a schema or omit the brand.

Narrow instead of asserting

Use control-flow checks, discriminants, typeof, instanceof, Array.isArray, property checks, or a runtime schema. Avoid non-null assertions and unchecked casts.

type State =
  | { kind: "idle" }
  | { kind: "loading" }
  | { kind: "loaded"; count: number }
  | { kind: "failed"; message: string };

function describe(state: State): string {
  switch (state.kind) {
    case "idle":
      return "Idle";
    case "loading":
      return "Loading";
    case "loaded":
      return `${state.count} records`;
    case "failed":
      return state.message;
    default:
      return assertNever(state);
  }
}

function assertNever(value: never): never {
  throw new Error(`Unhandled state: ${JSON.stringify(value)}`);
}

A reducer that returns the old state from a default branch hides newly added actions. Exhaustive never handling makes the missing case fail during checking.