0
# ts-toolbelt
1

2
TypeScript's largest utility library providing 200+ type utilities for advanced type manipulation. It offers sophisticated type-level programming capabilities with mapped types, conditional types, and recursive types for performing complex transformations on objects, unions, functions, strings, numbers, and other TypeScript constructs.
3

4
## Package Information
5

6
- **Package Name**: ts-toolbelt
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ts-toolbelt`
10

11
## Core Imports
12

13
```typescript
14
import { A, Any, B, Boolean, C, Class, F, Function, L, List, N, Number, O, Object, S, String, U, Union } from "ts-toolbelt";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { A, Any, B, Boolean, C, Class, F, Function, L, List, N, Number, O, Object, S, String, U, Union } = require("ts-toolbelt");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { O, F, L, S } from "ts-toolbelt";
27

28
// Object manipulation
29
type User = { name: string; age: number; email: string };
30
type PartialUser = O.Partial<User>; // Make all properties optional
31
type PickedUser = O.Pick<User, "name" | "email">; // Pick specific properties
32

33
// Function composition and currying  
34
type Add = (a: number) => (b: number) => number;
35
type CurriedAdd = F.Curry<Add>; // Enable currying with placeholders
36

37
// List operations
38
type Numbers = [1, 2, 3, 4, 5];
39
type Reversed = L.Reverse<Numbers>; // [5, 4, 3, 2, 1]
40
type FirstTwo = L.Take<Numbers, 2>; // [1, 2]
41

42
// String manipulation
43
type Text = "hello-world";
44
type Parts = S.Split<Text, "-">; // ["hello", "world"]
45
type Length = S.Length<Text>; // 11
46
```
47

48
## Architecture
49

50
ts-toolbelt is built around several key principles:
51

52
- **Modular Design**: Each domain (Any, Boolean, Class, etc.) has its own module with dedicated `_api.ts` exports
53
- **Dual Exports**: Both shorthand (single letter) and full names for each module (e.g., `A`/`Any`, `O`/`Object`)
54
- **Performance Optimization**: Non-distributed versions available with `_` prefix for internal use
55
- **Type-Level Programming**: Comprehensive arithmetic, boolean logic, and complex transformations at the type level
56
- **Distribution Handling**: Careful management of type distribution across unions for correctness and performance
57

58
## Capabilities
59

60
### Any Module
61

62
Generic type utilities for fundamental type operations including casting, equality checking, and property access.
63

64
```typescript { .api }
65
// Core casting and type checking
66
type Cast<A1, A2> = A1 extends A2 ? A1 : A2;
67
type Equals<A1, A2> = (<A>() => A extends A1 ? 1 : 0) extends (<A>() => A extends A2 ? 1 : 0) ? 1 : 0;
68
type Extends<A, B> = A extends B ? 1 : 0;
69

70
// Property access and key operations
71
type At<O, K extends keyof O> = O[K];
72
type Keys<O> = keyof O;
73
type KnownKeys<O> = keyof O;
74

75
// Type computation control
76
type Compute<O extends Record<string, any>, depth extends 'flat' | 'deep' = 'flat'> = 
77
  depth extends 'flat' ? { [K in keyof O]: O[K] } & {} : ComputeDeep<O>;
78
```
79

80
[Any Module](./any.md)
81

82
### Boolean Module  
83

84
Type-level boolean logic operations using lookup tables for AND, OR, NOT, and XOR operations.
85

86
```typescript { .api }
87
type Boolean = 0 | 1;
88
type Not<B extends Boolean> = B extends 0 ? 1 : 0;
89
type And<B1 extends Boolean, B2 extends Boolean> = B1 extends 1 ? B2 : 0;
90
type Or<B1 extends Boolean, B2 extends Boolean> = B1 extends 1 ? 1 : B2;
91
type Xor<B1 extends Boolean, B2 extends Boolean> = B1 extends B2 ? 0 : 1;
92
```
93

94
[Boolean Module](./boolean.md)
95

96
### Class Module
97

98
Class-related utilities for extracting instance types and constructor parameters.
99

100
```typescript { .api }
101
type Class<A = any, P extends readonly any[] = any> = new (...args: P) => A;
102
type Instance<C extends Class> = C extends Class<infer I> ? I : never;
103
type Parameters<C extends Class> = C extends Class<any, infer P> ? P : never;
104
```
105

106
[Class Module](./class.md)
107

108
### Function Module
109

110
Advanced function manipulation including composition, currying, and piping with placeholder support.
111

112
```typescript { .api }
113
type Function<P extends readonly any[] = any, R = any> = (...args: P) => R;
114
type Parameters<F extends Function> = F extends Function<infer P> ? P : never;
115
type Return<F extends Function> = F extends Function<any, infer R> ? R : never;
116

117
// Advanced currying with placeholder support
118
type Curry<F extends Function> = F extends Function<infer P, infer R> 
119
  ? P extends readonly [] ? () => R 
120
  : CurryImpl<P, R> : never;
121

122
// Function composition and piping
123
type Compose<Fns extends readonly Function[]> = ComposeImpl<Fns>;
124
type Pipe<F extends Function, Fns extends readonly Function[]> = PipeImpl<F, Fns>;
125
```
126

127
[Function Module](./function.md)
128

129
### List Module
130

131
Comprehensive array and tuple manipulation - the largest module with 73+ operations.
132

133
```typescript { .api }
134
type List<A = any> = readonly A[];
135

136
// Core manipulation
137
type Append<L extends List, A> = [...L, A];
138
type Prepend<L extends List, A> = [A, ...L];
139
type Concat<L1 extends List, L2 extends List> = [...L1, ...L2];
140
type Reverse<L extends List> = ReverseImpl<L>;
141

142
// Access operations  
143
type At<L extends List, K extends number> = L[K];
144
type Head<L extends List> = L extends readonly [infer H, ...any[]] ? H : never;
145
type Tail<L extends List> = L extends readonly [any, ...infer T] ? T : never;
146
type Last<L extends List> = L extends readonly [...any[], infer L] ? L : never;
147

148
// Transformation operations
149
type Filter<L extends List, M> = FilterImpl<L, M>;
150
type Map<L extends List, F> = MapImpl<L, F>;
151
type Zip<L1 extends List, L2 extends List> = ZipImpl<L1, L2>;
152
```
153

154
[List Module](./list.md)
155

156
### Number Module
157

158
Type-level arithmetic operations using an internal iteration system supporting operations from -100 to 100.
159

160
```typescript { .api }
161
type Add<N1 extends number, N2 extends number> = AddImpl<N1, N2>;
162
type Sub<N1 extends number, N2 extends number> = SubImpl<N1, N2>;
163
type Absolute<N extends number> = AbsoluteImpl<N>;
164
type Negate<N extends number> = NegateImpl<N>;
165

166
// Comparison operations
167
type Greater<N1 extends number, N2 extends number> = GreaterImpl<N1, N2>;
168
type GreaterEq<N1 extends number, N2 extends number> = GreaterEqImpl<N1, N2>;
169
type Lower<N1 extends number, N2 extends number> = LowerImpl<N1, N2>;
170
type LowerEq<N1 extends number, N2 extends number> = LowerEqImpl<N1, N2>;
171

172
// Utility checks
173
type IsZero<N extends number> = N extends 0 ? 1 : 0;
174
type IsPositive<N extends number> = IsPositiveImpl<N>;
175
type IsNegative<N extends number> = IsNegativeImpl<N>;
176
```
177

178
[Number Module](./number.md)
179

180
### Object Module
181

182
Extensive object manipulation utilities with deep property operations and path-based access.
183

184
```typescript { .api }
185
type Object = Record<string | number | symbol, any>;
186

187
// Property access
188
type At<O extends Object, K extends keyof O> = O[K];
189
type Keys<O extends Object> = keyof O;
190
type Values<O extends Object> = O[keyof O];
191
type Paths<O extends Object> = PathsImpl<O>;
192

193
// Core transformations
194
type Pick<O extends Object, K extends keyof O> = { [P in K]: O[P] } & {};
195
type Omit<O extends Object, K extends keyof O> = Pick<O, Exclude<keyof O, K>>;
196
type Merge<O1 extends Object, O2 extends Object, depth extends 'flat' | 'deep' = 'flat'> = 
197
  depth extends 'flat' ? O1 & O2 : MergeDeep<O1, O2>;
198

199
// Property modifications
200
type Partial<O extends Object> = { [K in keyof O]?: O[K] };
201
type Required<O extends Object> = { [K in keyof O]-?: O[K] };
202
type Readonly<O extends Object> = { readonly [K in keyof O]: O[K] };
203
type Writable<O extends Object> = { -readonly [K in keyof O]: O[K] };
204
```
205

206
[Object Module](./object.md)
207

208
### String Module
209

210
Template literal-based string manipulation utilities.
211

212
```typescript { .api }
213
type At<S extends string, N extends number> = AtImpl<S, N>;
214
type Length<S extends string> = LengthImpl<S>;
215
type Split<S extends string, D extends string> = S extends `${infer B}${D}${infer A}` 
216
  ? [B, ...Split<A, D>] : [S];
217
type Join<L extends readonly string[], D extends string> = JoinImpl<L, D>;
218
type Replace<S extends string, From extends string, To extends string> = 
219
  S extends `${infer B}${From}${infer A}` ? `${B}${To}${Replace<A, From, To>}` : S;
220
```
221

222
[String Module](./string.md)
223

224
### Union Module
225

226
Union type operations including set operations, filtering, and transformations.
227

228
```typescript { .api }
229
// Set operations
230
type Exclude<U, E> = U extends E ? never : U;
231
type Extract<U, E> = U extends E ? U : never;
232
type Intersect<U1, U2> = Extract<U1, U2>;
233
type Diff<U1, U2> = Exclude<U1, U2>;
234

235
// Transformations
236
type Strict<U> = StrictImpl<U>;
237
type Merge<U> = MergeImpl<U>;
238
type IntersectOf<U> = IntersectOfImpl<U>;
239
type ListOf<U> = ListOfImpl<U>;
240

241
// Utilities
242
type Has<U, A> = A extends U ? 1 : 0;
243
type Last<U> = LastImpl<U>;
244
type Pop<U> = PopImpl<U>;
245
```
246

247
[Union Module](./union.md)
248

249
### Testing Module
250

251
Built-in type testing utilities for validating type transformations.
252

253
```typescript { .api }
254
type Pass = 1;
255
type Fail = 0;
256

257
declare function check<Type, Expect, Outcome extends Boolean>(
258
  debug?: Equals<Equals<Type, Expect>, Outcome>
259
): Equals<Equals<Type, Expect>, Outcome>;
260

261
declare function checks(checks: 1[]): void;
262
```
263

264
[Testing Module](./testing.md)
265

266
### Community Module
267

268
Community-contributed utilities for deep inclusion checking and literal type validation.
269

270
```typescript { .api }
271
type IncludesDeep<T, U> = IncludesDeepImpl<T, U>;
272
type IsLiteral<T> = IsLiteralImpl<T>;
273
```
274

275
[Community Module](./community.md)
276

277
### Misc Module
278

279
Miscellaneous utilities including built-in types, primitives, and JSON handling.
280

281
```typescript { .api }
282
type BuiltIn = Function | Error | Date | { readonly [Symbol.toStringTag]: string } | RegExp | Generator;
283
type Primitive = string | number | boolean | bigint | symbol | undefined | null;
284

285
namespace JSON {
286
  type Primitive = string | number | boolean | null;
287
  type Array = Value[];
288
  type Object = { [key: string]: Value };
289
  type Value = Primitive | Object | Array;
290
}
291
```
292

293
[Misc Module](./misc.md)
294

295
### Iteration Module
296

297
Internal iteration system providing type-level arithmetic infrastructure.
298

299
```typescript { .api }
300
type Iteration = [number, '-' | '0' | '+', IterationKey, IterationKey, IterationKey];
301
type IterationOf<N extends number> = IterationOfImpl<N>;
302
type Next<I extends Iteration> = NextImpl<I>;
303
type Prev<I extends Iteration> = PrevImpl<I>;
304
type Pos<I extends Iteration> = PosImpl<I>;
305
type Key = string;
306
```
307

308
[Iteration Module](./iteration.md)
309

310
## Types
311

312
```typescript { .api }
313
// Core utility types used across modules
314
type Key = string | number | symbol;
315
type Boolean = 0 | 1;
316
type List<A = any> = readonly A[];
317
type Object = Record<Key, any>;
318
type Function<P extends readonly any[] = any, R = any> = (...args: P) => R;
319
type BuiltIn = Function | Error | Date | { readonly [Symbol.toStringTag]: string } | RegExp | Generator;
320
type Primitive = string | number | boolean | bigint | symbol | undefined | null;
321
```