The TypeScript type system and where it stops

HOW IT FITS TOGETHER

KEY TERMS

Structural typing

Compatibility is decided by members, not by declared names: any value with the required properties fits, extra properties included. Fresh object literals get an extra excess-property check, which is why the same object passes as a variable and fails inline. Use branded types when two structurally identical types (UserId, OrderId) must not mix.

Type erasure

Types have no runtime existence. You cannot ask whether a value is a User at runtime, generics do not exist in the output, and `as` is an unchecked assertion, not a conversion. Runtime checks must be written in JavaScript, which is why schema libraries derive the static type from a runtime validator (z.infer) rather than the other way around.

Narrowing and discriminated unions

Control-flow analysis refines a type after typeof, instanceof, in, equality checks, truthiness, type predicates and assertion functions. A union of object types sharing a literal tag (status: "pending" | "failed") narrows on that tag, so each branch sees only valid fields, and assigning the leftover to never makes a missing case a compile error.

Generics and constraints

Type parameters relate inputs to outputs (T in, T out) instead of collapsing to unknown. extends constrains what T may be (T extends { id: string }, K extends keyof T), and inference fills them in from arguments. If a type parameter appears only once, it is usually unnecessary.

unknown vs any

Both accept every value. any also lets you do anything with it and can be assigned to everything, so one any silently disables checks downstream. unknown forces a narrowing step before use. Type untrusted data and catch-clause errors as unknown (useUnknownInCatchVariables is part of strict).

satisfies vs annotation

const x: T = value checks the value and then forgets it, giving x the declared type T. value satisfies T checks the same thing but keeps the inferred, narrower type (literal keys, specific members), so you get both the error and the autocomplete.

Utility, mapped and conditional types

Mapped types transform each key of a type (Partial, Readonly, Record, Pick, Omit are mapped types). Conditional types choose a type by a test (T extends string ? A : B) and with infer extract parts (ReturnType, Awaited). Use them to derive types from one source of truth; keep them out of hot paths of everyday code, since deep type-level programs are hard to read and slow to check.

IN YOUR STACK

type PaymentState =
  | { status: "idle" }
  | { status: "pending"; startedAt: number }
  | { status: "succeeded"; receiptId: string }
  | { status: "failed"; error: string; retryable: boolean };

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

function buttonLabel(state: PaymentState): string {
  switch (state.status) {
    case "idle":
      return "Pay now";
    case "pending":
      return `Processing since ${new Date(state.startedAt).toLocaleTimeString()}`;
    case "succeeded":
      return `Paid, receipt ${state.receiptId}`; // receiptId exists only here
    case "failed":
      return state.retryable ? `Retry: ${state.error}` : state.error;
    default:
      return assertNever(state); // adding a status without a case fails to compile
  }
}

import { z } from "zod";

const Order = z.object({
  id: z.uuid(),
  email: z.email(),
  totalCents: z.number().int().nonnegative(),
  status: z.enum(["open", "paid", "refunded"]),
  createdAt: z.iso.datetime(),
});
export type Order = z.infer<typeof Order>; // the type is derived from the check

export async function fetchOrder(id: string): Promise<Order> {
  const res = await fetch(`https://api.example.com/orders/${encodeURIComponent(id)}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const body: unknown = await res.json(); // json() returns any; refuse to trust it
  const result = Order.safeParse(body);
  if (!result.success) {
    throw new Error(`Invalid order payload:\n${z.prettifyError(result.error)}`);
  }
  return result.data; // typed, and actually checked
}

// K is tied to T, so the result is T[K][] rather than unknown[]
function pluck<T, K extends keyof T>(items: readonly T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

// Constraint on shape: anything with a string id, structurally
function indexById<T extends { id: string }>(items: readonly T[]): Map<string, T> {
  return new Map(items.map((item) => [item.id, item]));
}

type User = { id: string; name: string; age: number };
const users: User[] = [{ id: "u1", name: "Ada", age: 36 }];

const names = pluck(users, "name"); // string[]
const ages = pluck(users, "age");   // number[]
const byId = indexById(users);      // Map<string, User>, the full type survives
// pluck(users, "email");           // error: not "id" | "name" | "age"

// const type parameter: infer literal types without as const at the call site
function defineRoles<const R extends readonly string[]>(roles: R): R {
  return roles;
}
const roles = defineRoles(["admin", "editor"]); // readonly ["admin", "editor"]
type Role = (typeof roles)[number];             // "admin" | "editor"

type Route = { path: `/${string}`; auth: boolean };

// Annotation: checked, then widened to the declared type
const annotated: Record<string, Route> = {
  home: { path: "/", auth: false },
  settings: { path: "/settings", auth: true },
};
annotated.setings; // no error: any string key is allowed by the annotation

// satisfies: same check, but the inferred type is kept
const routes = {
  home: { path: "/", auth: false },
  settings: { path: "/settings", auth: true },
  // admin: { path: "admin", auth: true }, // error: path must start with "/"
} satisfies Record<string, Route>;

// routes.setings;                   // error: property does not exist
type RouteName = keyof typeof routes; // "home" | "settings"

// Combine with as const to keep literal values as well as keys
const flags = { beta: true, rollout: 0.25 } as const satisfies Record<string, boolean | number>;
type Flags = typeof flags; // { readonly beta: true; readonly rollout: 0.25 }

declare const brand: unique symbol;
type Brand<T, B extends string> = T & { readonly [brand]: B };

type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
type Cents = Brand<number, "Cents">;
// The only way in is a function that checks; the brand costs nothing at runtime
function toUserId(raw: string): UserId {
  if (!/^usr_[a-z0-9]{12}$/.test(raw)) throw new Error(`Invalid user id: ${raw}`);
  return raw as UserId;
}
function toOrderId(raw: string): OrderId {
  if (!raw.startsWith("ord_")) throw new Error(`Invalid order id: ${raw}`);
  return raw as OrderId;
}
function toCents(amount: number): Cents {
  if (!Number.isSafeInteger(amount)) throw new Error("Cents must be an integer");
  return amount as Cents;
}

function refund(user: UserId, order: OrderId, amount: Cents): void { /* ... */ }
refund(toUserId("usr_abc123def456"), toOrderId("ord_1"), toCents(1999)); // OK
// refund(toOrderId("ord_1"), toUserId("usr_abc123def456"), toCents(1999)); // error
// refund(userId, orderId, 19.99); // error: number is not Cents

// tsconfig.json for code Node runs directly: node src/server.ts
{
  "compilerOptions": {
    "noEmit": true,                         // tsc only checks; Node strips at runtime
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true, // imports keep their .ts extension
    "erasableSyntaxOnly": true,             // reject enum, namespaces, parameter properties
    "verbatimModuleSyntax": true,           // type-only imports must say import type
    "types": ["node"],                      // TS 6+ no longer loads every @types package
    "strict": true,                         // default since TS 6; keep it explicit
    "noUncheckedIndexedAccess": true,       // arr[i] and record[key] may be undefined
    "exactOptionalPropertyTypes": true,     // x?: T does not accept an explicit undefined
    "noImplicitOverride": true,
    "skipLibCheck": true
  }
}

WHERE IT BITES

• Casting at the boundary: res.json() as User, JSON.parse(x) as Config, or a generic fetch<T>() that never validates. The types say safe; production data disagrees later and far away.
• Letting any leak in through untyped libraries, JSON.parse or catch (e) in older configs. One any flows through assignments and switches off checks everywhere it reaches; turn on noImplicitAny and lint against explicit any.
• Expecting types at runtime: checking value instanceof SomeInterface, relying on a generic parameter inside the function body, or assuming an enum exists in stripped code (Node's type stripping rejects enums).
• Optional-field soup instead of unions: { loading?: boolean; data?: T; error?: E } allows loading with data and error at once. Model states as a discriminated union.
• Running only a type stripper (Node, Bun, esbuild, Vite) and assuming the code was type-checked. Stripping succeeds on code full of type errors.
• Assuming arr[i] or record[key] is defined. Without noUncheckedIndexedAccess the type omits undefined, which is the most common source of 'cannot read properties of undefined' in typed code.

SOURCES

• TypeScript handbook: Narrowing (opens in new tab)Checked 2026-10-11
• TypeScript handbook: Type compatibility (opens in new tab)Checked 2026-10-11
• TypeScript 5.8 release notes: --erasableSyntaxOnly (opens in new tab)Checked 2026-10-11
• Announcing TypeScript 7.0 (opens in new tab)Checked 2026-10-11
• Node.js: Modules: TypeScript (opens in new tab)Checked 2026-10-11
• Zod: Basic usage (opens in new tab)Checked 2026-10-11