0
# Utility Types
1
2
Utility Types is a comprehensive collection of TypeScript utility types that complement built-in mapped types and aliases. It provides the essential type-level utilities for TypeScript developers, serving as the "lodash" for static types with zero runtime cost and no dependencies.
3
4
## Package Information
5
6
- **Package Name**: utility-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install utility-types`
10
- **Zero Runtime Cost**: Yes
11
- **Dependencies**: None
12
13
## Core Imports
14
15
```typescript
16
import {
17
// Flow-style utilities
18
$Keys, $Values, $ReadOnly, $Diff, $PropertyType, $ElementType,
19
$Call, $Shape, $NonMaybeType, Class,
20
21
// Advanced mapped types
22
SetIntersection, SetDifference, Diff, Omit, Optional, Required,
23
DeepReadonly, DeepRequired, DeepPartial, DeepNonNullable,
24
PickByValue, FunctionKeys, NonFunctionKeys, Mutable, Brand,
25
26
// Type aliases and guards
27
Primitive, Falsy, Nullish, isPrimitive, isFalsy, isNullish,
28
29
// Deprecated (do not use in new code)
30
getReturnOfExpression
31
} from 'utility-types';
32
```
33
34
For specific imports:
35
36
```typescript
37
import { Omit, DeepReadonly, $Keys } from 'utility-types';
38
```
39
40
## Basic Usage
41
42
```typescript
43
import { Omit, DeepReadonly, $Keys, Optional, PickByValue } from 'utility-types';
44
45
// Basic object manipulation
46
interface User {
47
id: number;
48
name: string;
49
email: string;
50
password: string;
51
}
52
53
// Remove sensitive fields
54
type PublicUser = Omit<User, 'password'>;
55
// Result: { id: number; name: string; email: string; }
56
57
// Make some fields optional
58
type UserUpdate = Optional<User, 'id' | 'email'>;
59
// Result: { id?: number; name: string; email?: string; password: string; }
60
61
// Extract keys as union type
62
type UserKeys = $Keys<User>;
63
// Result: "id" | "name" | "email" | "password"
64
65
// Deep readonly for nested objects
66
interface Settings {
67
theme: { mode: 'light' | 'dark'; colors: string[] };
68
preferences: { notifications: boolean; autoSave: boolean };
69
}
70
71
type ReadonlySettings = DeepReadonly<Settings>;
72
// Result: All properties and nested properties become readonly
73
74
// Pick properties by value type
75
interface Mixed {
76
id: number;
77
name: string;
78
count: number;
79
active: boolean;
80
}
81
82
type NumberFields = PickByValue<Mixed, number>;
83
// Result: { id: number; count: number; }
84
```
85
86
## Architecture
87
88
Utility Types is organized into four logical modules:
89
90
- **Flow-style Utilities**: Flow.js compatibility types for migration and interoperability
91
- **Advanced Mapped Types**: Complex type transformations, key selection, and object manipulation
92
- **Type Aliases and Guards**: Common type definitions with runtime type checking functions
93
- **Deep Transformations**: Recursive type operations for nested data structures
94
95
The library uses conditional types, mapped types, and type inference to provide compile-time type transformations without any runtime overhead.
96
97
## Capabilities
98
99
### Flow-style Utilities
100
101
Flow.js compatible utility types that enable easy migration from Flow to TypeScript and provide familiar APIs for Flow developers.
102
103
```typescript { .api }
104
type $Keys<T extends object> = keyof T;
105
type $Values<T extends object> = T[keyof T];
106
type $ReadOnly<T extends object> = DeepReadonly<T>;
107
type $Diff<T extends U, U extends object> = Pick<T, SetComplement<keyof T, keyof U>>;
108
type $PropertyType<T extends object, K extends keyof T> = T[K];
109
type $ElementType<T, K extends keyof T | number> = T[K];
110
type $Call<Fn extends (...args: any[]) => any> = Fn extends (arg: any) => infer RT ? RT : never;
111
type $Shape<T extends object> = Partial<T>;
112
type $NonMaybeType<T> = NonNullable<T>;
113
type Class<T> = new (...args: any[]) => T;
114
```
115
116
[Flow-style Utilities](./flow-utilities.md)
117
118
### Advanced Mapped Types
119
120
Sophisticated type transformations for object manipulation, key selection, and complex type operations including set operations and property filtering.
121
122
```typescript { .api }
123
// Set operations
124
type SetIntersection<A, B> = A extends B ? A : never;
125
type SetDifference<A, B> = A extends B ? never : A;
126
type SetComplement<A, A1 extends A> = SetDifference<A, A1>;
127
128
// Object manipulation
129
type Omit<T, K extends keyof any> = Pick<T, SetDifference<keyof T, K>>;
130
type Optional<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
131
type Required<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Required<Pick<T, K>>;
132
133
// Key selection
134
type FunctionKeys<T extends object> = {
135
[K in keyof T]-?: NonUndefined<T[K]> extends Function ? K : never;
136
}[keyof T];
137
type OptionalKeys<T> = {
138
[K in keyof T]: {} extends Pick<T, K> ? K : never;
139
}[keyof T];
140
141
// Value-based selection
142
type PickByValue<T, ValueType> = Pick<T, {
143
[Key in keyof T]: T[Key] extends ValueType ? Key : never;
144
}[keyof T]>;
145
```
146
147
[Advanced Mapped Types](./mapped-types.md)
148
149
### Type Aliases and Guards
150
151
Common type definitions with corresponding runtime type guard functions for type checking at runtime.
152
153
```typescript { .api }
154
type Primitive = string | number | bigint | boolean | symbol | null | undefined;
155
type Falsy = false | '' | 0 | null | undefined;
156
type Nullish = null | undefined;
157
158
function isPrimitive(val: unknown): val is Primitive;
159
function isFalsy(val: unknown): val is Falsy;
160
function isNullish(val: unknown): val is Nullish;
161
```
162
163
[Type Aliases and Guards](./aliases-guards.md)
164
165
### Deep Transformations
166
167
Recursive type operations that work on deeply nested data structures, providing consistent behavior across all nesting levels.
168
169
```typescript { .api }
170
type DeepReadonly<T> = T extends ((...args: any[]) => any) | Primitive
171
? T
172
: T extends _DeepReadonlyArray<infer U>
173
? _DeepReadonlyArray<U>
174
: T extends _DeepReadonlyObject<infer V>
175
? _DeepReadonlyObject<V>
176
: T;
177
178
type DeepRequired<T> = T extends (...args: any[]) => any
179
? T
180
: T extends any[]
181
? _DeepRequiredArray<T[number]>
182
: T extends object
183
? _DeepRequiredObject<T>
184
: T;
185
186
type DeepPartial<T> = { [P in keyof T]?: _DeepPartial<T[P]> };
187
188
type DeepNonNullable<T> = T extends (...args: any[]) => any
189
? T
190
: T extends any[]
191
? _DeepNonNullableArray<T[number]>
192
: T extends object
193
? _DeepNonNullableObject<T>
194
: T;
195
```
196
197
These transformations handle functions, arrays, and objects appropriately, ensuring type safety throughout complex nested structures.
198
199
## Type Definitions
200
201
### Common Supporting Types
202
203
```typescript { .api }
204
type NonUndefined<A> = A extends undefined ? never : A;
205
206
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
207
208
type Brand<T, U> = T & { __brand: U };
209
210
type PromiseType<T extends Promise<any>> = T extends Promise<infer U> ? U : never;
211
212
type ValuesType<T extends ReadonlyArray<any> | ArrayLike<any> | Record<any, any>> =
213
T extends ReadonlyArray<any>
214
? T[number]
215
: T extends ArrayLike<any>
216
? T[number]
217
: T extends object
218
? T[keyof T]
219
: never;
220
221
// Deep transformation helper types
222
interface _DeepReadonlyArray<T> extends ReadonlyArray<DeepReadonly<T>> {}
223
type _DeepReadonlyObject<T> = { readonly [P in keyof T]: DeepReadonly<T[P]> };
224
225
type _DeepRequiredArray<T> = Array<DeepRequired<NonUndefined<T>>>;
226
type _DeepRequiredObject<T> = { [P in keyof T]-?: DeepRequired<NonUndefined<T[P]>> };
227
228
type _DeepNonNullableArray<T> = Array<DeepNonNullable<NonNullable<T>>>;
229
type _DeepNonNullableObject<T> = { [P in keyof T]-?: DeepNonNullable<NonNullable<T[P]>> };
230
231
type _DeepPartial<T> = T extends Function
232
? T
233
: T extends ReadonlyArray<infer U>
234
? _DeepPartialArray<U>
235
: T extends object
236
? DeepPartial<T>
237
: T;
238
239
type _DeepPartialArray<T> = Array<_DeepPartial<T>>;
240
```