typescript

TypeScript Standards

Default load: this file only. Pull refs/tooling.md, refs/testing.md, or refs/security.md only when the task explicitly needs that depth.

Priority: P0 — Type Correctness

Type Annotations

• Explicit params and return types on all public declarations. Infer locals.
• Avoid any. Prefer unknown, generics, or a narrowly-scoped escape hatch with a comment when interop forces it.
• Never use the Function type. Use a typed signature: () => void.

Interfaces vs Types

• interface for object shapes that describe APIs — supports declaration merging.
• type for unions, intersections, mapped types, and conditional types.

Strict Mode

• strict: true in tsconfig. On existing repos, migrate incrementally: strictNullChecks → noImplicitAny → strictFunctionTypes. Never flip strict: true in one step.
• Avoid non-null assertion (!). Use narrowing (typeof, instanceof, if-checks) instead.
• ?. and ?? for null safety — use narrowing, not !.

Enums

• Literal unions or as const objects. No runtime enum.

Generics

• Use generics for reusable, type-safe code. Constrain with extends where appropriate.

Type Guards

• Use typeof, instanceof, and predicate functions (x is T) to narrow types.

Utility Types

• Prefer built-ins: Partial, Required, Pick, Omit, Record, Readonly, NonNullable.
• Prefer satisfies for object literals that must conform to a contract without widening the inferred type.

Immutability

• readonly on arrays and object properties. Use as const and satisfies for const assertions.

Discriminated Unions

• Use a stable discriminant such as kind or type to narrow safely. Switch on the discriminant.

type Result<T> = { kind: 'ok'; data: T } | { kind: 'err'; error: Error };

Branded Types

• Use brands only when structurally identical values such as IDs or units are easy to mix up across boundaries.

type UserId = string & { readonly __brand: 'UserId' };
function createUserId(id: string): UserId { return id as UserId; }