The satisfies Operator - TypeScript Expert - ggcoder.com

What satisfies Does

The satisfies operator, introduced in TypeScript 4.9, validates that an expression is assignable to a type without widening or changing its inferred type. You get both type-safety and the narrowest possible type.

satisfies-intro.ts

1// Type annotation widens — 'port' is inferred as string | number2const config: Record<string, string | number> = {3  host: "localhost",4  port: 3000,5};6config.port.toFixed(); // Error: toFixed does not exist on string | number78// satisfies validates without widening — 'port' stays number, 'host' stays string9const config2 = {10  host: "localhost",11  port: 3000,12} satisfies Record<string, string | number>;1314config2.port.toFixed();  // OK — TypeScript knows port is number15config2.host.toUpperCase(); // OK — TypeScript knows host is string

Comparison: satisfies vs Type Annotation vs as

There are three ways to apply type information to an expression, each with different tradeoffs. Understanding the distinction helps you pick the right tool.

Type annotation (const x: T = ...): widens the inferred type to T. TypeScript forgets the specific literal types. Good when you truly want type T.

satisfies T: validates assignability to T but preserves the narrowly inferred type. Best when you need validation without losing type information.

as T (type assertion): overrides the inferred type without any checking. Unsafe — TypeScript trusts you unconditionally. Use only as a last resort.

comparison.ts

1type Color = "red" | "green" | "blue";23// Annotation: palette is Record<Color, string>, values become string (widened)4const paletteAnnotated: Record<Color, string> = {5  red: "#ff0000",6  green: "#00ff00",7  blue: "#0000ff",8};9// paletteAnnotated.red is 'string', not '#ff0000'1011// satisfies: values keep their literal types12const palette = {

Use Case: Key Validation with Preserved Value Types

The most common pattern for satisfies is applying it to object literals when you want TypeScript to check key completeness and correctness while retaining per-value literal types.

key-validation.ts

1type Route = "home" | "about" | "contact";23const routeMeta = {4  home:    { title: "Home",    icon: "house" },5  about:   { title: "About",   icon: "info" },6  contact: { title: "Contact", icon: "mail" },7} satisfies Record<Route, { title: string; icon: string }>;89// Each value keeps its literal shape:10routeMeta.home.icon; // type is "house", not just string1112// Missing a key is a compile error:

Tip

satisfies still performs excess property checking on object literals. If a key is not present in the constraining type, TypeScript reports an error at the declaration site — exactly where you want it.

Use Case: Config Objects with Mixed Value Types

satisfies shines with config objects whose values have different types. A type annotation loses the specific type info; satisfies preserves it for safe downstream access.

config-satisfies.ts

1type AppConfig = {2  host: string;3  port: number;4  debug: boolean;5  tags: string[];6};78const config = {9  host: "localhost",10  port: 3000,11  debug: true,12  tags: ["web", "api"],

Gotchas and Things to Avoid

satisfies Does Not Prevent Reassignment

satisfies validates at declaration only. It does not add readonly to the inferred type, so properties remain mutable unless you also use as const or explicit readonly.

Tip

Combine satisfies with as const for both type validation and immutability: const x = { ... } as const satisfies T. Order matters — as const is applied first, then satisfies validates that immutable type.

Warning

satisfies works on expressions, not function declarations. You cannot write function f() satisfies T. For return type validation, use a standard return type annotation.

Summary

satisfies validates assignability to a type without widening the inferred type

Type annotation widens to T; satisfies keeps the narrow type; as skips all checking

Use satisfies on object literals when you want key validation and preserved literal value types

Excess property checking still applies — extra keys are compile errors

Combine as const satisfies T for both immutability and type validation

satisfies works on expressions only, not function declarations

1// Type annotation widens — 'port' is inferred as string | number2const config: Record<string, string | number> = {3 host: "localhost",4 port: 3000,5};6config.port.toFixed(); // Error: toFixed does not exist on string | number78// satisfies validates without widening — 'port' stays number, 'host' stays string9const config2 = {10 host: "localhost",11 port: 3000,12} satisfies Record<string, string | number>;1314config2.port.toFixed(); // OK — TypeScript knows port is number15config2.host.toUpperCase(); // OK — TypeScript knows host is string

1type Color = "red" | "green" | "blue";23// Annotation: palette is Record<Color, string>, values become string (widened)4const paletteAnnotated: Record<Color, string> = {5 red: "#ff0000",6 green: "#00ff00",7 blue: "#0000ff",8};9// paletteAnnotated.red is 'string', not '#ff0000'1011// satisfies: values keep their literal types12const palette = {

1type Route = "home" | "about" | "contact";23const routeMeta = {4 home: { title: "Home", icon: "house" },5 about: { title: "About", icon: "info" },6 contact: { title: "Contact", icon: "mail" },7} satisfies Record<Route, { title: string; icon: string }>;89// Each value keeps its literal shape:10routeMeta.home.icon; // type is "house", not just string1112// Missing a key is a compile error: