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
```