typescript-guide

TypeScript Coding Guidelines

Write strict TypeScript modules with explicit types, direct imports, and checked errors.

Requirements

• Node.js ESM, TypeScript ≥ 5.8, Vitest ≥ 3, Zod ≥ 4.

Essentials

• Strict mode - Enable strict flags, avoid @ts-ignore without comment+issue
• Type safety - Explicit public types, unknown over any, derive from generated types
• Imports - Use import type for type-only imports
• Async/await - Handle errors explicitly, only use async with await, see references/async-without-await.md, references/unnecessary-async-keywords.md
• Immutability - Use const/readonly where possible
• Validation - Zod for I/O boundaries, infer types from schemas
• Linting - Never suppress with eslint-disable, fix root causes, see references/avoid-eslint-disable.md
• Template literals - Convert numbers with String(value), see references/template-literals-require-string-conversion.md
• Numeric literals - Use underscores in large numbers (30_000), see references/numeric-separator-enforcement.md
• Method references - Keep object references to maintain this binding, see references/unbound-method-references.md
• Environment - Use dot notation for process.env access, see references/env-access-bracket-notation.md
• Paradigm - Functional style → fp-guide; class/OO design → oop-guide

Gotchas

• Structural typing means { a: string } accepts { a: string, b: number } silently: explicit satisfies is the way to catch unintended extras
• as casts bypass the type system without check: prefer narrowing functions (type predicates) over casts
• type vs interface: interfaces merge across declarations, types don't. declare global { interface Window { ... } } works, type Window = ... doesn't
• unknown is the safer any, but it doesn't propagate; narrowing once doesn't carry across assignments
• Module resolution depends on tsconfig moduleResolution (bundler vs node16 vs nodenext): wrong choice silently breaks deep imports