Typescript Idioms

Core Philosophy

TypeScript's type system is your documentation, your test, and your specification — all at once. Make the type system encode the invariants of your domain so that invalid states are unrepresentable. Lean into the compiler.

Scope: This file covers TypeScript-specific type system and language idioms. For framework-specific patterns, see the respective idiom skill (Vue, React, Angular, Next.js, Hono). For file layout, see references/project-structure.md. For detailed safety, SAST patterns, and performance patterns, see references/ts-patterns-and-anti-patterns.md. For quality commands, see @.agents/rules/code-idioms-and-conventions.md. For logging library, see @.agents/skills/logging-implementation/SKILL.md.

Loading guards:

• Plain JavaScript (no tsconfig.json): load @.agents/skills/javascript-idioms/SKILL.md instead — this skill assumes strict-mode TS.
• Hono backend: hono has no repo-level marker file, so it is not auto-detected. If hono appears in package.json dependencies, co-load @.agents/skills/hono-idioms/SKILL.md alongside this skill.
• Test-file naming diverges by framework: see references/project-structure.md § Test Organization for the reconciliation rule before creating test files.

When to Load References

Load these before writing code in the matching context — not after.

Toolchain and Runtime

• Default to latest Node.js LTS. As of July 2026, Node.js 24 LTS with TypeScript 5.8+
• ESM over CJS for all new projects
• tsx for development execution (replaces ts-node)
• Key version milestones: TS 5.0+ decorators, TS 5.4+ NoInfer, TS 5.5+ inferred type predicates

Strict Mode — Non-Negotiable

All TypeScript projects MUST have strict mode enabled. If a project does not have these settings, fix tsconfig.json before proceeding.

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "useUnknownInCatchVariables": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "forceConsistentCasingInFileNames": true
  }
}

Type System Idioms

1. Use unknown instead of any

   // ❌ any disables type checking
   function processPayload(payload: any) {
     console.log(payload.id); // No error if id doesn't exist
   }
   
   // ✅ unknown forces narrowing
   function processPayload(payload: unknown) {
     if (typeof payload === 'object' && payload !== null && 'id' in payload) {
       console.log(payload.id);
     }
   }

2. Discriminated Unions for state machines

   // ❌ Optional properties lead to impossible states
   type State = {
     status: 'loading' | 'success' | 'error';
     data?: string;
     error?: Error;
   };
   
   // ✅ Discriminated union makes impossible states unrepresentable
   type State = 
     | { status: 'loading' }
     | { status: 'success'; data: string }
     | { status: 'error'; error: Error };

3. Type narrowing with in and typeof

   function handle(val: string | number) {
     if (typeof val === 'string') {
       // val is string
     }
   }

4. Satisfies operator for checking without widening

   type Colors = 'red' | 'green' | 'blue';
   type RGB = [number, number, number];
   
   // ❌ Record widens the specific keys
   const palette1: Record<Colors, RGB> = { red: [255, 0, 0], green: [0, 255, 0], blue: [0, 0, 255] };
   
   // ✅ satisfies keeps exact type
   const palette2 = { red: [255, 0, 0], green: [0, 255, 0], blue: [0, 0, 255] } satisfies Record<Colors, RGB>;

5. readonly everywhere

   // ❌ Mutable arrays
   function sum(numbers: number[]): number { ... }
   
   // ✅ Readonly arrays
   function sum(numbers: readonly number[]): number { ... }

6. Opaque/Nominal typing for domain primitives

   type UserId = string & { readonly __brand: 'UserId' };
   type OrderId = string & { readonly __brand: 'OrderId' };
   
   function getUser(id: UserId): User { ... }
   
   // ❌ Compile error — OrderId is not assignable to UserId
   getUser(orderId);
   
   // ✅ Explicit creation
   const userId = 'u-123' as UserId;
   getUser(userId);

7. Template literal types for string patterns

   type EventName = `on${Capitalize<string>}`;
   type Route = `/${string}`;

8. NoInfer<T> to prevent unwanted inference (TS 5.4+)

   function createFSM<S extends string>(initial: S, transitions: Record<S, NoInfer<S>[]>) { ... }

Null Safety

1. Enable strictNullChecks (always).
2. Optional Chaining (?.) over explicit checks

   // ❌ Verbose
   const city = user && user.address && user.address.city;
   
   // ✅ Concise
   const city = user?.address?.city;

3. Nullish Coalescing (??) over Logical OR (||)

   // ❌ Fails on 0 or ''
   const count = input.count || 10;
   
   // ✅ Only falls back on null/undefined
   const count = input.count ?? 10;

4. Explicit Resource Management (using declarations — TypeScript 5.2+) Requires lib: ["es2022"] or higher in tsconfig.json. Available in all Node.js 24 LTS projects.

   // ✅ Automatic cleanup — resource disposed when scope exits
   {
     using file = await openFile('data.csv');
     // file is automatically closed when block exits, even on throw
   }

Error Handling

1. Always throw Error instances, never primitives

   // ❌ Loses stack trace, breaks instanceof checks
   throw 'Something went wrong';
   throw { message: 'fail' };
   
   // ✅ Proper error with stack trace
   throw new Error('Something went wrong');

2. Custom error classes for domain errors

   export class NotFoundError extends Error {
     constructor(public readonly resource: string, public readonly id: string) {
       super(`${resource} not found: ${id}`);
       this.name = 'NotFoundError';
     }
   }

3. Type-safe error narrowing

   try {
     await api.createUser(data);
   } catch (err) {
     // ❌ unsafe — err is unknown
     console.log(err.message);
     
     // ✅ narrowed
     if (err instanceof NotFoundError) {
       console.log(err.resource, err.id);
     } else if (err instanceof Error) {
       console.log(err.message);
     }
   }

4. Exhaustive error handling with Result<T, E> discriminated union

   Use this when you want to make errors part of the return type (no throw/catch required).

   // Define once, reuse everywhere
   type Ok<T> = { ok: true; value: T };
   type Err<E> = { ok: false; error: E };
   type Result<T, E> = Ok<T> | Err<E>;
   
   // Helper constructors eliminate boilerplate
   const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
   const err = <E>(error: E): Err<E> => ({ ok: false, error });
   
   // Usage — no try/catch, caller is forced to handle the error case
   function divide(a: number, b: number): Result<number, string> {
     if (b === 0) return err('Division by zero');
     return ok(a / b);
   }
   
   const result = divide(10, 0);
   if (!result.ok) {
     console.error(result.error); // 'Division by zero'
   } else {
     console.log(result.value);   // number
   }

Async/Await

1. Always use async/await over raw Promises.

2. Use Promise.all for parallel operations.

   // ❌ Sequential
   const users = await getUsers();
   const posts = await getPosts();
   
   // ✅ Parallel
   const [users, posts] = await Promise.all([getUsers(), getPosts()]);

3. Use Promise.allSettled when some can fail.

4. Avoid .then().catch() chains.

5. Abort long-running operations with AbortController

   const controller = new AbortController();
   const response = await fetch(url, { signal: controller.signal });
   // Cancel if needed
   controller.abort();

6. Never use async callbacks in Array.forEach

   // ❌ forEach ignores returned promises — operations run detached
   items.forEach(async (item) => {
     await process(item);
   });
   
   // ✅ Use for...of for sequential
   for (const item of items) {
     await process(item);
   }
   
   // ✅ Use Promise.all for concurrent
   await Promise.all(items.map(item => process(item)));

7. Handle timeouts with AbortSignal.timeout()

   const response = await fetch(url, {
     signal: AbortSignal.timeout(5000),
   });

Runtime Validation at Boundaries

TypeScript types do not exist at runtime. Any data crossing an I/O boundary must be validated.

1. Use Zod for all schema validation.

   import { z } from 'zod';
   
   const UserSchema = z.object({
     id: z.string().uuid(),
     name: z.string().min(2),
     age: z.number().int().nonnegative(),
   });
   
   type User = z.infer<typeof UserSchema>;
   
   function parseUser(data: unknown): User {
     return UserSchema.parse(data);
   }

For advanced Zod patterns (transforms, discriminated unions, branded types, error formatting), see references/zod-patterns.md.

Iteration and Collections

1. Use Map/Set over plain objects for dynamic keys

   // ❌ Plain objects as maps — prototype pollution risk, string-only keys
   const cache: Record<string, User> = {};
   
   // ✅ Map — any key type, no prototype chain, O(1) has/get/set
   const cache = new Map<string, User>();

2. Use structuredClone() for deep copies (not JSON round-trip)

   // ❌ Lossy — drops undefined, functions, Date objects, BigInt
   const copy = JSON.parse(JSON.stringify(original));
   
   // ✅ Handles circular refs, Date, RegExp, Map, Set, ArrayBuffer
   const copy = structuredClone(original);

3. Prefer immutable array methods (ES2023+)

   // ❌ Mutates original array
   const sorted = arr.sort((a, b) => a - b);
   const reversed = arr.reverse();
   
   // ✅ Returns new array, original unchanged
   const sorted = arr.toSorted((a, b) => a - b);
   const reversed = arr.toReversed();
   const withReplacement = arr.with(2, 'new');

4. Use Object.groupBy() for grouping (ES2024)

5. Use Set for O(1) lookups instead of Array.includes in loops

Centralized HTTP Client

Never use raw fetch spread throughout the codebase. Centralize it to handle tokens, retries, and errors.

Testability requirement: Always define an interface first. The concrete class implements it. This lets tests inject a FakeHttpClient without network calls.

// ✅ Define interface first — enables test doubles (architectural rule: I/O isolation)
export interface HttpClient {
  get<T>(path: string, schema: z.ZodType<T>): Promise<T>;
  post<T>(path: string, body: unknown, schema: z.ZodType<T>): Promise<T>;
  delete(path: string): Promise<void>;
}

// ✅ Production implementation
export class ApiClient implements HttpClient {
  constructor(private readonly baseUrl: string) {}

  async get<T>(path: string, schema: z.ZodType<T>): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      signal: AbortSignal.timeout(10_000),
    });
    if (!res.ok) throw new ApiError(res.status, res.statusText);
    const data: unknown = await res.json();
    return schema.parse(data);
  }

  async post<T>(path: string, body: unknown, schema: z.ZodType<T>): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(10_000),
    });
    if (!res.ok) throw new ApiError(res.status, res.statusText);
    const data: unknown = await res.json();
    return schema.parse(data);
  }

  async delete(path: string): Promise<void> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      method: 'DELETE',
      signal: AbortSignal.timeout(10_000),
    });
    if (!res.ok) throw new ApiError(res.status, res.statusText);
  }
}

// ✅ Test double — use in unit tests, no network required
export class FakeHttpClient implements HttpClient {
  readonly calls: { method: string; path: string }[] = [];
  private responses = new Map<string, unknown>();

  enqueue(path: string, response: unknown): void {
    this.responses.set(path, response);
  }

  async get<T>(path: string, schema: z.ZodType<T>): Promise<T> {
    this.calls.push({ method: 'GET', path });
    return schema.parse(this.responses.get(path));
  }

  async post<T>(path: string, body: unknown, schema: z.ZodType<T>): Promise<T> {
    this.calls.push({ method: 'POST', path });
    return schema.parse(this.responses.get(path));
  }

  async delete(path: string): Promise<void> {
    this.calls.push({ method: 'DELETE', path });
  }
}

Idiomatic Patterns

1. Parameter object over positional arguments

   // ❌ Positional — error-prone, order-sensitive, boolean traps
   function createUser(name: string, email: string, isAdmin: boolean, isActive: boolean) {}
   
   // ✅ Named parameters — self-documenting, order-independent
   interface CreateUserParams {
     name: string;
     email: string;
     isAdmin: boolean;
     isActive: boolean;
   }
   function createUser(params: CreateUserParams) {}

2. Branded/Opaque types for domain primitives — see Type System Idioms §6. Never pass bare string or number for domain IDs.

3. Discriminated unions over inheritance — prefer union types with a type or kind discriminant over class hierarchies. Invalid states become compile errors.

4. Parse, don't validate — convert raw input into typed, validated domain objects at the boundary. Downstream code works with the typed form and never re-validates.

   // ❌ Validate at every call site
   function processOrder(orderId: string) {
     if (!isValidUuid(orderId)) throw new Error('Invalid');
     // ...
   }
   
   // ✅ Parse at boundary, use branded type everywhere else
   const orderId = OrderIdSchema.parse(rawInput); // throws once at entry
   processOrder(orderId); // OrderId is always valid

5. Early returns to reduce nesting — use guard clauses instead of nested if/else.

   // ❌ Deep nesting
   function handle(req: Request) {
     if (req.auth) {
       if (req.auth.isValid) {
         if (req.body) {
           return process(req.body);
         }
       }
     }
   }
   
   // ✅ Guard clauses
   function handle(req: Request) {
     if (!req.auth) return unauthorized();
     if (!req.auth.isValid) return forbidden();
     if (!req.body) return badRequest();
     return process(req.body);
   }

6. Keep function complexity low (cyclomatic complexity < 10)

   • Functions exceeding this threshold must be decomposed
   • Common signal: if explaining what a function does requires the word "and", split it