TypeScript offers several ways to describe an object, but they do not provide the same guarantees. This guide compares satisfies, as const, explicit type annotations, and type assertions so you can validate configuration objects while preserving useful literal types, autocomplete, and reliable error messages.
Overview
Configuration objects, route maps, feature flags, and lookup tables often need two things at once: they must conform to a known shape, and their individual values must remain specific. A route method such as 'GET' is more useful than a widened string; a feature flag key such as 'checkout' is more useful than an arbitrary property name.
The four common approaches solve different problems:
- Type annotations describe the variable's type and contextually check the value.
satisfieschecks that an expression conforms to a type without replacing the expression's inferred type.as constpreserves literal values and makes the resulting expression deeply readonly.- Type assertions, written with
as SomeType, tell the compiler to treat a value as another type. They are useful at carefully controlled boundaries, but they can suppress errors.
For most hand-written configuration, satisfies is the best starting point when you want validation and precise inference. Add as const when the values should be immutable and literal. Use an annotation when the declared type itself should control the variable. Reserve assertions for cases where you have stronger knowledge than the compiler and can justify the boundary.
How to compare options
Before choosing a syntax, ask four questions:
- Should unknown properties be rejected? This matters for configuration because a misspelled key can otherwise be silently ignored.
- Do values need to remain literals? Literal types enable precise discriminated unions, key-based lookups, and autocomplete.
- Should the object be mutable? Readonly inference is useful for constants, but inconvenient for objects that will be edited.
- Should the declared type replace inference? An annotation intentionally gives the variable the annotated type.
satisfieschecks against a type while retaining more information from the expression.
These are separate concerns. A type annotation is not simply a safer version of an assertion, and as const is not a replacement for validating a schema. In particular, as const preserves literals but does not, by itself, prove that an object has the properties required by a separate configuration type.
| Approach | Excess-property checks | Literal inference | Mutability | Error reporting |
|---|---|---|---|---|
const x: Config = value | Yes, especially for a fresh object literal | Usually widened to the annotation's types | Controlled by Config | Clear shape-oriented errors |
const x = value satisfies Config | Yes, including unknown keys on a fresh literal | Preserved from the expression | Normal mutability unless combined with as const | Reports mismatch while retaining property context |
const x = value as const | Not a schema check by itself | Preserved as narrowly as possible | Deeply readonly for the expression | Does not identify missing schema requirements unless another check is used |
const x = value as Config | Can be bypassed | Generally replaced by the asserted view | Controlled by Config | May hide a real mismatch |
Feature-by-feature breakdown
satisfies: validate without throwing away inference
Use satisfies when an object must conform to a known contract but you still want TypeScript to remember its exact keys and values:
type Route = {
method: 'GET' | 'POST';
auth: boolean;
};
type RouteMap = Record<string, Route>;
const routes = {
users: { method: 'GET', auth: true },
sessions: { method: 'POST', auth: true }
} satisfies RouteMap;
routes.users.method; // 'GET'
routes.sessions.auth; // boolean value: true
The object is checked against RouteMap, so a misspelled property inside a route or an invalid method is reported. At the same time, routes.users remains a known property rather than becoming merely Route or Record<string, Route>. The object is still mutable because satisfies does not add readonly modifiers.
as const: preserve literals and freeze the type view
Use as const for a value that represents a fixed set of data:
const features = {
checkout: { enabled: true, owner: 'payments' },
search: { enabled: false, owner: 'catalog' }
} as const;
type FeatureName = keyof typeof features;
type Owner = (typeof features)[FeatureName]['owner'];
Keys and nested values remain literal types, and properties become readonly. This is convenient for deriving unions with keyof typeof, but it does not validate a separate required shape. If owner is misspelled or a required property is omitted, as const alone has no contract against which to compare it.
Annotations: declare the variable's public shape
An explicit annotation is appropriate when consumers should see a stable abstraction rather than every detail of the initializer:
type AppConfig = {
port: number;
environment: 'development' | 'production';
};
const config: AppConfig = {
port: 3000,
environment: 'development'
};
The annotation catches missing and unknown properties on the object literal. It also contextually types the values. In this example, config.environment is typed as the union 'development' | 'production', not necessarily the single literal 'development'. That is often desirable when the variable may be reassigned within the declared contract.
Assertions: an escape hatch, not validation
A type assertion changes how the compiler views an expression:
const rawConfig = loadConfigFromFile();
const config = rawConfig as AppConfig;
This can be reasonable after runtime validation or when a library's type declarations cannot express a fact established elsewhere. It is unsafe when used merely to silence an error. An assertion does not transform data, check a JSON file at runtime, or guarantee that an API response matches the asserted type. For external input, pair static types with runtime validation; see the TypeScript runtime validation guide.
Combining satisfies and as const
For immutable configuration with both schema checking and literal preservation, combine the operators:
type Theme = {
mode: 'light' | 'dark';
contrast: 'normal' | 'high';
};
const themes = {
default: { mode: 'light', contrast: 'normal' },
accessible: { mode: 'dark', contrast: 'high' }
} as const satisfies Record<string, Theme>;
The ordering matters conceptually: as const creates the narrow readonly expression, while satisfies checks that expression against the required shape. This pattern is useful for route definitions, design tokens, feature flags, and lookup tables that should not be modified after declaration.
Best fit by scenario
Configuration objects
Prefer satisfies when configuration should be checked but values such as environment names, modes, or adapter identifiers should remain specific. Use as const satisfies Config for a static configuration that should be readonly. For framework configuration, apply the framework's exported configuration type where available, but avoid assertions that conceal unsupported options.
Route maps and discriminated unions
Use satisfies to validate each route while preserving the literal method or handler metadata. For a fixed command list, as const can derive a union of command names:
const commands = ['start', 'stop', 'restart'] as const;
type Command = typeof commands[number];
If each item must have a discriminant, validate the array as well:
type Action =
| { kind: 'add'; amount: number }
| { kind: 'remove'; amount: number };
const actions = [
{ kind: 'add', amount: 1 },
{ kind: 'remove', amount: 2 }
] as const satisfies readonly Action[];
Mutable data and builders
Choose an annotation when the object is intentionally updated and its public type should remain stable. Avoid as const if later assignments are part of the design; its readonly result will create errors that are correct but unhelpful for that use case.
External data
Neither annotations nor satisfies validates data received at runtime. Parse or validate external data first, then give the validated result an appropriate type. This distinction is especially important for Node.js environment variables, HTTP responses, generated JSON, and user-submitted forms. For related form typing patterns, see React forms with TypeScript.
When to revisit
Revisit this decision whenever a configuration type changes, a new key is added, or a value that used to be a broad string must drive a discriminated union. These changes often expose whether the object is being validated or merely asserted.
- Start with an explicit contract such as
Config,Record<Key, Value>, or a union of allowed variants. - Replace broad assertions with
satisfieswhere the data is local and should be checked. - Add
as constonly when literal preservation or readonly behavior is useful. - Run the compiler with the project's normal strictness settings and inspect the exact error location.
- For generated or external data, add runtime validation instead of increasing the strength of an assertion.
When a compiler error appears after a refactor, do not immediately add as SomeType. First decide whether the object has the wrong shape, the wrong mutability, or an unnecessarily widened value. That diagnosis usually points to the smallest reliable fix: an annotation for a stable public shape, satisfies for checked inference, as const for immutable literals, or a narrowly documented assertion at a genuine boundary.
For broader type-safety work, the same principle applies to utility types, generated API models, and migration code: preserve information where it helps the compiler, validate data where it crosses a runtime boundary, and use assertions only when the reason can be explained in the code review.