@sinclair/typebox 0.21.2 → 0.23.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +8 -8
- package/readme.md +209 -256
- package/typebox.d.ts +182 -144
- package/typebox.js +149 -114
package/readme.md
CHANGED
|
@@ -2,8 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
<h1>TypeBox</h1>
|
|
4
4
|
|
|
5
|
+
<img src="https://github.com/sinclairzx81/typebox/blob/master/typebox.png?raw=true" />
|
|
6
|
+
|
|
5
7
|
<p>JSON Schema Type Builder with Static Type Resolution for TypeScript</p>
|
|
6
8
|
|
|
9
|
+
|
|
10
|
+
|
|
7
11
|
[](https://badge.fury.io/js/%40sinclair%2Ftypebox) [](https://github.com/sinclairzx81/typebox/actions)
|
|
8
12
|
|
|
9
13
|
</div>
|
|
@@ -24,7 +28,7 @@ $ npm install @sinclair/typebox --save
|
|
|
24
28
|
import { Static, Type } from 'https://deno.land/x/typebox/src/typebox.ts'
|
|
25
29
|
```
|
|
26
30
|
|
|
27
|
-
##
|
|
31
|
+
## Example
|
|
28
32
|
|
|
29
33
|
```typescript
|
|
30
34
|
import { Static, Type } from '@sinclair/typebox'
|
|
@@ -38,7 +42,7 @@ type T = Static<typeof T> // type T = string
|
|
|
38
42
|
|
|
39
43
|
## Overview
|
|
40
44
|
|
|
41
|
-
TypeBox is a library that
|
|
45
|
+
TypeBox is a library that creates in-memory JSON Schema objects that can be statically inferred as TypeScript types. The schemas produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox allows one to create a unified type that can be both statically asserted by the TypeScript compiler and runtime asserted using industry standard JSON Schema validation.
|
|
42
46
|
|
|
43
47
|
TypeBox can be used as a simple tool to build up complex schemas or integrated into RPC or REST services to help validate JSON data received over the wire. TypeBox does not provide any JSON schema validation. Please use libraries such as AJV to validate schemas built with this library.
|
|
44
48
|
|
|
@@ -49,7 +53,7 @@ License MIT
|
|
|
49
53
|
## Contents
|
|
50
54
|
- [Install](#Install)
|
|
51
55
|
- [Overview](#Overview)
|
|
52
|
-
- [
|
|
56
|
+
- [Usage](#Usage)
|
|
53
57
|
- [Types](#Types)
|
|
54
58
|
- [Modifiers](#Modifiers)
|
|
55
59
|
- [Options](#Options)
|
|
@@ -63,7 +67,7 @@ License MIT
|
|
|
63
67
|
|
|
64
68
|
<a name="Example"></a>
|
|
65
69
|
|
|
66
|
-
##
|
|
70
|
+
## Usage
|
|
67
71
|
|
|
68
72
|
The following demonstrates TypeBox's general usage.
|
|
69
73
|
|
|
@@ -89,25 +93,25 @@ type T = {
|
|
|
89
93
|
//
|
|
90
94
|
//--------------------------------------------------------------------------------------------
|
|
91
95
|
|
|
92
|
-
const T = Type.Object({
|
|
93
|
-
id: Type.String(),
|
|
94
|
-
name: Type.String(),
|
|
95
|
-
timestamp: Type.Integer()
|
|
96
|
-
})
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
96
|
+
const T = Type.Object({ // const T = {
|
|
97
|
+
id: Type.String(), // type: 'object',
|
|
98
|
+
name: Type.String(), // properties: {
|
|
99
|
+
timestamp: Type.Integer() // id: {
|
|
100
|
+
}) // type: 'string'
|
|
101
|
+
// },
|
|
102
|
+
// name: {
|
|
103
|
+
// type: 'string'
|
|
104
|
+
// },
|
|
105
|
+
// timestamp: {
|
|
106
|
+
// type: 'integer'
|
|
107
|
+
// }
|
|
108
|
+
// },
|
|
109
|
+
// required: [
|
|
110
|
+
// "id",
|
|
111
|
+
// "name",
|
|
112
|
+
// "timestamp"
|
|
113
|
+
// ]
|
|
114
|
+
// }
|
|
111
115
|
|
|
112
116
|
//--------------------------------------------------------------------------------------------
|
|
113
117
|
//
|
|
@@ -115,11 +119,11 @@ const T = Type.Object({ // const T = {
|
|
|
115
119
|
//
|
|
116
120
|
//--------------------------------------------------------------------------------------------
|
|
117
121
|
|
|
118
|
-
type T = Static<typeof T>
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
122
|
+
type T = Static<typeof T> // type T = {
|
|
123
|
+
// id: string,
|
|
124
|
+
// name: string,
|
|
125
|
+
// timestamp: number
|
|
126
|
+
// }
|
|
123
127
|
|
|
124
128
|
//--------------------------------------------------------------------------------------------
|
|
125
129
|
//
|
|
@@ -127,9 +131,9 @@ type T = Static<typeof T> // type T = {
|
|
|
127
131
|
//
|
|
128
132
|
//--------------------------------------------------------------------------------------------
|
|
129
133
|
|
|
130
|
-
function receive(value: T) {
|
|
134
|
+
function receive(value: T) { // ... as a Type
|
|
131
135
|
|
|
132
|
-
if(JSON.validate(T, value)) {
|
|
136
|
+
if(JSON.validate(T, value)) { // ... as a Schema
|
|
133
137
|
|
|
134
138
|
// ok...
|
|
135
139
|
}
|
|
@@ -145,50 +149,50 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
145
149
|
```typescript
|
|
146
150
|
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
|
|
147
151
|
│ TypeBox │ TypeScript │ JSON Schema │
|
|
148
|
-
│
|
|
152
|
+
│ │ │ │
|
|
149
153
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
150
154
|
│ const T = Type.Any() │ type T = any │ const T = { } │
|
|
151
|
-
│
|
|
155
|
+
│ │ │ │
|
|
152
156
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
153
157
|
│ const T = Type.Unknown() │ type T = unknown │ const T = { } │
|
|
154
|
-
│
|
|
158
|
+
│ │ │ │
|
|
155
159
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
156
160
|
│ const T = Type.String() │ type T = string │ const T = { │
|
|
157
161
|
│ │ │ type: 'string' │
|
|
158
162
|
│ │ │ } │
|
|
159
|
-
│
|
|
163
|
+
│ │ │ │
|
|
160
164
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
161
165
|
│ const T = Type.Number() │ type T = number │ const T = { │
|
|
162
166
|
│ │ │ type: 'number' │
|
|
163
167
|
│ │ │ } │
|
|
164
|
-
│
|
|
168
|
+
│ │ │ │
|
|
165
169
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
166
170
|
│ const T = Type.Integer() │ type T = number │ const T = { │
|
|
167
171
|
│ │ │ type: 'integer' │
|
|
168
172
|
│ │ │ } │
|
|
169
|
-
│
|
|
173
|
+
│ │ │ │
|
|
170
174
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
171
175
|
│ const T = Type.Boolean() │ type T = boolean │ const T = { │
|
|
172
176
|
│ │ │ type: 'boolean' │
|
|
173
177
|
│ │ │ } │
|
|
174
|
-
│
|
|
178
|
+
│ │ │ │
|
|
175
179
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
176
180
|
│ const T = Type.Null() │ type T = null │ const T = { │
|
|
177
181
|
│ │ │ type: 'null' │
|
|
178
182
|
│ │ │ } │
|
|
179
|
-
│
|
|
183
|
+
│ │ │ │
|
|
180
184
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
181
|
-
│ const T = Type.RegEx(/foo/)
|
|
185
|
+
│ const T = Type.RegEx(/foo/) │ type T = string │ const T = { │
|
|
182
186
|
│ │ │ type: 'string', │
|
|
183
187
|
│ │ │ pattern: 'foo' │
|
|
184
188
|
│ │ │ } │
|
|
185
|
-
│
|
|
189
|
+
│ │ │ │
|
|
186
190
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
187
191
|
│ const T = Type.Literal(42) │ type T = 42 │ const T = { │
|
|
188
192
|
│ │ │ const: 42 │
|
|
189
193
|
│ │ │ type: 'number' │
|
|
190
194
|
│ │ │ } │
|
|
191
|
-
│
|
|
195
|
+
│ │ │ │
|
|
192
196
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
193
197
|
│ const T = Type.Array( │ type T = number[] │ const T = { │
|
|
194
198
|
│ Type.Number() │ │ type: 'array', │
|
|
@@ -196,36 +200,36 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
196
200
|
│ │ │ type: 'number' │
|
|
197
201
|
│ │ │ } │
|
|
198
202
|
│ │ │ } │
|
|
199
|
-
│
|
|
203
|
+
│ │ │ │
|
|
200
204
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
201
205
|
│ const T = Type.Object({ │ type T = { │ const T = { │
|
|
202
206
|
│ x: Type.Number(), │ x: number, │ type: 'object', │
|
|
203
207
|
│ y: Type.Number() │ y: number │ properties: { │
|
|
204
208
|
│ }) │ } │ x: { │
|
|
205
209
|
│ │ │ type: 'number' │
|
|
206
|
-
│
|
|
207
|
-
│
|
|
208
|
-
│
|
|
210
|
+
│ │ │ }, │
|
|
211
|
+
│ │ │ y: { │
|
|
212
|
+
│ │ │ type: 'number' │
|
|
209
213
|
│ │ │ } │
|
|
210
|
-
│
|
|
211
|
-
│
|
|
214
|
+
│ │ │ }, │
|
|
215
|
+
│ │ │ required: ['x', 'y'] │
|
|
212
216
|
│ │ │ } │
|
|
213
|
-
│
|
|
217
|
+
│ │ │ │
|
|
214
218
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
215
219
|
│ const T = Type.Tuple([ │ type T = [number, number] │ const T = { │
|
|
216
220
|
│ Type.Number(), │ │ type: 'array', │
|
|
217
221
|
│ Type.Number() │ │ items: [ │
|
|
218
222
|
│ ]) │ │ { │
|
|
219
|
-
│
|
|
220
|
-
│
|
|
221
|
-
│
|
|
222
|
-
│
|
|
223
|
-
│
|
|
224
|
-
│
|
|
225
|
-
│
|
|
226
|
-
│
|
|
227
|
-
│
|
|
228
|
-
│
|
|
223
|
+
│ │ │ type: 'number' │
|
|
224
|
+
│ │ │ }, { │
|
|
225
|
+
│ │ │ type: 'number' │
|
|
226
|
+
│ │ │ } │
|
|
227
|
+
│ │ │ ], │
|
|
228
|
+
│ │ │ additionalItems: false, │
|
|
229
|
+
│ │ │ minItems: 2, │
|
|
230
|
+
│ │ │ maxItems: 2, │
|
|
231
|
+
│ │ │ } │
|
|
232
|
+
│ │ │ │
|
|
229
233
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
230
234
|
│ enum Foo { │ enum Foo { │ const T = { │
|
|
231
235
|
│ A, │ A, │ anyOf: [{ │
|
|
@@ -244,7 +248,7 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
244
248
|
│ y: Type.Number() │ } │ } │
|
|
245
249
|
│ }) │ │ │
|
|
246
250
|
│ ) │ │ │
|
|
247
|
-
│
|
|
251
|
+
│ │ │ │
|
|
248
252
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
249
253
|
│ const T = Type.Union([ │ type T = string | number │ const T = { │
|
|
250
254
|
│ Type.String(), │ │ anyOf: [{ │
|
|
@@ -253,14 +257,14 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
253
257
|
│ │ │ type: 'number' │
|
|
254
258
|
│ │ │ }] │
|
|
255
259
|
│ │ │ } │
|
|
256
|
-
│
|
|
260
|
+
│ │ │ │
|
|
257
261
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
258
262
|
│ const T = Type.Intersect([ │ type T = { │ const T = { │
|
|
259
263
|
│ Type.Object({ │ x: number │ allOf: [{ │
|
|
260
264
|
│ x: Type.Number() │ } & { │ type: 'object', │
|
|
261
265
|
│ }), │ y: number │ properties: { │
|
|
262
266
|
│ Type.Object({ │ } │ a: { │
|
|
263
|
-
│ y: Type.Number() │ │ type: 'number' │
|
|
267
|
+
│ y: Type.Number() │ │ type: 'number' │
|
|
264
268
|
│ }) │ │ } │
|
|
265
269
|
│ }) │ │ }, │
|
|
266
270
|
│ │ │ required: ['a'] │
|
|
@@ -268,23 +272,23 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
268
272
|
│ │ │ type: 'object', │
|
|
269
273
|
│ │ │ properties: { │
|
|
270
274
|
│ │ │ b: { │
|
|
271
|
-
│
|
|
272
|
-
│
|
|
273
|
-
│
|
|
274
|
-
│
|
|
275
|
-
│
|
|
276
|
-
│
|
|
277
|
-
│
|
|
275
|
+
│ │ │ type: 'number' │
|
|
276
|
+
│ │ │ } │
|
|
277
|
+
│ │ │ }, │
|
|
278
|
+
│ │ │ required: ['b'] │
|
|
279
|
+
│ │ │ }] │
|
|
280
|
+
│ │ │ } │
|
|
281
|
+
│ │ │ │
|
|
278
282
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
279
283
|
│ const T = Type.Record( │ type T = { │ const T = { │
|
|
280
284
|
│ Type.String(), │ [key: string]: number │ type: 'object', │
|
|
281
285
|
│ Type.Number() │ } │ patternProperties: { │
|
|
282
|
-
│ )
|
|
283
|
-
│
|
|
284
|
-
│
|
|
285
|
-
│
|
|
286
|
-
│
|
|
287
|
-
│
|
|
286
|
+
│ ) │ │ '^.*$': { │
|
|
287
|
+
│ │ │ type: 'number' │
|
|
288
|
+
│ │ │ } │
|
|
289
|
+
│ │ │ } │
|
|
290
|
+
│ │ │ } │
|
|
291
|
+
│ │ │ │
|
|
288
292
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
289
293
|
│ const T = Type.Partial( │ type T = Partial<{ │ const T = { │
|
|
290
294
|
│ Type.Object({ │ x: number, │ type: 'object', │
|
|
@@ -297,7 +301,7 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
297
301
|
│ │ │ } │
|
|
298
302
|
│ │ │ } │
|
|
299
303
|
│ │ │ } │
|
|
300
|
-
│
|
|
304
|
+
│ │ │ │
|
|
301
305
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
302
306
|
│ const T = Type.Required( │ type T = Required<{ │ const T = { │
|
|
303
307
|
│ Type.Object({ │ x?: number, │ type: 'object', │
|
|
@@ -311,7 +315,7 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
|
|
|
311
315
|
│ ) │ │ }, │
|
|
312
316
|
│ │ │ required: ['x', 'y'] │
|
|
313
317
|
│ │ │ } │
|
|
314
|
-
│
|
|
318
|
+
│ │ │ │
|
|
315
319
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
316
320
|
│ const T = Type.Pick( │ type T = Pick<{ │ const T = { │
|
|
317
321
|
│ Type.Object({ │ x: number, │ type: 'object', │
|
|
@@ -345,38 +349,38 @@ TypeBox provides modifiers that can be applied to an objects properties. This al
|
|
|
345
349
|
```typescript
|
|
346
350
|
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
|
|
347
351
|
│ TypeBox │ TypeScript │ JSON Schema │
|
|
348
|
-
│
|
|
352
|
+
│ │ │ │
|
|
349
353
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
350
354
|
│ const T = Type.Object({ │ type T = { │ const T = { │
|
|
351
355
|
│ name: Type.Optional( │ name?: string, │ type: 'object', │
|
|
352
356
|
│ Type.String(), │ } │ properties: { │
|
|
353
|
-
│ )
|
|
357
|
+
│ ) │ │ name: { │
|
|
354
358
|
│ }) │ │ type: 'string' │
|
|
355
|
-
│
|
|
356
|
-
│
|
|
357
|
-
│
|
|
358
|
-
│
|
|
359
|
+
│ │ │ } │
|
|
360
|
+
│ │ │ } │
|
|
361
|
+
│ │ │ } │
|
|
362
|
+
│ │ │ │
|
|
359
363
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
360
364
|
│ const T = Type.Object({ │ type T = { │ const T = { │
|
|
361
365
|
│ name: Type.Readonly( │ readonly name: string, │ type: 'object', │
|
|
362
366
|
│ Type.String(), │ } │ properties: { │
|
|
363
|
-
│ )
|
|
367
|
+
│ ) │ │ name: { │
|
|
364
368
|
│ }) │ │ type: 'string' │
|
|
365
|
-
│
|
|
366
|
-
│
|
|
369
|
+
│ │ │ } │
|
|
370
|
+
│ │ │ }, │
|
|
367
371
|
│ │ │ required: ['name'] │
|
|
368
|
-
│
|
|
369
|
-
│
|
|
372
|
+
│ │ │ } │
|
|
373
|
+
│ │ │ │
|
|
370
374
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
371
375
|
│ const T = Type.Object({ │ type T = { │ const T = { │
|
|
372
376
|
│ name: Type.ReadonlyOptional( │ readonly name?: string, │ type: 'object', │
|
|
373
377
|
│ Type.String(), │ } │ properties: { │
|
|
374
|
-
│ )
|
|
378
|
+
│ ) │ │ name: { │
|
|
375
379
|
│ }) │ │ type: 'string' │
|
|
376
|
-
│
|
|
377
|
-
│
|
|
380
|
+
│ │ │ } │
|
|
381
|
+
│ │ │ } │
|
|
378
382
|
│ │ │ } │
|
|
379
|
-
│
|
|
383
|
+
│ │ │ │
|
|
380
384
|
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
|
|
381
385
|
```
|
|
382
386
|
|
|
@@ -409,25 +413,25 @@ import { Type, Static, TSchema } from '@sinclair/typebox'
|
|
|
409
413
|
|
|
410
414
|
const Nullable = <T extends TSchema>(type: T) => Type.Union([type, Type.Null()])
|
|
411
415
|
|
|
412
|
-
const T = Nullable(Type.String())
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
type T = Static<typeof T>
|
|
421
|
-
|
|
422
|
-
const U = Nullable(Type.Number())
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
type U = Static<typeof U>
|
|
416
|
+
const T = Nullable(Type.String()) // const T = {
|
|
417
|
+
// "anyOf": [{
|
|
418
|
+
// type: 'string'
|
|
419
|
+
// }, {
|
|
420
|
+
// type: 'null'
|
|
421
|
+
// }]
|
|
422
|
+
// }
|
|
423
|
+
|
|
424
|
+
type T = Static<typeof T> // type T = string | null
|
|
425
|
+
|
|
426
|
+
const U = Nullable(Type.Number()) // const U = {
|
|
427
|
+
// "anyOf": [{
|
|
428
|
+
// type: 'number'
|
|
429
|
+
// }, {
|
|
430
|
+
// type: 'null'
|
|
431
|
+
// }]
|
|
432
|
+
// }
|
|
433
|
+
|
|
434
|
+
type U = Static<typeof U> // type U = number | null
|
|
431
435
|
```
|
|
432
436
|
|
|
433
437
|
<a name="Reference-Types"></a>
|
|
@@ -437,61 +441,61 @@ type U = Static<typeof U> // type U = number | null
|
|
|
437
441
|
Types can be referenced with `Type.Ref(...)`. To reference a type, the target type must specify an `$id`.
|
|
438
442
|
|
|
439
443
|
```typescript
|
|
440
|
-
const T = Type.String({ $id: 'T' })
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
+
const T = Type.String({ $id: 'T' }) // const T = {
|
|
445
|
+
// $id: 'T',
|
|
446
|
+
// type: 'string'
|
|
447
|
+
// }
|
|
444
448
|
|
|
445
|
-
const R = Type.Ref(T)
|
|
446
|
-
|
|
447
|
-
|
|
449
|
+
const R = Type.Ref(T) // const R = {
|
|
450
|
+
// $ref: 'T'
|
|
451
|
+
// }
|
|
448
452
|
```
|
|
449
453
|
|
|
450
|
-
It can be helpful to organize shared referenced types under a common namespace. The `Type.Namespace(...)` function can be used to create a shared definition container for related types. The following creates a `Math3D` container and a `Vertex` structure that references types in the container.
|
|
454
|
+
It can sometimes be helpful to organize shared referenced types under a common namespace. The `Type.Namespace(...)` function can be used to create a shared definition container for related types. The following creates a `Math3D` container and a `Vertex` structure that references types in the container.
|
|
451
455
|
|
|
452
456
|
```typescript
|
|
453
|
-
const Math3D = Type.Namespace({
|
|
454
|
-
Vector4: Type.Object({
|
|
455
|
-
x: Type.Number(),
|
|
456
|
-
y: Type.Number(),
|
|
457
|
-
z: Type.Number(),
|
|
458
|
-
w: Type.Number()
|
|
459
|
-
}),
|
|
460
|
-
Vector3: Type.Object({
|
|
461
|
-
x: Type.Number(),
|
|
462
|
-
y: Type.Number(),
|
|
463
|
-
z: Type.Number()
|
|
464
|
-
}),
|
|
465
|
-
Vector2: Type.Object({
|
|
466
|
-
x: Type.Number(),
|
|
467
|
-
y: Type.Number()
|
|
468
|
-
})
|
|
469
|
-
}, { $id: 'Math3D' })
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
457
|
+
const Math3D = Type.Namespace({ // const Math3D = {
|
|
458
|
+
Vector4: Type.Object({ // $id: 'Math3D',
|
|
459
|
+
x: Type.Number(), // $defs: {
|
|
460
|
+
y: Type.Number(), // Vector4: {
|
|
461
|
+
z: Type.Number(), // type: 'object',
|
|
462
|
+
w: Type.Number() // properties: {
|
|
463
|
+
}), // x: { type: 'number' },
|
|
464
|
+
Vector3: Type.Object({ // y: { type: 'number' },
|
|
465
|
+
x: Type.Number(), // z: { type: 'number' },
|
|
466
|
+
y: Type.Number(), // w: { type: 'number' }
|
|
467
|
+
z: Type.Number() // },
|
|
468
|
+
}), // required: ['x', 'y', 'z', 'w']
|
|
469
|
+
Vector2: Type.Object({ // },
|
|
470
|
+
x: Type.Number(), // Vector3: {
|
|
471
|
+
y: Type.Number() // type: 'object',
|
|
472
|
+
}) // properties: {
|
|
473
|
+
}, { $id: 'Math3D' }) // x: { 'type': 'number' },
|
|
474
|
+
// y: { 'type': 'number' },
|
|
475
|
+
// z: { 'type': 'number' }
|
|
476
|
+
// },
|
|
477
|
+
// required: ['x', 'y', 'z']
|
|
478
|
+
// },
|
|
479
|
+
// Vector2: {
|
|
480
|
+
// type: 'object',
|
|
481
|
+
// properties: {
|
|
482
|
+
// x: { 'type': 'number' },
|
|
483
|
+
// y: { 'type': 'number' },
|
|
484
|
+
// },
|
|
485
|
+
// required: ['x', 'y']
|
|
486
|
+
// }
|
|
487
|
+
// }
|
|
488
|
+
// }
|
|
485
489
|
|
|
486
|
-
const Vertex = Type.Object({
|
|
487
|
-
position: Type.Ref(Math3D, 'Vector4'),
|
|
488
|
-
normal: Type.Ref(Math3D, 'Vector3'),
|
|
489
|
-
uv: Type.Ref(Math3D, 'Vector2')
|
|
490
|
-
})
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
490
|
+
const Vertex = Type.Object({ // const Vertex = {
|
|
491
|
+
position: Type.Ref(Math3D, 'Vector4'), // type: 'object',
|
|
492
|
+
normal: Type.Ref(Math3D, 'Vector3'), // properties: {
|
|
493
|
+
uv: Type.Ref(Math3D, 'Vector2') // position: { $ref: 'Math3D#/$defs/Vector4' },
|
|
494
|
+
}) // normal: { $ref: 'Math3D#/$defs/Vector3' },
|
|
495
|
+
// uv: { $ref: 'Math3D#/$defs/Vector2' }
|
|
496
|
+
// },
|
|
497
|
+
// required: ['position', 'normal', 'uv']
|
|
498
|
+
// }
|
|
495
499
|
```
|
|
496
500
|
|
|
497
501
|
<a name="Recursive-Types"></a>
|
|
@@ -501,30 +505,30 @@ const Vertex = Type.Object({ // const Vertex = {
|
|
|
501
505
|
Recursive types can be created with the `Type.Rec(...)` function. The following creates a `Node` type that contains an array of inner Nodes. Note that due to current restrictions on TypeScript inference, it is not possible for TypeBox to statically infer for recursive types. TypeBox will infer the inner recursive type as `any`.
|
|
502
506
|
|
|
503
507
|
```typescript
|
|
504
|
-
const Node = Type.Rec(Self => Type.Object({
|
|
505
|
-
id: Type.String(),
|
|
506
|
-
nodes: Type.Array(Self),
|
|
507
|
-
}), { $id: 'Node' })
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
type Node = Static<typeof Node>
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
508
|
+
const Node = Type.Rec(Self => Type.Object({ // const Node = {
|
|
509
|
+
id: Type.String(), // $id: 'Node',
|
|
510
|
+
nodes: Type.Array(Self), // $ref: 'Node#/$defs/self',
|
|
511
|
+
}), { $id: 'Node' }) // $defs: {
|
|
512
|
+
// self: {
|
|
513
|
+
// type: 'object',
|
|
514
|
+
// properties: {
|
|
515
|
+
// id: {
|
|
516
|
+
// type: 'string'
|
|
517
|
+
// },
|
|
518
|
+
// nodes: {
|
|
519
|
+
// type: 'array',
|
|
520
|
+
// items: {
|
|
521
|
+
// $ref: 'Node#/$defs/self'
|
|
522
|
+
// }
|
|
523
|
+
// }
|
|
524
|
+
// }
|
|
525
|
+
// }
|
|
526
|
+
// }
|
|
527
|
+
|
|
528
|
+
type Node = Static<typeof Node> // type Node = {
|
|
529
|
+
// id: string
|
|
530
|
+
// nodes: any[]
|
|
531
|
+
// }
|
|
528
532
|
|
|
529
533
|
function visit(node: Node) {
|
|
530
534
|
for(const inner of node.nodes) {
|
|
@@ -542,7 +546,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
|
|
|
542
546
|
```typescript
|
|
543
547
|
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
|
|
544
548
|
│ TypeBox │ TypeScript │ Extended Schema │
|
|
545
|
-
│
|
|
549
|
+
│ │ │ │
|
|
546
550
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
547
551
|
│ const T = Type.Constructor([ │ type T = new ( │ const T = { │
|
|
548
552
|
│ Type.String(), │ arg0: string, │ type: 'constructor' │
|
|
@@ -555,7 +559,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
|
|
|
555
559
|
│ │ │ type: 'boolean' │
|
|
556
560
|
│ │ │ } │
|
|
557
561
|
│ │ │ } │
|
|
558
|
-
│
|
|
562
|
+
│ │ │ │
|
|
559
563
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
560
564
|
│ const T = Type.Function([ │ type T = ( │ const T = { │
|
|
561
565
|
| Type.String(), │ arg0: string, │ type : 'function', │
|
|
@@ -568,7 +572,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
|
|
|
568
572
|
│ │ │ type: 'boolean' │
|
|
569
573
|
│ │ │ } │
|
|
570
574
|
│ │ │ } │
|
|
571
|
-
│
|
|
575
|
+
│ │ │ │
|
|
572
576
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
573
577
|
│ const T = Type.Promise( │ type T = Promise<string> │ const T = { │
|
|
574
578
|
│ Type.String() │ │ type: 'promise', │
|
|
@@ -576,17 +580,17 @@ In addition to JSON schema types, TypeBox provides several extended types that a
|
|
|
576
580
|
│ │ │ type: 'string' │
|
|
577
581
|
│ │ │ } │
|
|
578
582
|
│ │ │ } │
|
|
579
|
-
│
|
|
583
|
+
│ │ │ │
|
|
580
584
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
581
585
|
│ const T = Type.Undefined() │ type T = undefined │ const T = { │
|
|
582
586
|
│ │ │ type: 'undefined' │
|
|
583
587
|
│ │ │ } │
|
|
584
|
-
│
|
|
588
|
+
│ │ │ │
|
|
585
589
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
586
590
|
│ const T = Type.Void() │ type T = void │ const T = { │
|
|
587
591
|
│ │ │ type: 'void' │
|
|
588
592
|
│ │ │ } │
|
|
589
|
-
│
|
|
593
|
+
│ │ │ │
|
|
590
594
|
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
|
|
591
595
|
```
|
|
592
596
|
|
|
@@ -594,7 +598,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
|
|
|
594
598
|
|
|
595
599
|
### Strict
|
|
596
600
|
|
|
597
|
-
TypeBox
|
|
601
|
+
TypeBox schemas contain the properties `kind` and `modifier`. These properties are provided to enable runtime type reflection on schemas, as well as helping TypeBox apply the appropriate static type inference rules. These properties are not strictly valid JSON schema so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict()` function that will omit these properties if nessasary.
|
|
598
602
|
|
|
599
603
|
```typescript
|
|
600
604
|
const T = Type.Object({ // const T = {
|
|
@@ -623,7 +627,7 @@ const U = Type.Strict(T) // const U = {
|
|
|
623
627
|
|
|
624
628
|
### Validation
|
|
625
629
|
|
|
626
|
-
TypeBox does not provide JSON schema validation
|
|
630
|
+
TypeBox does not provide JSON schema validation so users will need to select an appropriate JSON Schema validator for their needs. TypeBox schemas target JSON Schema draft `2019-09` so any validator capable of draft `2019-09` should be fine. A good library to use for validation in JavaScript environments is [AJV](https://www.npmjs.com/package/ajv). The following example shows setting up AJV 7 to work with TypeBox.
|
|
627
631
|
|
|
628
632
|
```bash
|
|
629
633
|
$ npm install ajv ajv-formats --save
|
|
@@ -689,64 +693,11 @@ const ok = ajv.validate(User, {
|
|
|
689
693
|
}) // -> ok
|
|
690
694
|
```
|
|
691
695
|
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
Referenced types can be added to AJV with the `ajv.addSchema(...)` function. The following moves the `userId` and `email` property types into a `Type.Namespace(...)` and registers the box with AJV.
|
|
695
|
-
|
|
696
|
-
```typescript
|
|
697
|
-
//--------------------------------------------------------------------------------------------
|
|
698
|
-
//
|
|
699
|
-
// Shared Types
|
|
700
|
-
//
|
|
701
|
-
//--------------------------------------------------------------------------------------------
|
|
702
|
-
|
|
703
|
-
const Shared = Type.Namespace({
|
|
704
|
-
UserId: Type.String({ format: 'uuid' }),
|
|
705
|
-
Email: Type.String({ format: 'email' })
|
|
706
|
-
}, { $id: 'Shared' })
|
|
707
|
-
|
|
708
|
-
//--------------------------------------------------------------------------------------------
|
|
709
|
-
//
|
|
710
|
-
// Setup Validator and Register Shared Types
|
|
711
|
-
//
|
|
712
|
-
//--------------------------------------------------------------------------------------------
|
|
713
|
-
|
|
714
|
-
const ajv = addFormats(new Ajv({}), [...])
|
|
715
|
-
.addKeyword('kind')
|
|
716
|
-
.addKeyword('modifier')
|
|
717
|
-
.addSchema(Shared) // <-- Register Shared Types
|
|
718
|
-
|
|
719
|
-
//--------------------------------------------------------------------------------------------
|
|
720
|
-
//
|
|
721
|
-
// Create a TypeBox type
|
|
722
|
-
//
|
|
723
|
-
//--------------------------------------------------------------------------------------------
|
|
724
|
-
|
|
725
|
-
const User = Type.Object({
|
|
726
|
-
userId: Type.Ref(Shared, 'UserId'),
|
|
727
|
-
email: Type.Ref(Shared, 'Email'),
|
|
728
|
-
online: Type.Boolean()
|
|
729
|
-
}, { additionalProperties: false })
|
|
730
|
-
|
|
731
|
-
//--------------------------------------------------------------------------------------------
|
|
732
|
-
//
|
|
733
|
-
// Validate Data
|
|
734
|
-
//
|
|
735
|
-
//--------------------------------------------------------------------------------------------
|
|
736
|
-
|
|
737
|
-
const ok = ajv.validate(User, {
|
|
738
|
-
userId: '68b4b1d8-0db6-468d-b551-02069a692044',
|
|
739
|
-
email: 'dave@domain.com',
|
|
740
|
-
online: true
|
|
741
|
-
}) // -> ok
|
|
742
|
-
|
|
743
|
-
```
|
|
744
|
-
|
|
745
|
-
Please refer to the official AJV [documentation](https://ajv.js.org/guide/getting-started.html) for additional information.
|
|
696
|
+
Please refer to the official AJV [documentation](https://ajv.js.org/guide/getting-started.html) for additional information on using AJV.
|
|
746
697
|
|
|
747
698
|
### OpenAPI
|
|
748
699
|
|
|
749
|
-
TypeBox can be used to create schemas for OpenAPI, however users should be aware of the various
|
|
700
|
+
TypeBox can be used to create schemas for OpenAPI, however users should be aware of the various disparities between the JSON Schema and OpenAPI schema specifications. Two common instances where OpenAPI diverges from the JSON Schema specification is OpenAPI's handling of string enums and nullable schemas. The following shows how you can use TypeBox to construct these types.
|
|
750
701
|
|
|
751
702
|
```typescript
|
|
752
703
|
import { Type, Static, TNull, TLiteral, TUnion, TSchema } from '@sinclair/typebox'
|
|
@@ -761,12 +712,12 @@ function Nullable<T extends TSchema>(schema: T): TUnion<[T, TNull]> {
|
|
|
761
712
|
return { ...schema, nullable: true } as any
|
|
762
713
|
}
|
|
763
714
|
|
|
764
|
-
const T = Nullable(Type.String())
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
715
|
+
const T = Nullable(Type.String()) // const T = {
|
|
716
|
+
// type: 'string',
|
|
717
|
+
// nullable: true
|
|
718
|
+
// }
|
|
768
719
|
|
|
769
|
-
type T = Static<typeof T>
|
|
720
|
+
type T = Static<typeof T> // type T = string | null
|
|
770
721
|
|
|
771
722
|
//--------------------------------------------------------------------------------------------
|
|
772
723
|
//
|
|
@@ -774,13 +725,15 @@ type T = Static<typeof T> // type T = string | null
|
|
|
774
725
|
//
|
|
775
726
|
//--------------------------------------------------------------------------------------------
|
|
776
727
|
|
|
777
|
-
|
|
728
|
+
type IntoStringUnion<T> = {[K in keyof T]: T[K] extends string ? TLiteral<T[K]>: never }
|
|
729
|
+
|
|
730
|
+
function StringUnion<T extends string[]>(values: [...T]): TUnion<IntoStringUnion<T>> {
|
|
778
731
|
return { enum: values } as any
|
|
779
732
|
}
|
|
780
733
|
|
|
781
|
-
const T = StringUnion(['A', 'B', 'C'])
|
|
782
|
-
|
|
783
|
-
|
|
734
|
+
const T = StringUnion(['A', 'B', 'C']) // const T = {
|
|
735
|
+
// enum: ['A', 'B', 'C']
|
|
736
|
+
// }
|
|
784
737
|
|
|
785
|
-
type T = Static<typeof T>
|
|
738
|
+
type T = Static<typeof T> // type T = 'A' | 'B' | 'C'
|
|
786
739
|
```
|