typescript-satisfies-operator

TypeScript satisfies

Goal

Validate that a value matches a type without replacing the value's inferred type.

Rules

• Use satisfies when value specificity should win.
• Use : Type when the variable should have the wider type.
• Use as const satisfies for readonly literal config.
• Avoid as Type unless it is a deliberate escape hatch.
• Use Record<Union, Value> with satisfies for exhaustive maps.

Mental Model

• : Type: type wins, value may widen.
• satisfies Type: value wins, shape is checked.
• as Type: tells TypeScript to trust you.
• no annotation: inference only.

Pattern

type Locale = "en" | "cs";

const localeIds = {
  en: "1",
  cs: "2",
} as const satisfies Record<Locale, string>;

Object Validation

type Colors = "red" | "green" | "blue";
type RGB = [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<Colors, string | RGB>;

palette.green.toUpperCase();

Use Cases

• Route maps.
• Locale maps.
• Feature flag config.
• Status labels.
• Event handler maps.
• Design token objects.

Avoid

• Annotating config objects so all literals widen.
• Using satisfies when later reassignment needs wider type.
• Using as const after a type annotation and expecting literals to survive.

References

• TypeScript 4.9 Release Notes
• Matt Pocock - Clarifying the satisfies Operator
• GitHub Issue #47920 - Original Proposal

Output

• Whether to use annotation, satisfies, as const satisfies, or inference.
• Reason tied to widening or validation.
• Example replacement when useful.