Typescript Core

TypeScript Core Patterns

Modern TypeScript development patterns for type safety, runtime validation, and optimal configuration.

Quick Start

New Project: Use 2025 tsconfig → Enable strict + noUncheckedIndexedAccess → Choose Zod for validation

Existing Project: Enable strict: false initially → Fix any with unknown → Add noUncheckedIndexedAccess

API Development: Zod schemas at boundaries → z.infer<typeof Schema> for types → satisfies for routes

Library Development: Enable declaration: true → Use const type parameters → See advanced-patterns-2025.md

Quick Reference

tsconfig.json 2025 Baseline

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true
  }
}

Key Compiler Options

Local Baselines

See references/configuration.md for repo-specific tsconfig patterns (CommonJS CLI, NodeNext strict, Next.js bundler).

Core Type Patterns

Const Type Parameters

Preserve literal types through generic functions:

function createConfig<const T extends Record<string, unknown>>(config: T): T {
  return config;
}

const config = createConfig({ 
  apiUrl: "https://api.example.com", 
  timeout: 5000 
});
// Type: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000 }

Satisfies Operator

Validate against a type while preserving literal inference:

type Route = { path: string; children?: Routes };
type Routes = Record<string, Route>;

const routes = {
  AUTH: { path: "/auth" },
  HOME: { path: "/" }
} satisfies Routes;

routes.AUTH.path;     // Type: "/auth" (literal preserved)
routes.NONEXISTENT;   // ❌ Type error

Template Literal Types

Type-safe string manipulation and route extraction:

type ExtractParams<T extends string> = 
  T extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<Rest>
    : T extends `${string}:${infer Param}`
      ? Param
      : never;

type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"

Discriminated Unions with Exhaustiveness

type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function handleResult<T>(result: Result<T>): T {
  if (result.success) return result.data;
  throw result.error;
}

// Exhaustiveness checking
type Action = 
  | { type: 'create'; payload: string }
  | { type: 'delete'; id: number };

function handle(action: Action) {
  switch (action.type) {
    case 'create': return action.payload;
    case 'delete': return action.id;
    default: {
      const _exhaustive: never = action;
      throw new Error(`Unhandled: ${_exhaustive}`);
    }
  }
}

Runtime Validation

TypeScript types disappear at runtime. Use validation libraries for external data (APIs, forms, config files).

Quick Comparison

Basic Pattern (Zod)

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});

type User = z.infer<typeof UserSchema>;

// Validate external data
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

→ See [runtime-validation.md](./references/runtime-validation.md) for complete Zod, TypeBox, and Valibot patterns

Decision Support

Quick Decision Guide

Need to choose between `type` vs `interface`?

• Public API / library types → interface
• Union types / mapped types → type
• Simple object shapes → interface (default)

Need generics or union types?

• Output type depends on input type → Generics
• Fixed set of known types → Union types
• Building reusable data structures → Generics

Dealing with unknown data?

• External data (API, user input) → unknown (type-safe)
• Rapid prototyping / migration → any (temporarily)

Need runtime validation?

• Full-stack TypeScript with tRPC → Zod
• OpenAPI / high performance → TypeBox
• Edge functions / minimal bundle → Valibot

→ See [decision-trees.md](./references/decision-trees.md) for comprehensive decision frameworks

Troubleshooting

Common Issues Quick Reference

Property does not exist on type → Define proper interface or use optional properties

Type is not assignable → Fix property types or use runtime validation (Zod)

Object is possibly 'undefined' → Use optional chaining (?.) or type guards

Cannot find module → Check file extensions (.js for ESM) and module resolution

Slow compilation → Enable incremental, use skipLibCheck, consider esbuild/swc

→ See [troubleshooting.md](./references/troubleshooting.md) for detailed solutions with examples

Navigation

Detailed References

• [📐 Advanced Types](./references/advanced-types.md) - Conditional types, mapped types, infer keyword, recursive types. Load when building complex type utilities or generic libraries.

• [⚙️ Configuration](./references/configuration.md) - Complete tsconfig.json guide, project references, monorepo patterns. Load when setting up new projects or optimizing builds.

• [🔒 Runtime Validation](./references/runtime-validation.md) - Zod, TypeBox, Valibot deep patterns, error handling, integration strategies. Load when implementing API validation or form handling.

• [✨ Advanced Patterns 2025](./references/advanced-patterns-2025.md) - TypeScript 5.2+ features: using keyword, stable decorators, import type behavior, satisfies with generics. Load when using modern language features.

• [🌳 Decision Trees](./references/decision-trees.md) - Clear decision frameworks for type vs interface, generics vs unions, unknown vs any, validation library selection, type narrowing strategies, and module resolution. Load when making TypeScript design decisions.

• [🔧 Troubleshooting](./references/troubleshooting.md) - Common TypeScript errors and fixes, type inference issues, module resolution problems, tsconfig misconfigurations, build performance optimization, and type compatibility errors. Load when debugging TypeScript issues.

JavaScript / Runtime Quality Anti-Patterns

The type system catches type errors, but a class of JavaScript defects is runtime/AST- level and survives into emitted JS and plain-JS files. Watch for:

• Loose equality (==/!=) — coercion bugs and auth flaws; use ===/!== (accept == null only when commented as "null or undefined").
• Dynamic code execution (eval, new Function(str), string setTimeout) — injection risk and unnecessary; use direct syntax.
• Mutating builtins (Object/Array/Function.prototype) — pollutes for…in, breaks the whole runtime; extend or use free functions instead.
• Variable shadowing, `var` instead of `let`/`const`, using functions before declaration — readability and "wrong variable" bugs.