For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/typescript/types.md.
Quick start

Types

Use types to describe valid states. Use runtime checks to establish whether external data belongs to those states.

Narrowing and modeling

Why

A local directory and a Git commit have different required fields. One broad object with optional fields permits combinations the installer cannot use.

Rules

  • MUST accept untrusted data as unknown until a schema or type guard validates it. [review]
  • MUST avoid any, the non-null assertion operator, and assertions unsupported by a runtime check. [review]
  • MAY retain literal types with as const, or use a documented assertion immediately after proving it at runtime. [review]
  • MUST use type for object contracts; reserve interface for necessary augmentation or declaration merging. [review]
  • MUST expose object fields and incoming collections through readonly types. [review]
  • MUST assign variants a common literal discriminant and variant-specific required data. [review]
  • MUST derive a union from its literal catalog instead of maintaining parallel lists. [review]
  • MUST try built-in utility types before duplicating a related contract or writing a mapped type. [review]
  • SHOULD inspect type-fest when a built-in utility cannot express the needed relationship, subject to the consumer's dependency approval. [review]

Example

type ContentOrigin =
  | { readonly kind: 'directory'; readonly path: string }
  | { readonly kind: 'commit'; readonly repository: string; readonly commit: string }

[review]

Typechecks establish supported narrowing and readonly contracts. Boundary tests prove runtime validation; review checks unsafe assertions and deeper immutability.

Enforcement

Typechecks establish supported narrowing and readonly contracts. Boundary tests prove runtime validation; review checks unsafe assertions and deeper immutability.