0
# JavaScript Types
1

2
Types that represent JavaScript runtime constructs like functions, constructors, dates, and other built-in objects. These types extend JSON Schema to support JavaScript-specific validation scenarios.
3

4
## Capabilities
5

6
### Function Type
7

8
Creates a function type with parameter and return type validation.
9

10
```typescript { .api }
11
/**
12
 * Creates a function type with parameter and return type validation
13
 * @param parameters - Array of parameter schemas
14
 * @param returns - Return value schema
15
 * @returns TFunction schema
16
 */
17
function Function<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TFunction<P, R>;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { Type } from "@sinclair/typebox";
24

25
// Simple function: (x: number, y: number) => number
26
const AddFunction = Type.Function([Type.Number(), Type.Number()], Type.Number());
27

28
// Function with optional parameters
29
const LogFunction = Type.Function([
30
  Type.String(),
31
  Type.Optional(Type.Object({ level: Type.String() }))
32
], Type.Void());
33

34
// Async function returning Promise
35
const FetchFunction = Type.Function([Type.String()], Type.Promise(Type.Object({
36
  status: Type.Number(),
37
  data: Type.Any()
38
})));
39
```
40

41
### Constructor Type
42

43
Creates a constructor function type.
44

45
```typescript { .api }
46
/**
47
 * Creates a constructor function type
48
 * @param parameters - Array of constructor parameter schemas
49
 * @param returns - Instance type schema
50
 * @returns TConstructor schema
51
 */
52
function Constructor<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TConstructor<P, R>;
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
// Constructor for a User class
59
const UserConstructor = Type.Constructor([
60
  Type.String(), // name
61
  Type.Number()  // age
62
], Type.Object({
63
  name: Type.String(),
64
  age: Type.Number(),
65
  id: Type.String()
66
}));
67
```
68

69
### Constructor and Function Utility Types
70

71
Extracts parameter and return types from functions and constructors.
72

73
```typescript { .api }
74
/**
75
 * Extracts constructor parameters from Constructor type
76
 * @param schema - Constructor schema
77
 * @returns TConstructorParameters schema
78
 */
79
function ConstructorParameters<T extends TConstructor>(schema: T): TConstructorParameters<T>;
80

81
/**
82
 * Extracts instance type from Constructor type
83
 * @param schema - Constructor schema
84
 * @returns TInstanceType schema
85
 */
86
function InstanceType<T extends TConstructor>(schema: T): TInstanceType<T>;
87

88
/**
89
 * Extracts parameters from Function type
90
 * @param schema - Function schema
91
 * @returns TParameters schema
92
 */
93
function Parameters<T extends TFunction>(schema: T): TParameters<T>;
94

95
/**
96
 * Extracts return type from Function type
97
 * @param schema - Function schema
98
 * @returns TReturnType schema
99
 */
100
function ReturnType<T extends TFunction>(schema: T): TReturnType<T>;
101
```
102

103
### Date Type
104

105
Creates a Date type with timestamp validation.
106

107
```typescript { .api }
108
/**
109
 * Creates a Date type with timestamp validation
110
 * @param options - Date validation options
111
 * @returns TDate schema
112
 */
113
function Date(options?: DateOptions): TDate;
114

115
interface DateOptions extends SchemaOptions {
116
  minimum?: number | string | Date;
117
  maximum?: number | string | Date;
118
  exclusiveMinimum?: number | string | Date;
119
  exclusiveMaximum?: number | string | Date;
120
}
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
// Basic date
127
const CreatedAt = Type.Date();
128

129
// Date with range constraints
130
const FutureDate = Type.Date({ 
131
  minimum: new Date().toISOString() 
132
});
133

134
// Date with both bounds
135
const EventDate = Type.Date({
136
  minimum: '2024-01-01T00:00:00Z',
137
  maximum: '2024-12-31T23:59:59Z'
138
});
139
```
140

141
### Promise Type
142

143
Creates a Promise type with inner type validation.
144

145
```typescript { .api }
146
/**
147
 * Creates a Promise type with inner type validation
148
 * @param item - Schema for the resolved value
149
 * @returns TPromise schema
150
 */
151
function Promise<T extends TSchema>(item: T): TPromise<T>;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
// Promise that resolves to string
158
const StringPromise = Type.Promise(Type.String());
159

160
// Promise that resolves to object
161
const UserPromise = Type.Promise(Type.Object({
162
  id: Type.String(),
163
  name: Type.String()
164
}));
165

166
// Promise that resolves to array
167
const ItemsPromise = Type.Promise(Type.Array(Type.String()));
168
```
169

170
### Awaited Type
171

172
Unwraps Promise types recursively.
173

174
```typescript { .api }
175
/**
176
 * Unwraps Promise types recursively
177
 * @param schema - Promise schema to unwrap
178
 * @returns TAwaited schema
179
 */
180
function Awaited<T extends TSchema>(schema: T): TAwaited<T>;
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
const NestedPromise = Type.Promise(Type.Promise(Type.String()));
187
const UnwrappedType = Type.Awaited(NestedPromise);
188
// Result: string (fully unwrapped)
189
```
190

191
### RegExp Type
192

193
Creates a RegExp type for pattern matching.
194

195
```typescript { .api }
196
/**
197
 * Creates a RegExp type for pattern matching
198
 * @param source - Regular expression source
199
 * @param flags - Regular expression flags
200
 * @returns TRegExp schema
201
 */
202
function RegExp(source: string, flags?: string): TRegExp;
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
// Email pattern
209
const EmailRegex = Type.RegExp('^[\\w-\\.]+@[\\w-]+\\.[a-z]{2,}$', 'i');
210

211
// Phone number pattern
212
const PhoneRegex = Type.RegExp('^\\+?[1-9]\\d{1,14}$');
213

214
// UUID pattern
215
const UuidRegex = Type.RegExp('^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', 'i');
216
```
217

218
### BigInt Type
219

220
Creates a BigInt type for large integer values.
221

222
```typescript { .api }
223
/**
224
 * Creates a BigInt type
225
 * @param options - BigInt validation options
226
 * @returns TBigInt schema
227
 */
228
function BigInt(options?: BigIntOptions): TBigInt;
229

230
interface BigIntOptions extends SchemaOptions {
231
  minimum?: bigint;
232
  maximum?: bigint;
233
  exclusiveMinimum?: bigint;
234
  exclusiveMaximum?: bigint;
235
  multipleOf?: bigint;
236
}
237
```
238

239
**Usage Examples:**
240

241
```typescript
242
// Basic BigInt
243
const LargeNumber = Type.BigInt();
244

245
// BigInt with constraints
246
const PositiveBigInt = Type.BigInt({ minimum: 0n });
247

248
// BigInt with range
249
const TimestampBigInt = Type.BigInt({
250
  minimum: 0n,
251
  maximum: 9223372036854775807n // Max safe BigInt
252
});
253
```
254

255
### Symbol Type
256

257
Creates a Symbol type for unique identifiers.
258

259
```typescript { .api }
260
/**
261
 * Creates a Symbol type
262
 * @param options - Schema options
263
 * @returns TSymbol schema
264
 */
265
function Symbol(options?: SchemaOptions): TSymbol;
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
// Basic symbol
272
const UniqueKey = Type.Symbol();
273

274
// Symbol with description
275
const EventSymbol = Type.Symbol({ 
276
  description: 'Unique event identifier' 
277
});
278
```
279

280
### Uint8Array Type
281

282
Creates a Uint8Array type for binary data.
283

284
```typescript { .api }
285
/**
286
 * Creates a Uint8Array type with byte length validation
287
 * @param options - Uint8Array validation options
288
 * @returns TUint8Array schema
289
 */
290
function Uint8Array(options?: Uint8ArrayOptions): TUint8Array;
291

292
interface Uint8ArrayOptions extends SchemaOptions {
293
  minByteLength?: number;
294
  maxByteLength?: number;
295
}
296
```
297

298
**Usage Examples:**
299

300
```typescript
301
// Basic Uint8Array
302
const BinaryData = Type.Uint8Array();
303

304
// Uint8Array with length constraints
305
const Hash = Type.Uint8Array({ 
306
  minByteLength: 32, 
307
  maxByteLength: 32 
308
});
309

310
// Small buffer
311
const SmallBuffer = Type.Uint8Array({ maxByteLength: 1024 });
312
```
313

314
### Iterator Types
315

316
Creates Iterator and AsyncIterator types.
317

318
```typescript { .api }
319
/**
320
 * Creates an Iterator type
321
 * @param items - Schema for iterator values
322
 * @returns TIterator schema
323
 */
324
function Iterator<T extends TSchema>(items: T): TIterator<T>;
325

326
/**
327
 * Creates an AsyncIterator type
328
 * @param items - Schema for async iterator values
329
 * @returns TAsyncIterator schema
330
 */
331
function AsyncIterator<T extends TSchema>(items: T): TAsyncIterator<T>;
332
```
333

334
**Usage Examples:**
335

336
```typescript
337
// Iterator of strings
338
const StringIterator = Type.Iterator(Type.String());
339

340
// AsyncIterator of objects
341
const UserIterator = Type.AsyncIterator(Type.Object({
342
  id: Type.String(),
343
  name: Type.String()
344
}));
345
```
346

347
### Void Type
348

349
Creates a Void type (undefined or null based on policy).
350

351
```typescript { .api }
352
/**
353
 * Creates a Void type
354
 * @param options - Schema options
355
 * @returns TVoid schema
356
 */
357
function Void(options?: SchemaOptions): TVoid;
358
```
359

360
**Usage Examples:**
361

362
```typescript
363
// Basic void (for function returns)
364
const VoidReturn = Type.Void();
365

366
// Function that returns void
367
const LoggerFunction = Type.Function([Type.String()], Type.Void());
368
```
369

370
## Type Interfaces
371

372
```typescript { .api }
373
interface TFunction<P extends TSchema[], R extends TSchema> extends TSchema {
374
  type: 'function';
375
  parameters: P;
376
  returns: R;
377
}
378

379
interface TConstructor<P extends TSchema[], R extends TSchema> extends TSchema {
380
  type: 'constructor';
381
  parameters: P;
382
  returns: R;
383
}
384

385
interface TDate extends TSchema {
386
  type: 'date';
387
  minimum?: number | string;
388
  maximum?: number | string;
389
  exclusiveMinimum?: number | string;
390
  exclusiveMaximum?: number | string;
391
}
392

393
interface TPromise<T extends TSchema> extends TSchema {
394
  type: 'promise';
395
  item: T;
396
}
397

398
interface TRegExp extends TSchema {
399
  type: 'regexp';
400
  source: string;
401
  flags?: string;
402
}
403

404
interface TBigInt extends TSchema {
405
  type: 'bigint';
406
  minimum?: bigint;
407
  maximum?: bigint;
408
  exclusiveMinimum?: bigint;
409
  exclusiveMaximum?: bigint;
410
  multipleOf?: bigint;
411
}
412

413
interface TSymbol extends TSchema {
414
  type: 'symbol';
415
}
416

417
interface TUint8Array extends TSchema {
418
  type: 'uint8array';
419
  minByteLength?: number;
420
  maxByteLength?: number;
421
}
422

423
interface TIterator<T extends TSchema> extends TSchema {
424
  type: 'iterator';
425
  items: T;
426
}
427

428
interface TAsyncIterator<T extends TSchema> extends TSchema {
429
  type: 'async-iterator';
430
  items: T;
431
}
432

433
interface TVoid extends TSchema {
434
  type: 'void';
435
}
436

437
// Utility type interfaces
438
interface TConstructorParameters<T extends TConstructor> extends TSchema {
439
  type: 'tuple';
440
  items: T['parameters'];
441
}
442

443
interface TInstanceType<T extends TConstructor> extends TSchema {
444
  [Kind]: 'InstanceType';
445
  type: T['returns']['type'];
446
}
447

448
interface TParameters<T extends TFunction> extends TSchema {
449
  type: 'tuple';
450
  items: T['parameters'];
451
}
452

453
interface TReturnType<T extends TFunction> extends TSchema {
454
  [Kind]: 'ReturnType';
455
  type: T['returns']['type'];
456
}
457

458
interface TAwaited<T extends TSchema> extends TSchema {
459
  [Kind]: 'Awaited';
460
  // Recursively unwraps Promise types
461
}
462
```