Back to skills

skills/typescript-satisfies-operator/SKILL.md

typescript-satisfies-operator

Choose TypeScript satisfies, type annotations, as const, or assertions. Use when validating config objects, route maps, locale maps, feature flags, status labels, design tokens, or handler maps while preserving literal types; fixing widened types; or requiring exhaustive Record keys. For general interface/type choice use typescript-interface-vs-type; for broader typing strategy use typescript-best-practices.

npx skills add https://github.com/flpbalada/fb-skills --skill typescript-satisfies-operator
GitHub

Skill Docs

When to use

  • Validating object shape while preserving literal types.
  • Defining config objects, route maps, locale maps, or handler maps.
  • Choosing between : Type, satisfies Type, as const, and as Type.
  • Fixing widened types caused by annotations.

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

Output

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