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

The `satisfies` operator to the rescue

satisfies allows us to have the best of both worlds:

typescript

Concrete use cases

1. Configuration validation

typescript

2. Typing constants with union types

typescript

Best practices

Use satisfies for configuration objects
- Ideal for validating structure while allowing extensions
Prefer satisfies over type assertions
- Safer than as because validation is done at definition
Combine with utility types
```
typescript
```

Limitations and pitfalls to avoid

Don't overload types
```
typescript
```
Be careful with union types
```
typescript
```

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.

💡 Pro tip: Use satisfies when you need to validate a type while maintaining precise property inference. It's particularly useful for configuration objects and typed constants.

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

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

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

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[]

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

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

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 };