Overview
TypeScript is constantly evolving with powerful features, some of which, despite their utility, lack dedicated documentation. One such feature is the `satisfies` keyword. This article will guide you through understanding and implementing the `satisfies` keyword with practical, real-world examples. You’ll learn how to maintain specific types while ensuring they conform to broader type definitions, enhance autocompletion, prevent type widening, and enforce exhaustive checks in switch statements, ultimately leading to more robust and maintainable code.
Understanding the Problem `satisfies` Solves
Before diving into `satisfies`, let’s understand the issue it addresses. Consider a scenario where you have a general type and a specific value that should conform to it, but you also want to retain the specific type’s information.
Example: Basic Type Conformance
Imagine you have an object type defined as:
type ObjectType = {
value: string | number;
};
And a variable:
let a = {
value: 'hello'
};
If you were to type `a` directly as `ObjectType`:
let a: ObjectType = {
value: 'hello'
};
This works for ensuring the structure matches. However, if you attempt to use a method specific to strings (like `toLowerCase()`), you’ll encounter an error:
// Error: Property 'toLowerCase' does not exist on type 'string | number'.
a.value.toLowerCase();
This happens because TypeScript, by enforcing the `ObjectType`, narrows the `value` property to `string | number`, losing the specific knowledge that `a.value` is indeed a string in this context.
Introducing the `satisfies` Keyword
The `satisfies` keyword allows you to assert that a value conforms to a specific type without changing the value’s original, more specific type. It ensures structural compatibility while preserving the original type information.
Syntax
The `satisfies` keyword is placed after the value and before the type it should satisfy:
const myValue = { ... } satisfies MyType;
Applying `satisfies` to the Basic Example
Let’s revisit the previous example using `satisfies`:
type ObjectType = {
value: string | number;
};
const a = {
value: 'hello'
} satisfies ObjectType;
// This now works perfectly:
a.value.toLowerCase();
With `satisfies ObjectType`, TypeScript knows that `a` must have a `value` property that is either a string or a number. Crucially, it also retains the knowledge that `a.value` is specifically a string because that’s its original type. This provides the structural type safety of `ObjectType` without losing the specific type information of `’hello’`.
Real-World Use Cases
1. Complex Configuration Objects
When dealing with complex configuration objects, especially those with many optional properties, `satisfies` can be invaluable for maintaining type specificity and gaining autocompletion.
Scenario
Consider a function accepting a complex options object:
type ComplexOptions = {
mode: 'simple' | 'advanced';
level?: number;
format?: string;
retry?: boolean;
// ... many other optional properties
};
function processOptions(options: ComplexOptions) {
// Function implementation
}
If you define your options separately:
const myOptions = {
mode: 'simple',
level: 5,
format: 'json'
};
// Problem: TypeScript might widen the types (e.g., 'simple' becomes string)
// and you lose autocompletion and specific type information.
processOptions(myOptions);
Using `satisfies` resolves this:
const myOptions = {
mode: 'simple',
level: 5,
format: 'json'
} satisfies ComplexOptions;
processOptions(myOptions);
Benefit: You get full autocompletion for `myOptions` and its properties. TypeScript maintains the specific literal types (e.g., `’simple’`) instead of widening them to `string`. This prevents accidental assignment of incorrect values and ensures you’re working with the most precise types possible.
2. Defining Data Structures with Specific Constraints
When defining data structures that need to adhere to a general type but also have specific, constrained values, `satisfies` is extremely useful.
Scenario
Imagine defining RGB color values:
type RGB = `#${string}` | [number, number, number];
const primaryColors = {
red: '#FF0000',
green: '#00FF00',
blue: '#0000FF'
};
type ColorMap = Record<'red' | 'green' | 'blue', RGB>;
// Problem: If you type primaryColors as ColorMap directly,
// TypeScript might lose the specific string literal types.
// const typedColors: ColorMap = primaryColors; // Might cause issues or widen types
Using `satisfies` ensures the structure matches `ColorMap` while keeping the specific string literals:
const primaryColors = {
red: '#FF0000',
green: '#00FF00',
blue: '#0000FF'
} satisfies ColorMap;
// Now, primaryColors.red is still '#FF0000', not just string.
console.log(primaryColors.red.toUpperCase()); // Works as expected
Benefit: You enforce that the `primaryColors` object has keys ‘red’, ‘green’, and ‘blue’, and that each corresponding value is of type `RGB`. Crucially, the actual string values like `’#FF0000’` retain their specific literal types, preventing accidental modifications or assignments that don’t strictly match.
3. Ensuring Exhaustive `switch` Statements (The Killer Feature)
This is perhaps the most powerful application of `satisfies`. It allows you to ensure that every possible case in a `switch` statement is handled, especially when dealing with enums or union types.
Scenario
Consider an enum for grades and a function to get their descriptions:
enum Grade {
A = 'A',
B = 'B',
C = 'C',
D = 'D',
F = 'F'
}
function getGradeDescription(grade: Grade): string {
switch (grade) {
case Grade.A:
return 'Excellent';
case Grade.B:
return 'Good';
case Grade.C:
return 'Average';
case Grade.D:
return 'Below Average';
// Missing case for Grade.F!
}
}
If you run this, passing `Grade.F` would result in `undefined` being returned, as there’s no `case` for it. If you later add a new grade (e.g., `Grade.S`), you’d have to remember to update all `switch` statements across your codebase.
The `satisfies never` Trick
To enforce exhaustiveness, you can use `satisfies` with the `never` type. The `never` type represents values that should never occur. If a `switch` statement covers all possible cases of a union type, the variable’s type after the switch will correctly be `never`. If a case is missed, the type will remain the original union type, causing a TypeScript error when assigned to `never`.
enum Grade {
A = 'A',
B = 'B',
C = 'C',
D = 'D',
F = 'F'
}
function getGradeDescription(grade: Grade): string {
switch (grade) {
case Grade.A:
return 'Excellent';
case Grade.B:
return 'Good';
case Grade.C:
return 'Average';
case Grade.D:
return 'Below Average';
case Grade.F:
return 'Failing'; // Added the missing case
default:
// This ensures that if a new grade is added to the enum,
// and not handled above, TypeScript will throw an error here.
const _exhaustiveCheck: never = grade;
return `Unknown grade: ${_exhaustiveCheck}`;
}
}
// Using the `satisfies never` pattern directly on the switch statement's default:
function getGradeDescriptionImproved(grade: Grade): string {
const description = (() => {
switch (grade) {
case Grade.A:
return 'Excellent';
case Grade.B:
return 'Good';
case Grade.C:
return 'Average';
case Grade.D:
return 'Below Average';
case Grade.F:
return 'Failing';
}
})();
// Here, if any case is missed, 'grade' will not be 'never'.
// The `satisfies never` check happens implicitly if you assign the result
// of the switch to a variable typed as `never` or use it in a way that requires it.
// A more direct way to use `satisfies` for this is often combined with a default:
// Let's refine this to show the direct `satisfies` application:
switch (grade) {
case Grade.A: return 'Excellent';
case Grade.B: return 'Good';
case Grade.C: return 'Average';
case Grade.D: return 'Below Average';
case Grade.F: return 'Failing';
}
// The following line ensures exhaustiveness. If 'grade' is not one of the above,
// it means a case was missed. Trying to satisfy 'never' will fail.
// However, the most common pattern is the default case throwing an error or
// checking against `never` like this:
// const _unhandled: never = grade; // This will error if grade is not fully handled.
}
// A cleaner implementation demonstrating the principle:
function getGradeDescriptionFinal(grade: Grade): string {
switch (grade) {
case Grade.A: return 'Excellent';
case Grade.B: return 'Good';
case Grade.C: return 'Average';
case Grade.D: return 'Below Average';
case Grade.F: return 'Failing';
default:
// This ensures exhaustiveness. If a new grade is added to the enum
// and not handled above, TypeScript will throw an error here.
const _exhaustiveCheck: never = grade;
// Using template literal for clarity in error message
throw new Error(`Unhandled grade: ${_exhaustiveCheck}`);
}
}
console.log(getGradeDescriptionFinal(Grade.A));
console.log(getGradeDescriptionFinal(Grade.F));
// If you were to add Grade.S to the enum and forget to add a case for it,
// the `_exhaustiveCheck: never = grade;` line would immediately give you a compile-time error.
Benefit: This pattern acts as a safety net. Whenever the `Grade` enum is updated (e.g., a new grade is added), TypeScript will flag the `switch` statement, forcing you to handle the new case. This prevents runtime errors caused by unhandled enum values.
Conclusion
The `satisfies` keyword in TypeScript is a powerful tool for enhancing type safety without compromising flexibility. It allows you to maintain specific type information while ensuring conformance to broader types, improves developer experience through better autocompletion, prevents unwanted type widening, and is crucial for enforcing exhaustive checks in control flow structures like `switch` statements. By incorporating `satisfies` into your workflow, you can write more robust, maintainable, and error-resistant TypeScript code.
Source: This Amazing TypeScript Feature Has NO Docs! (YouTube)
