TypeScript and JavaScript Conventions

Framework-agnostic language conventions for any TS/JS code: browser, Node, build tooling, service workers, browser extensions. Framework specifics layer on top (personal-angular-conventions for Angular). Assumes TypeScript 5+.

TypeScript strictness

• strict: true is the floor. Also enable noUncheckedIndexedAccess, noImplicitOverride, noFallthroughCasesInSwitch, exactOptionalPropertyTypes, and noImplicitReturns.
• No any. Use unknown for genuinely unknown values and narrow with type guards. An any that must exist (untyped dependency) is isolated behind a typed wrapper, never spread through call sites.
• No non-null assertions (!.) without a comment explaining why the value cannot be null. Prefer narrowing or an early return.
• No @ts-ignore; use @ts-expect-error with a reason comment so it fails when the underlying issue is fixed.
• Type guards return value is T, not boolean. Centralize narrowing in named user-defined guards.

Type modeling

• Prefer discriminated unions (a literal kind/type tag) over inheritance or optional-field soup for variant types. Exhaustive-check the tag in a switch with a never default.
• Use utility types (Partial, Pick, Omit, Readonly, Record, ReturnType, Awaited) instead of redefining shapes.
• String-literal unions over enum for closed sets that cross a runtime boundary (JSON, storage, wire). const enum only when bundled in and never exposed across a package boundary.
• interface for object shapes meant to be implemented or extended; type for unions, intersections, tuples, and mapped/conditional types. Pick one and stay consistent within a file.
• Model "no value" deliberately: a single optional (x?: T) over T | null | undefined ambiguity; don't mix null and undefined to mean the same thing (pick one per codebase - undefined is the TS-idiomatic default).
• readonly by default for data: readonly properties, ReadonlyArray<T> / readonly T[] for collections, as const for literal config. Mutability is opt-in.