typescript-best-practices

TypeScript Best Practices

Treat types as precise, compiler-checked models of valid program states and boundaries; preserve inference where it carries information, then narrow uncertainty explicitly so invalid states and unhandled cases cannot silently reach runtime.

Effective Strategies for TypeScript

Read the references that apply to the current task before writing or reviewing TypeScript.

1. Preserve TypeScript's specific inference whenever it proves the intended contract.
   • Infer derivable types and impose annotations only where they prove a required contract, because redundant annotations drift while deliberate boundary contracts constrain implementations.
   • Declare the intended state set at a literal inference boundary when an API infers a closed state from one initial literal so later valid members remain assignable.
   • Model named durable closed sets of serialized primitive values as const enums rather than string-literal unions.
   • Preserve readonly tuple or literal-union inference with as const when consumers require it rather than treating the assertion as a default.
   • Use structural conformance when a value must satisfy a shape without losing its precise inferred literals instead of widening it with an annotation.
2. Model domain contracts and closed states precisely.
   • Choose interface by default and compose it with extends for object contracts; reserve type for contracts that interfaces cannot express naturally.
   • Model parallel flags as discriminated variants so impossible state combinations cannot occur and each status has one valid shape.
   • Make decisions over closed enums or unions exhaustive so new members cannot silently reach a fallback.
3. Narrow uncertainty and absence explicitly at the boundary that owns it.
   • Contain type escape hatches by narrowing or validating any and unknown inside the boundary that receives them so neither can escape to callers or domain state.
   • Replace unchecked assertions with runtime proof at a serialization boundary when a value is untrusted or insufficiently typed.
   • Establish an absent-value invariant explicitly when an operation requires it rather than asserting it with !.
   • Express optional-argument omission by leaving it out; pass void 0 only when the API requires a positional value.
   • Narrow a required optional value before the call, or preserve absence in its return or state contract when it is expected.
   • Do not fabricate a default for missing required input unless the domain contract assigns that exact omitted-value meaning.
   • Guard an indexed array value before treating it as present when bracket access or destructuring can produce no element.
   • Preserve absence from a .split() component until domain or display policy resolves it instead of supplying an arbitrary empty string.
   • Validate a required regular-expression capture first because named and positional groups can be absent.