typescript-conventions

name	typescript-conventions
description	TypeScript convention lens consulted BEFORE writing code — strictness, type-at-the-boundary, discriminated unions over booleans, and no-any hygiene. Appended to impl-conventions.txt by the stack-conventions pack. Also usable standalone.

typescript-conventions

When: consulted by plan-writer (to record type-design decisions) and by implement-feature (to apply them while coding), in projects where the stack-conventions pack is installed and the stack is TS. Not a review lens — shapes code as written; the code-review lens still audits it after.

Scope: TS the change introduces. Advisory knowledge, makes no edits.

Conventions

• Strict on: assume strict: true. No implicit any. If a value's type is unknown at a boundary, type it unknown and narrow — never any to silence the compiler.
• Type at the boundary: every external input (HTTP body/query, env, DB row, third-party response) is validated into a typed shape at the edge (zod/valibot/class-validator or an explicit parser), so the interior is trusted. Don't cast (as Foo) untrusted data into a type — casting is an assertion, not a check.
• Make illegal states unrepresentable: discriminated unions over boolean flags for mutually exclusive states ({ status: 'loading' } | { status: 'ok'; data } | { status: 'error'; error }, not isLoading+data?+error?). Prefer readonly fields and as const for fixed sets.
• Narrow allowed values by whitelist: for source/role/type/origin checks, type them as a union and check membership against the allowed set — the compiler then rejects new stray values by default (mirrors the constitution's authorization rule).
• Async correctness: every promise is awaited or explicitly voided; no floating promises. Errors propagate as typed results or thrown typed errors — never swallowed in a bare catch {}.
• No enums-as-strings sprawl: a fixed set is a union type or const object, named once and imported — not the same string literal retyped across files.
• Nullish over falsy: ?? / ?. for null-vs-undefined intent; reserve || for genuine boolean-falsy defaults.

Applying

• In plan-writer: when the plan introduces a domain state machine or an external boundary, record the union/parse-at-edge decision in Technical Decisions.
• In implement-feature: match the repo's existing validation lib and type-organization convention before introducing a new one — climb the laziness ladder (reuse existing).