TypeScript: Mastering the `satisfies` operator

TypeScript: Mastering the satisfies operator

The satisfies operator is one of TypeScript's most powerful features for type validation. Introduced in version 4.9, it offers a perfect balance between strict type checking and smart type inference. Let's discover together how to use it effectively.

The problem satisfies solves

In TypeScript, we often need to verify that an object matches a specific type while preserving exact information about its properties. Traditional approaches have limitations:

typescript
1// Type definition
2type ColorMap = {
3  primary: string;
4  secondary: string;
5};
6
7// Approach 1: Type annotation - Loss of precise information
8const colors: ColorMap = {
9  primary: '#007bff',
10  secondary: '#6c757d',
11}; // The exact type of values is lost
12
13// Approach 2: Without annotation - No validation
14const colors2 = {
15  primary: '#007bff',
16  secondary: '#6c757d',
17}; // No validation against ColorMap

The satisfies operator to the rescue

satisfies allows us to have the best of both worlds:

typescript
1const colors = {
2  primary: '#007bff',
3  secondary: '#6c757d',
4} satisfies ColorMap;
5
6// ✅ Checks conformity with ColorMap
7// ✅ Preserves literal string information
8// ✅ Autocompletion works perfectly

Concrete use cases

1. Configuration validation

typescript
1type Config = {
2  api: {
3    endpoint: string;
4    timeout?: number;
5  };
6  features: Record<string, boolean>;
7};
8
9const config = {
10  api: {
11    endpoint: 'https://api.example.com',
12    timeout: 5000,
13    retryCount: 3, // Additional property allowed
14  },
15  features: {
16    darkMode: true,
17    betaFeatures: false,
18  },
19} satisfies Config;
20
21// TypeScript checks that required properties are present
22// while allowing additional properties

2. Typing constants with union types

typescript
1type MediaType = 'image' | 'video' | 'audio';
2
3const MEDIA_CONFIG = {
4  image: { maxSize: 5000000, formats: ['jpg', 'png'] },
5  video: { maxSize: 50000000, formats: ['mp4', 'mov'] },
6  audio: { maxSize: 10000000, formats: ['mp3', 'wav'] },
7} satisfies Record<MediaType, { maxSize: number; formats: string[] }>;
8
9// Accessing properties maintains their precise type
10const imageFormats = MEDIA_CONFIG.image.formats; // string[]

Best practices

1. Use satisfies for configuration objects

   • Ideal for validating structure while allowing extensions

2. Prefer satisfies over type assertions

   • Safer than as because validation is done at definition

3. Combine with utility types

   typescript
   1type Partial<T> = { [P in keyof T]?: T[P] };
   2
   3const partialConfig = {
   4  api: { endpoint: 'https://api.example.com' },
   5} satisfies Partial<Config>;
   

Limitations and pitfalls to avoid

1. Don't overload types

   typescript
   1// ❌ Too restrictive
   2type StrictConfig = {
   3  [K in string]: never;
   4} & Config;
   5
   6// ✅ More flexible
   7type ExtensibleConfig = Config & Record<string, unknown>;
   

2. Be careful with union types

   typescript
   1type Status = 'success' | 'error';
   2
   3// ❌ Can be misleading
   4const result = { status: 'success' as Status };
   5
   6// ✅ Safer
   7const result = { status: 'success' } satisfies { status: Status };
   

Conclusion

The satisfies operator is a powerful tool for type validation in TypeScript. It allows you to:

• Check conformity with a type
• Preserve precise type inference
• Allow extensions while guaranteeing the base structure

By using it judiciously, you can make your code more robust while maintaining the flexibility needed for your application.