/typescript

name: typescript
description: Use when writing or hardening TypeScript in strict mode. Covers advanced types, discriminated unions, runtime validation at trust boundaries, generics, and removing `any` from an existing codebase. Trigger on "get rid of all the any types", "turn on strict mode in tsconfig", "type inference is failing on this generic", "validate this api response at runtime". Do not use for React component and hook design — see the react skill.
metadata:
  category: languages
  version: 1.0.0
  tags: [typescript, types, strict, zod, generics]

TypeScript

Purpose

Use the type system to make invalid states unrepresentable. This skill covers strict-mode TypeScript, the advanced type features worth reaching for, and the discipline of validating untrusted data exactly once — at the boundary.

When to Use

• Starting a TypeScript project or tightening `tsconfig.json`.
• Removing `any` and unchecked casts from an existing codebase.
• Modeling a domain with discriminated unions and exhaustive matching.
• Writing a typed API client or SDK.
• Debugging inference failures in generic code.

Capabilities

• Strict compiler configuration and incremental adoption paths.
• Discriminated unions, template literal types, conditional and mapped types.
• Generic constraints, inference control, and `satisfies`.
• Runtime schema validation with Zod, wired to inferred static types.
• Type-safe error handling with `Result`-style unions.

Inputs

• Source files and the current `tsconfig.json`.
• Runtime target (Node, browser, edge, Deno, Bun).
• External data shapes: API responses, environment variables, user input.

Outputs

• Source that compiles under `strict: true` with zero `any`.
• Schemas for every trust boundary, with static types derived from them.
• A `tsconfig.json` reflecting the target runtime.

Workflow

1. **Set the gate** — Enable `strict`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes`. Everything else follows from the compiler's complaints. 2. **Type the boundaries** — Define schemas for every input that crosses into your program: HTTP payloads, env vars, config files, message queues. 3. **Model the domain** — Replace boolean flags and optional grab-bags with discriminated unions. 4. **Implement inward** — Internal code trusts its types because the boundary already validated them. 5. **Verify** — `tsc --noEmit` and lint with `@typescript-eslint`, `no-explicit-any` set to error.

Best Practices

• Never use `as` to silence the compiler. It is an assertion, not a check; it lies at runtime.
• Prefer `unknown` over `any` at every boundary, then narrow.
• Derive types from schemas (`z.infer`), never maintain both by hand.
• Use `satisfies` to validate an object literal against a type while preserving its narrow inferred type.
• Add an exhaustiveness check (`never`) to every union switch — it turns a future missing case into a compile error.
• Do not export types you do not intend to support. A public type is an API contract.

Examples

**Boundary validation with derived types:**

import { z } from "zod";

const Config = z.object({
  port: z.coerce.number().int().positive(),
  databaseUrl: z.string().url(),
  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

export type Config = z.infer<typeof Config>;

export function loadConfig(env: NodeJS.ProcessEnv): Config {
  const parsed = Config.safeParse({
    port: env.PORT,
    databaseUrl: env.DATABASE_URL,
    logLevel: env.LOG_LEVEL,
  });
  if (!parsed.success) {
    throw new Error(`Invalid configuration:\n${parsed.error.message}`);
  }
  return parsed.data;
}

**Exhaustive discriminated union:**

type Job =
  | { status: "queued"; queuedAt: Date }
  | { status: "running"; startedAt: Date; workerId: string }
  | { status: "failed"; error: string; attempts: number };

function describe(job: Job): string {
  switch (job.status) {
    case "queued":
      return `Queued at ${job.queuedAt.toISOString()}`;
    case "running":
      return `Running on ${job.workerId}`;
    case "failed":
      return `Failed after ${job.attempts} attempts: ${job.error}`;
    default: {
      const unreachable: never = job;
      throw new Error(`Unhandled job status: ${JSON.stringify(unreachable)}`);
    }
  }
}

Notes

• `noUncheckedIndexedAccess` is the single highest-value flag most codebases are missing: it makes `arr[i]` return `T | undefined`, which is the truth.
• Declaration files (`.d.ts`) from `DefinitelyTyped` are frequently wrong. Verify against runtime behavior before trusting them.
• Type-level programming is a cost. If a conditional type takes more than a minute to read, prefer a simpler runtime check.