typescript-patterns

name	typescript-patterns
description	TypeScript/Node conventions — strict compiler settings, parse-don't-cast boundaries, Result-style domain errors, floating-promise hygiene, ESM. Use when writing or reviewing TypeScript.

TypeScript

General TS/Node rules. React Native specifics live in react-native.md; both may load on the same file — this one governs the language, that one the platform.

Compiler is the first reviewer

• strict: true plus noUncheckedIndexedAccess and exactOptionalPropertyTypes in every new tsconfig. Weakening compiler options to make code compile is fixing the smoke alarm with a hammer.
• No any — use unknown and narrow. No non-null ! outside tests. No as on data you didn't construct.
• @ts-ignore/@ts-expect-error require a reason on the same line; prefer @ts-expect-error (it errors when stale).

Trust boundaries

• Parse, don't cast: every external input (HTTP body, env, file, LLM output, queue message) goes through a schema (zod or equivalent) at the boundary. JSON.parse(x) as Config is a runtime bug with a type-checker alibi.
• Inside the boundary, trust the types — re-validating everywhere means the boundary isn't doing its job.

Errors & control flow

• Throw only at boundaries; inside domain logic return discriminated unions / Result shapes so the compiler forces handling.
• Discriminated unions get exhaustiveness checks: a switch ends with a never-typed default (assertNever(x)), so adding a variant breaks the build, not production.
• ?? vs ||: use || only when 0/''/false are genuinely invalid values. Defaulting with || on numeric or string config is a classic silent bug.

Async

• No floating promises: every promise is awaited, returned, or explicitly void-ed with a comment. Enable @typescript-eslint/no-floating-promises.
• Independent awaits go through Promise.all — sequential awaiting of unrelated calls is silent 2-10x latency.
• Async functions that can reject are handled where the context to handle them exists — an unhandledRejection crash in Node is a design failure, not bad luck.

Modules & structure

• ESM only for new code ("type": "module"); no new CJS. Node built-ins imported with the node: prefix.
• Barrel files (index.ts re-export hubs) are import-cycle factories and tree-shaking obstacles — import from the concrete module.
• No mutable module-level state; module scope is for constants and pure definitions. A mutable module singleton is a hidden global with import-order semantics.

Runtime & deps

• Stdlib before deps: node:test, built-in fetch, node --env-file, node:util parseArgs — reach for a package only when these run out.
• Pin engines ("engines": { "node": ">=22" }) and commit the lockfile. CI installs with npm ci, never npm install.

Tests

• node:test (or the repo's established runner) with the same no-real-world rule as Go/Python: no live network, no wall clock, no shared module state between tests — reset or inject.