@sinclair/typebox 0.31.0-dev-1 → 0.31.0
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/compiler/compiler.d.ts +1 -1
- package/compiler/compiler.js +3 -17
- package/package.json +1 -1
- package/readme.md +424 -433
- package/typebox.d.ts +66 -64
- package/typebox.js +43 -43
package/readme.md
CHANGED
|
@@ -36,21 +36,21 @@ import { Type, Static } from 'https://esm.sh/@sinclair/typebox'
|
|
|
36
36
|
```typescript
|
|
37
37
|
import { Type, Static } from '@sinclair/typebox'
|
|
38
38
|
|
|
39
|
-
const T = Type.Object({
|
|
40
|
-
x: Type.Number(),
|
|
41
|
-
y: Type.Number(),
|
|
42
|
-
z: Type.Number()
|
|
43
|
-
})
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
type T = Static<typeof T>
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
39
|
+
const T = Type.Object({ // const T = {
|
|
40
|
+
x: Type.Number(), // type: 'object',
|
|
41
|
+
y: Type.Number(), // required: ['x', 'y', 'z'],
|
|
42
|
+
z: Type.Number() // properties: {
|
|
43
|
+
}) // x: { type: 'number' },
|
|
44
|
+
// y: { type: 'number' },
|
|
45
|
+
// z: { type: 'number' }
|
|
46
|
+
// }
|
|
47
|
+
// }
|
|
48
|
+
|
|
49
|
+
type T = Static<typeof T> // type T = {
|
|
50
|
+
// x: number,
|
|
51
|
+
// y: number,
|
|
52
|
+
// z: number
|
|
53
|
+
// }
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
|
|
@@ -58,11 +58,11 @@ type T = Static<typeof T> // type T = {
|
|
|
58
58
|
|
|
59
59
|
## Overview
|
|
60
60
|
|
|
61
|
-
TypeBox is a runtime type builder that creates Json Schema objects that infer as TypeScript types. The schemas produced by this library are designed
|
|
61
|
+
TypeBox is a runtime type builder that creates Json Schema objects that infer as TypeScript types. The schemas produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox offers a unified type that can be statically checked by TypeScript and runtime checked using standard Json Schema validation.
|
|
62
62
|
|
|
63
|
-
TypeBox is
|
|
63
|
+
TypeBox is designed to be a runtime type system based on industry standard specifications for use in distributed systems. It offers serializable and publishable types as standard, a fully extensible type system capable of supporting multiple schema specifications, a high performance runtime validation compiler, various tools for working with dynamic data and offers detailed structured error reporting.
|
|
64
64
|
|
|
65
|
-
TypeBox can be used as a simple tool to build up complex schemas or integrated into applications
|
|
65
|
+
TypeBox can be used as a simple tool to build up complex schemas or integrated into applications to enable high performance runtime validation for data received over the wire.
|
|
66
66
|
|
|
67
67
|
License MIT
|
|
68
68
|
|
|
@@ -84,7 +84,7 @@ License MIT
|
|
|
84
84
|
- [Rest](#types-rest)
|
|
85
85
|
- [Transform](#types-transform)
|
|
86
86
|
- [Intrinsic](#types-intrinsic)
|
|
87
|
-
- [
|
|
87
|
+
- [Guard](#types-guard)
|
|
88
88
|
- [Unsafe](#types-unsafe)
|
|
89
89
|
- [Strict](#types-strict)
|
|
90
90
|
- [Values](#values)
|
|
@@ -149,25 +149,25 @@ type T = {
|
|
|
149
149
|
//
|
|
150
150
|
//--------------------------------------------------------------------------------------------
|
|
151
151
|
|
|
152
|
-
const T = Type.Object({
|
|
153
|
-
id: Type.String(),
|
|
154
|
-
name: Type.String(),
|
|
155
|
-
timestamp: Type.Integer()
|
|
156
|
-
})
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
152
|
+
const T = Type.Object({ // const T = {
|
|
153
|
+
id: Type.String(), // type: 'object',
|
|
154
|
+
name: Type.String(), // properties: {
|
|
155
|
+
timestamp: Type.Integer() // id: {
|
|
156
|
+
}) // type: 'string'
|
|
157
|
+
// },
|
|
158
|
+
// name: {
|
|
159
|
+
// type: 'string'
|
|
160
|
+
// },
|
|
161
|
+
// timestamp: {
|
|
162
|
+
// type: 'integer'
|
|
163
|
+
// }
|
|
164
|
+
// },
|
|
165
|
+
// required: [
|
|
166
|
+
// 'id',
|
|
167
|
+
// 'name',
|
|
168
|
+
// 'timestamp'
|
|
169
|
+
// ]
|
|
170
|
+
// }
|
|
171
171
|
|
|
172
172
|
//--------------------------------------------------------------------------------------------
|
|
173
173
|
//
|
|
@@ -175,11 +175,11 @@ const T = Type.Object({ // const T = {
|
|
|
175
175
|
//
|
|
176
176
|
//--------------------------------------------------------------------------------------------
|
|
177
177
|
|
|
178
|
-
type T = Static<typeof T>
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
178
|
+
type T = Static<typeof T> // type T = {
|
|
179
|
+
// id: string,
|
|
180
|
+
// name: string,
|
|
181
|
+
// timestamp: number
|
|
182
|
+
// }
|
|
183
183
|
|
|
184
184
|
//--------------------------------------------------------------------------------------------
|
|
185
185
|
//
|
|
@@ -189,9 +189,9 @@ type T = Static<typeof T> // type T = {
|
|
|
189
189
|
|
|
190
190
|
import { Value } from '@sinclair/typebox/value'
|
|
191
191
|
|
|
192
|
-
function receive(value: T) {
|
|
192
|
+
function receive(value: T) { // ... as a Static Type
|
|
193
193
|
|
|
194
|
-
if(Value.Check(T, value)) {
|
|
194
|
+
if(Value.Check(T, value)) { // ... as a Json Schema
|
|
195
195
|
|
|
196
196
|
// ok...
|
|
197
197
|
}
|
|
@@ -202,7 +202,7 @@ function receive(value: T) { // ... as a Static Type
|
|
|
202
202
|
|
|
203
203
|
## Types
|
|
204
204
|
|
|
205
|
-
TypeBox types are Json Schema fragments that compose into more complex types. Each fragment is structured such that any Json Schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox offers a set of Json Types which are used create Json Schema compliant schematics as well as a JavaScript type set used to create schematics for constructs native to JavaScript.
|
|
205
|
+
TypeBox types are Json Schema fragments that compose into more complex types. Each fragment is structured such that any Json Schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox offers a set of Json Types which are used to create Json Schema compliant schematics as well as a JavaScript type set used to create schematics for constructs native to JavaScript.
|
|
206
206
|
|
|
207
207
|
<a name='types-json'></a>
|
|
208
208
|
|
|
@@ -566,14 +566,6 @@ TypeBox provides an extended type set that can be used to create schematics for
|
|
|
566
566
|
│ │ │ } │
|
|
567
567
|
│ │ │ │
|
|
568
568
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
569
|
-
│ const T = Type.Iterator( │ type T = │ const T = { │
|
|
570
|
-
│ Type.String() │ IterableIterator<string> │ type: 'Iterator', │
|
|
571
|
-
│ ) │ │ items: { │
|
|
572
|
-
│ │ │ type: 'string' │
|
|
573
|
-
│ │ │ } │
|
|
574
|
-
│ │ │ } │
|
|
575
|
-
│ │ │ │
|
|
576
|
-
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
577
569
|
│ const T = │ type T = │ const T = { │
|
|
578
570
|
│ Type.AsyncIterator( │ AsyncIterableIterator< │ type: 'AsyncIterator', │
|
|
579
571
|
│ Type.String() │ string │ items: { │
|
|
@@ -582,6 +574,14 @@ TypeBox provides an extended type set that can be used to create schematics for
|
|
|
582
574
|
│ │ │ } │
|
|
583
575
|
│ │ │ │
|
|
584
576
|
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
577
|
+
│ const T = Type.Iterator( │ type T = │ const T = { │
|
|
578
|
+
│ Type.String() │ IterableIterator<string> │ type: 'Iterator', │
|
|
579
|
+
│ ) │ │ items: { │
|
|
580
|
+
│ │ │ type: 'string' │
|
|
581
|
+
│ │ │ } │
|
|
582
|
+
│ │ │ } │
|
|
583
|
+
│ │ │ │
|
|
584
|
+
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
|
|
585
585
|
│ const T = Type.RegExp(/abc/) │ type T = string │ const T = { │
|
|
586
586
|
│ │ │ type: 'string' │
|
|
587
587
|
│ │ │ pattern: 'abc' │
|
|
@@ -628,25 +628,25 @@ You can pass Json Schema options on the last argument of any type. Option hints
|
|
|
628
628
|
|
|
629
629
|
```typescript
|
|
630
630
|
// String must be an email
|
|
631
|
-
const T = Type.String({
|
|
632
|
-
format: 'email'
|
|
633
|
-
})
|
|
634
|
-
|
|
631
|
+
const T = Type.String({ // const T = {
|
|
632
|
+
format: 'email' // type: 'string',
|
|
633
|
+
}) // format: 'email'
|
|
634
|
+
// }
|
|
635
635
|
|
|
636
636
|
// Number must be a multiple of 2
|
|
637
|
-
const T = Type.Number({
|
|
638
|
-
multipleOf: 2
|
|
639
|
-
})
|
|
640
|
-
|
|
637
|
+
const T = Type.Number({ // const T = {
|
|
638
|
+
multipleOf: 2 // type: 'number',
|
|
639
|
+
}) // multipleOf: 2
|
|
640
|
+
// }
|
|
641
641
|
|
|
642
642
|
// Array must have at least 5 integer values
|
|
643
|
-
const T = Type.Array(Type.Integer(), {
|
|
644
|
-
minItems: 5
|
|
645
|
-
})
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
643
|
+
const T = Type.Array(Type.Integer(), { // const T = {
|
|
644
|
+
minItems: 5 // type: 'array',
|
|
645
|
+
}) // minItems: 5,
|
|
646
|
+
// items: {
|
|
647
|
+
// type: 'integer'
|
|
648
|
+
// }
|
|
649
|
+
// }
|
|
650
650
|
```
|
|
651
651
|
|
|
652
652
|
<a name='types-properties'></a>
|
|
@@ -696,43 +696,43 @@ Object properties can be modified with Readonly and Optional. The following tabl
|
|
|
696
696
|
|
|
697
697
|
### Generic Types
|
|
698
698
|
|
|
699
|
-
Generic types can be created with generic functions. All
|
|
699
|
+
Generic types can be created with generic functions. All types extend the base type TSchema. It is common to constrain generic function arguments to this type. The following creates a generic Vector type.
|
|
700
700
|
|
|
701
701
|
```typescript
|
|
702
702
|
import { Type, Static, TSchema } from '@sinclair/typebox'
|
|
703
703
|
|
|
704
704
|
const Vector = <T extends TSchema>(t: T) => Type.Object({ x: t, y: t, z: t })
|
|
705
705
|
|
|
706
|
-
const NumberVector = Vector(Type.Number())
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
type NumberVector = Static<typeof NumberVector>
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
706
|
+
const NumberVector = Vector(Type.Number()) // const NumberVector = {
|
|
707
|
+
// type: 'object',
|
|
708
|
+
// required: ['x', 'y', 'z'],
|
|
709
|
+
// properties: {
|
|
710
|
+
// x: { type: 'number' },
|
|
711
|
+
// y: { type: 'number' },
|
|
712
|
+
// z: { type: 'number' }
|
|
713
|
+
// }
|
|
714
|
+
// }
|
|
715
|
+
|
|
716
|
+
type NumberVector = Static<typeof NumberVector> // type NumberVector = {
|
|
717
|
+
// x: number,
|
|
718
|
+
// y: number,
|
|
719
|
+
// z: number
|
|
720
|
+
// }
|
|
721
721
|
```
|
|
722
722
|
|
|
723
|
-
Generic types
|
|
723
|
+
Generic types are often used to create aliases for more complex types. The following creates a Nullable generic type.
|
|
724
724
|
|
|
725
725
|
```typescript
|
|
726
726
|
const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])
|
|
727
727
|
|
|
728
|
-
const T = Nullable(Type.String())
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
728
|
+
const T = Nullable(Type.String()) // const T = {
|
|
729
|
+
// anyOf: [
|
|
730
|
+
// { type: 'string' },
|
|
731
|
+
// { type: 'null' }
|
|
732
|
+
// ]
|
|
733
|
+
// }
|
|
734
734
|
|
|
735
|
-
type T = Static<typeof T>
|
|
735
|
+
type T = Static<typeof T> // type T = string | null
|
|
736
736
|
```
|
|
737
737
|
|
|
738
738
|
<a name='types-references'></a>
|
|
@@ -742,52 +742,52 @@ type T = Static<typeof T> // type T = string | null
|
|
|
742
742
|
Reference types are supported with Ref.
|
|
743
743
|
|
|
744
744
|
```typescript
|
|
745
|
-
const T = Type.String({ $id: 'T' })
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
745
|
+
const T = Type.String({ $id: 'T' }) // const T = {
|
|
746
|
+
// $id: 'T',
|
|
747
|
+
// type: 'string'
|
|
748
|
+
// }
|
|
749
749
|
|
|
750
|
-
const R = Type.Ref<typeof T>('T')
|
|
751
|
-
|
|
752
|
-
|
|
750
|
+
const R = Type.Ref<typeof T>('T') // const R = {
|
|
751
|
+
// $ref: 'T'
|
|
752
|
+
// }
|
|
753
753
|
|
|
754
|
-
type R = Static<typeof R>
|
|
754
|
+
type R = Static<typeof R> // type R = string
|
|
755
755
|
```
|
|
756
756
|
|
|
757
757
|
<a name='types-recursive'></a>
|
|
758
758
|
|
|
759
759
|
### Recursive Types
|
|
760
760
|
|
|
761
|
-
TypeBox supports singular recursive data structures. Recursive type inference is also supported. The following creates a recursive Node structure.
|
|
761
|
+
TypeBox supports singular recursive data structures. Recursive type inference is also supported. The following creates a recursive Node data structure.
|
|
762
762
|
|
|
763
763
|
```typescript
|
|
764
|
-
const Node = Type.Recursive(This => Type.Object({
|
|
765
|
-
id: Type.String(),
|
|
766
|
-
nodes: Type.Array(This)
|
|
767
|
-
}), { $id: 'Node' })
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
type Node = Static<typeof Node>
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
764
|
+
const Node = Type.Recursive(This => Type.Object({ // const Node = {
|
|
765
|
+
id: Type.String(), // $id: 'Node',
|
|
766
|
+
nodes: Type.Array(This) // type: 'object',
|
|
767
|
+
}), { $id: 'Node' }) // properties: {
|
|
768
|
+
// id: {
|
|
769
|
+
// type: 'string'
|
|
770
|
+
// },
|
|
771
|
+
// nodes: {
|
|
772
|
+
// type: 'array',
|
|
773
|
+
// items: {
|
|
774
|
+
// $ref: 'Node'
|
|
775
|
+
// }
|
|
776
|
+
// }
|
|
777
|
+
// },
|
|
778
|
+
// required: [
|
|
779
|
+
// 'id',
|
|
780
|
+
// 'nodes'
|
|
781
|
+
// ]
|
|
782
|
+
// }
|
|
783
|
+
|
|
784
|
+
type Node = Static<typeof Node> // type Node = {
|
|
785
|
+
// id: string
|
|
786
|
+
// nodes: Node[]
|
|
787
|
+
// }
|
|
788
788
|
|
|
789
789
|
function test(node: Node) {
|
|
790
|
-
const id = node.nodes[0].nodes[0].id
|
|
790
|
+
const id = node.nodes[0].nodes[0].id // id is string
|
|
791
791
|
}
|
|
792
792
|
```
|
|
793
793
|
|
|
@@ -795,7 +795,7 @@ function test(node: Node) {
|
|
|
795
795
|
|
|
796
796
|
### Conditional Types
|
|
797
797
|
|
|
798
|
-
TypeBox supports conditional types with Extends. This type
|
|
798
|
+
TypeBox supports runtime conditional types with Extends. This type will perform a structural assignability check for the first two arguments and returns one of the second two arguments based on the result. The Extends type is modelled after TypeScript conditional types. The Exclude and Extract conditional types are also supported.
|
|
799
799
|
|
|
800
800
|
```typescript
|
|
801
801
|
// TypeScript
|
|
@@ -824,142 +824,142 @@ const T1 = Type.Extract( // const T1: TLiteral<1> =
|
|
|
824
824
|
Type.Literal(1)
|
|
825
825
|
)
|
|
826
826
|
|
|
827
|
-
const T2 = Type.Exclude(
|
|
828
|
-
Type.Union([
|
|
829
|
-
Type.Literal(1),
|
|
830
|
-
Type.Literal(2),
|
|
831
|
-
Type.Literal(3)
|
|
832
|
-
]),
|
|
833
|
-
Type.Literal(1)
|
|
834
|
-
)
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
827
|
+
const T2 = Type.Exclude( // const T2: TUnion<[
|
|
828
|
+
Type.Union([ // TLiteral<2>,
|
|
829
|
+
Type.Literal(1), // TLiteral<3>
|
|
830
|
+
Type.Literal(2), // ]> = {
|
|
831
|
+
Type.Literal(3) // anyOf: [{
|
|
832
|
+
]), // type: 'number',
|
|
833
|
+
Type.Literal(1) // const: 2
|
|
834
|
+
) // }, {
|
|
835
|
+
// type: 'number',
|
|
836
|
+
// const: 3
|
|
837
|
+
// }]
|
|
838
|
+
// }
|
|
839
839
|
```
|
|
840
840
|
|
|
841
841
|
<a name='types-templateliteral'></a>
|
|
842
842
|
|
|
843
843
|
### Template Literal Types
|
|
844
844
|
|
|
845
|
-
TypeBox supports template literal types with TemplateLiteral. This type can be created using a string syntax that is
|
|
845
|
+
TypeBox supports template literal types with TemplateLiteral. This type can be created using a string syntax that is similar to the TypeScript template literal syntax. This type can also be constructed by passing an array of Union and Literal types in sequence. The following example shows the string syntax.
|
|
846
846
|
|
|
847
847
|
```typescript
|
|
848
848
|
// TypeScript
|
|
849
849
|
|
|
850
|
-
type T = `option${'A'|'B'|'C'}`
|
|
850
|
+
type T = `option${'A'|'B'|'C'}` // type T = 'optionA' | 'optionB' | 'optionC'
|
|
851
851
|
|
|
852
|
-
type R = Record<T, string>
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
852
|
+
type R = Record<T, string> // type R = {
|
|
853
|
+
// optionA: string
|
|
854
|
+
// optionB: string
|
|
855
|
+
// optionC: string
|
|
856
|
+
// }
|
|
857
857
|
|
|
858
858
|
// TypeBox
|
|
859
859
|
|
|
860
|
-
const T = Type.TemplateLiteral('option${A|B|C}')
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
const R = Type.Record(T, Type.String())
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
860
|
+
const T = Type.TemplateLiteral('option${A|B|C}') // const T = {
|
|
861
|
+
// pattern: '^option(A|B|C)$',
|
|
862
|
+
// type: 'string'
|
|
863
|
+
// }
|
|
864
|
+
|
|
865
|
+
const R = Type.Record(T, Type.String()) // const R = {
|
|
866
|
+
// type: 'object',
|
|
867
|
+
// required: ['optionA', 'optionB'],
|
|
868
|
+
// properties: {
|
|
869
|
+
// optionA: {
|
|
870
|
+
// type: 'string'
|
|
871
|
+
// },
|
|
872
|
+
// optionB: {
|
|
873
|
+
// type: 'string'
|
|
874
|
+
// }
|
|
875
|
+
// optionC: {
|
|
876
|
+
// type: 'string'
|
|
877
|
+
// }
|
|
878
|
+
// }
|
|
879
|
+
// }
|
|
880
880
|
```
|
|
881
881
|
|
|
882
882
|
<a name='types-indexed'></a>
|
|
883
883
|
|
|
884
884
|
### Indexed Access Types
|
|
885
885
|
|
|
886
|
-
TypeBox supports Indexed Access Types with
|
|
886
|
+
TypeBox supports Indexed Access Types with Index. This type enables uniform access to interior property and array element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
|
|
887
887
|
|
|
888
888
|
```typescript
|
|
889
|
-
const T = Type.Object({
|
|
890
|
-
x: Type.Number(),
|
|
891
|
-
y: Type.String(),
|
|
892
|
-
z: Type.Boolean()
|
|
893
|
-
})
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
const A = Type.Index(T, ['x'])
|
|
900
|
-
|
|
901
|
-
const B = Type.Index(T, ['x', 'y'])
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
const C = Type.Index(T, Type.KeyOf(T))
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
889
|
+
const T = Type.Object({ // const T = {
|
|
890
|
+
x: Type.Number(), // type: 'object',
|
|
891
|
+
y: Type.String(), // required: ['x', 'y', 'z'],
|
|
892
|
+
z: Type.Boolean() // properties: {
|
|
893
|
+
}) // x: { type: 'number' },
|
|
894
|
+
// y: { type: 'string' },
|
|
895
|
+
// z: { type: 'string' }
|
|
896
|
+
// }
|
|
897
|
+
// }
|
|
898
|
+
|
|
899
|
+
const A = Type.Index(T, ['x']) // const A = { type: 'number' }
|
|
900
|
+
|
|
901
|
+
const B = Type.Index(T, ['x', 'y']) // const B = {
|
|
902
|
+
// anyOf: [
|
|
903
|
+
// { type: 'number' },
|
|
904
|
+
// { type: 'string' }
|
|
905
|
+
// ]
|
|
906
|
+
// }
|
|
907
|
+
|
|
908
|
+
const C = Type.Index(T, Type.KeyOf(T)) // const C = {
|
|
909
|
+
// anyOf: [
|
|
910
|
+
// { type: 'number' },
|
|
911
|
+
// { type: 'string' },
|
|
912
|
+
// { type: 'boolean' }
|
|
913
|
+
// ]
|
|
914
|
+
// }
|
|
915
915
|
```
|
|
916
916
|
|
|
917
917
|
<a name='types-rest'></a>
|
|
918
918
|
|
|
919
919
|
### Rest Types
|
|
920
920
|
|
|
921
|
-
TypeBox provides the Rest type to uniformly extract
|
|
921
|
+
TypeBox provides the Rest type to uniformly extract variadic tuples from Intersect, Union and Tuple types. This type can be useful to remap variadic types into different forms. The following uses Rest to remap a Tuple into a Union.
|
|
922
922
|
|
|
923
923
|
```typescript
|
|
924
|
-
const T = Type.Tuple([
|
|
925
|
-
Type.String(),
|
|
926
|
-
Type.Number()
|
|
927
|
-
])
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
const R = Type.Rest(T)
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
const U = Type.Union(R)
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
924
|
+
const T = Type.Tuple([ // const T = {
|
|
925
|
+
Type.String(), // type: 'array',
|
|
926
|
+
Type.Number() // items: [
|
|
927
|
+
]) // { type: 'string' },
|
|
928
|
+
// { type: 'number' }
|
|
929
|
+
// ],
|
|
930
|
+
// additionalItems: false,
|
|
931
|
+
// minItems: 2,
|
|
932
|
+
// maxItems: 2,
|
|
933
|
+
// }
|
|
934
|
+
|
|
935
|
+
const R = Type.Rest(T) // const R = [
|
|
936
|
+
// { type: 'string' },
|
|
937
|
+
// { type: 'number' }
|
|
938
|
+
// ]
|
|
939
|
+
|
|
940
|
+
const U = Type.Union(R) // const U = {
|
|
941
|
+
// anyOf: [
|
|
942
|
+
// { type: 'string' },
|
|
943
|
+
// { type: 'number' }
|
|
944
|
+
// ]
|
|
945
|
+
// }
|
|
946
946
|
```
|
|
947
947
|
|
|
948
948
|
<a name='types-transform'></a>
|
|
949
949
|
|
|
950
950
|
### Transform Types
|
|
951
951
|
|
|
952
|
-
TypeBox supports bi-directional
|
|
952
|
+
TypeBox supports bi-directional decode and encode with Transform types. These types are designed to operate with the Value and TypeCompiler Encode and Decode functions. Transform types are useful to convert Json encoded values into constructs more natural to JavaScript. The following creates a Transform type to convert between Date and number using the Value module.
|
|
953
953
|
|
|
954
954
|
```typescript
|
|
955
955
|
import { Value } from '@sinclair/typebox/value'
|
|
956
956
|
|
|
957
957
|
const T = Type.Transform(Type.Number())
|
|
958
|
-
.Decode(value => new Date(value))
|
|
959
|
-
.Encode(value => value.getTime())
|
|
958
|
+
.Decode(value => new Date(value)) // required: number to Date
|
|
959
|
+
.Encode(value => value.getTime()) // required: Date to number
|
|
960
960
|
|
|
961
|
-
const decoded = Value.Decode(T, 0)
|
|
962
|
-
const encoded = Value.Encode(T, decoded)
|
|
961
|
+
const decoded = Value.Decode(T, 0) // const decoded = Date(1970-01-01T00:00:00.000Z)
|
|
962
|
+
const encoded = Value.Encode(T, decoded) // const encoded = 0
|
|
963
963
|
```
|
|
964
964
|
Use the StaticEncode or StaticDecode types to infer a Transform type.
|
|
965
965
|
```typescript
|
|
@@ -969,41 +969,41 @@ const T = Type.Transform(Type.Array(Type.Number(), { uniqueItems: true }))
|
|
|
969
969
|
.Decode(value => new Set(value))
|
|
970
970
|
.Encode(value => [...value])
|
|
971
971
|
|
|
972
|
-
type D = StaticDecode<typeof T>
|
|
973
|
-
type E = StaticEncode<typeof T>
|
|
974
|
-
type T = Static<typeof T>
|
|
972
|
+
type D = StaticDecode<typeof T> // type D = Set<number>
|
|
973
|
+
type E = StaticEncode<typeof T> // type E = Array<number>
|
|
974
|
+
type T = Static<typeof T> // type T = Array<number>
|
|
975
975
|
```
|
|
976
976
|
|
|
977
977
|
<a name='types-intrinsic'></a>
|
|
978
978
|
|
|
979
979
|
### Intrinsic Types
|
|
980
980
|
|
|
981
|
-
TypeBox supports the TypeScript Intrinsic String Manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap String Literal, TemplateLiteral and Union types.
|
|
981
|
+
TypeBox supports the TypeScript Intrinsic String Manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap String Literal, TemplateLiteral and Union types.
|
|
982
982
|
|
|
983
983
|
```typescript
|
|
984
984
|
// TypeScript
|
|
985
985
|
|
|
986
|
-
type A = Capitalize<'hello'>
|
|
987
|
-
type B = Capitalize<'hello' | 'world'>
|
|
988
|
-
type C = Capitalize<`hello${1|2|3}`>
|
|
986
|
+
type A = Capitalize<'hello'> // type A = 'Hello'
|
|
987
|
+
type B = Capitalize<'hello' | 'world'> // type C = 'Hello' | 'World'
|
|
988
|
+
type C = Capitalize<`hello${1|2|3}`> // type B = 'Hello1' | 'Hello2' | 'Hello3'
|
|
989
989
|
|
|
990
990
|
// TypeBox
|
|
991
991
|
|
|
992
|
-
const A = Type.Capitalize(Type.Literal('hello'))
|
|
993
|
-
|
|
994
|
-
const B = Type.Capitalize(Type.Union([
|
|
995
|
-
Type.Literal('hello'),
|
|
996
|
-
Type.Literal('world')
|
|
997
|
-
]))
|
|
998
|
-
|
|
999
|
-
const C = Type.Capitalize(
|
|
1000
|
-
Type.TemplateLiteral('hello${1|2|3}')
|
|
1001
|
-
)
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
992
|
+
const A = Type.Capitalize(Type.Literal('hello')) // const A: TLiteral<'Hello'>
|
|
993
|
+
|
|
994
|
+
const B = Type.Capitalize(Type.Union([ // const B: TUnion<[
|
|
995
|
+
Type.Literal('hello'), // TLiteral<'Hello'>,
|
|
996
|
+
Type.Literal('world') // TLiteral<'World'>
|
|
997
|
+
])) // ]>
|
|
998
|
+
|
|
999
|
+
const C = Type.Capitalize( // const C: TTemplateLiteral<[
|
|
1000
|
+
Type.TemplateLiteral('hello${1|2|3}') // TLiteral<'Hello'>,
|
|
1001
|
+
) // TUnion<[
|
|
1002
|
+
// TLiteral<'1'>,
|
|
1003
|
+
// TLiteral<'2'>,
|
|
1004
|
+
// TLiteral<'3'>
|
|
1005
|
+
// ]>
|
|
1006
|
+
// ]>
|
|
1007
1007
|
```
|
|
1008
1008
|
|
|
1009
1009
|
<a name='types-unsafe'></a>
|
|
@@ -1013,49 +1013,49 @@ const C = Type.Capitalize( // const C: TTemplateLiteral
|
|
|
1013
1013
|
TypeBox supports user defined types with Unsafe. This type allows you to specify both schema representation and inference type. The following creates an Unsafe type with a number schema that infers as string.
|
|
1014
1014
|
|
|
1015
1015
|
```typescript
|
|
1016
|
-
const T = Type.Unsafe<string>({ type: 'number' })
|
|
1017
|
-
|
|
1018
|
-
|
|
1016
|
+
const T = Type.Unsafe<string>({ type: 'number' }) // const T = {
|
|
1017
|
+
// type: 'number'
|
|
1018
|
+
// }
|
|
1019
1019
|
|
|
1020
|
-
type T = Static<typeof T>
|
|
1020
|
+
type T = Static<typeof T> // type T = string - ?
|
|
1021
1021
|
```
|
|
1022
|
-
The Unsafe type
|
|
1022
|
+
The Unsafe type is often used to create schematics for extended specifications like OpenAPI
|
|
1023
1023
|
```typescript
|
|
1024
1024
|
|
|
1025
1025
|
const Nullable = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T> | null>({
|
|
1026
1026
|
...schema, nullable: true
|
|
1027
1027
|
})
|
|
1028
1028
|
|
|
1029
|
-
const T = Nullable(Type.String())
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1029
|
+
const T = Nullable(Type.String()) // const T = {
|
|
1030
|
+
// type: 'string',
|
|
1031
|
+
// nullable: true
|
|
1032
|
+
// }
|
|
1033
1033
|
|
|
1034
|
-
type T = Static<typeof T>
|
|
1034
|
+
type T = Static<typeof T> // type T = string | null
|
|
1035
1035
|
|
|
1036
1036
|
const StringEnum = <T extends string[]>(values: [...T]) => Type.Unsafe<T[number]>({
|
|
1037
1037
|
type: 'string', enum: values
|
|
1038
1038
|
})
|
|
1039
|
-
const S = StringEnum(['A', 'B', 'C'])
|
|
1040
|
-
|
|
1041
|
-
|
|
1039
|
+
const S = StringEnum(['A', 'B', 'C']) // const S = {
|
|
1040
|
+
// enum: ['A', 'B', 'C']
|
|
1041
|
+
// }
|
|
1042
1042
|
|
|
1043
|
-
type S = Static<typeof T>
|
|
1043
|
+
type S = Static<typeof T> // type S = 'A' | 'B' | 'C'
|
|
1044
1044
|
```
|
|
1045
|
-
<a name='types-
|
|
1045
|
+
<a name='types-guard'></a>
|
|
1046
1046
|
|
|
1047
|
-
### Type
|
|
1047
|
+
### Type Guard
|
|
1048
1048
|
|
|
1049
|
-
TypeBox
|
|
1049
|
+
TypeBox can type check its own types with the TypeGuard module. This module is written for reflection and provides structural tests for every TypeBox type. Functions of this module return `is` guards which can be used with TypeScript control flow assertions to obtain schema inference. The following guards that the value A is TString.
|
|
1050
1050
|
|
|
1051
1051
|
```typescript
|
|
1052
1052
|
import { Type, Kind, TypeGuard } from '@sinclair/typebox'
|
|
1053
1053
|
|
|
1054
|
-
const
|
|
1054
|
+
const A: unknown = { ... }
|
|
1055
1055
|
|
|
1056
|
-
if(TypeGuard.TString(
|
|
1056
|
+
if(TypeGuard.TString(A)) {
|
|
1057
1057
|
|
|
1058
|
-
//
|
|
1058
|
+
A.type // A.type = 'string'
|
|
1059
1059
|
}
|
|
1060
1060
|
```
|
|
1061
1061
|
|
|
@@ -1066,26 +1066,26 @@ if(TypeGuard.TString(T)) {
|
|
|
1066
1066
|
TypeBox types contain various symbol properties that are used for reflection, composition and compilation. These properties are not strictly valid Json Schema; so in some cases it may be desirable to omit them. TypeBox provides a `Strict` function that will omit these properties if necessary.
|
|
1067
1067
|
|
|
1068
1068
|
```typescript
|
|
1069
|
-
const T = Type.Object({
|
|
1070
|
-
name: Type.Optional(Type.String())
|
|
1071
|
-
})
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
const U = Type.Strict(T)
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1069
|
+
const T = Type.Object({ // const T = {
|
|
1070
|
+
name: Type.Optional(Type.String()) // [Kind]: 'Object',
|
|
1071
|
+
}) // type: 'object',
|
|
1072
|
+
// properties: {
|
|
1073
|
+
// name: {
|
|
1074
|
+
// type: 'string',
|
|
1075
|
+
// [Kind]: 'String',
|
|
1076
|
+
// [Optional]: 'Optional'
|
|
1077
|
+
// }
|
|
1078
|
+
// }
|
|
1079
|
+
// }
|
|
1080
|
+
|
|
1081
|
+
const U = Type.Strict(T) // const U = {
|
|
1082
|
+
// type: 'object',
|
|
1083
|
+
// properties: {
|
|
1084
|
+
// name: {
|
|
1085
|
+
// type: 'string'
|
|
1086
|
+
// }
|
|
1087
|
+
// }
|
|
1088
|
+
// }
|
|
1089
1089
|
```
|
|
1090
1090
|
|
|
1091
1091
|
<a name='values'></a>
|
|
@@ -1107,29 +1107,29 @@ Use the Create function to create a value from a type. TypeBox will use default
|
|
|
1107
1107
|
```typescript
|
|
1108
1108
|
const T = Type.Object({ x: Type.Number(), y: Type.Number({ default: 42 }) })
|
|
1109
1109
|
|
|
1110
|
-
const A = Value.Create(T)
|
|
1110
|
+
const A = Value.Create(T) // const A = { x: 0, y: 42 }
|
|
1111
1111
|
```
|
|
1112
1112
|
|
|
1113
1113
|
<a name='values-clone'></a>
|
|
1114
1114
|
|
|
1115
1115
|
### Clone
|
|
1116
1116
|
|
|
1117
|
-
Use the Clone function to deeply clone a value
|
|
1117
|
+
Use the Clone function to deeply clone a value.
|
|
1118
1118
|
|
|
1119
1119
|
```typescript
|
|
1120
|
-
const A = Value.Clone({ x: 1, y: 2, z: 3 })
|
|
1120
|
+
const A = Value.Clone({ x: 1, y: 2, z: 3 }) // const A = { x: 1, y: 2, z: 3 }
|
|
1121
1121
|
```
|
|
1122
1122
|
|
|
1123
1123
|
<a name='values-check'></a>
|
|
1124
1124
|
|
|
1125
1125
|
### Check
|
|
1126
1126
|
|
|
1127
|
-
Use the Check function to type check a value
|
|
1127
|
+
Use the Check function to type check a value.
|
|
1128
1128
|
|
|
1129
1129
|
```typescript
|
|
1130
1130
|
const T = Type.Object({ x: Type.Number() })
|
|
1131
1131
|
|
|
1132
|
-
const R = Value.Check(T, { x: 1 })
|
|
1132
|
+
const R = Value.Check(T, { x: 1 }) // const R = true
|
|
1133
1133
|
```
|
|
1134
1134
|
|
|
1135
1135
|
<a name='values-convert'></a>
|
|
@@ -1141,47 +1141,48 @@ Use the Convert function to convert a value into its target type if a reasonable
|
|
|
1141
1141
|
```typescript
|
|
1142
1142
|
const T = Type.Object({ x: Type.Number() })
|
|
1143
1143
|
|
|
1144
|
-
const R1 = Value.Convert(T, { x: '3.14' })
|
|
1144
|
+
const R1 = Value.Convert(T, { x: '3.14' }) // const R1 = { x: 3.14 }
|
|
1145
1145
|
|
|
1146
|
-
const R2 = Value.Convert(T, { x: 'not a number' })
|
|
1146
|
+
const R2 = Value.Convert(T, { x: 'not a number' }) // const R2 = { x: 'not a number' }
|
|
1147
1147
|
```
|
|
1148
1148
|
|
|
1149
1149
|
<a name='values-cast'></a>
|
|
1150
1150
|
|
|
1151
1151
|
### Cast
|
|
1152
1152
|
|
|
1153
|
-
Use the Cast function to cast a value
|
|
1153
|
+
Use the Cast function to cast a value with a type. The cast function will retain as much information as possible from the original value.
|
|
1154
1154
|
|
|
1155
1155
|
```typescript
|
|
1156
1156
|
const T = Type.Object({ x: Type.Number(), y: Type.Number() }, { additionalProperties: false })
|
|
1157
1157
|
|
|
1158
|
-
const X = Value.Cast(T, null)
|
|
1158
|
+
const X = Value.Cast(T, null) // const X = { x: 0, y: 0 }
|
|
1159
1159
|
|
|
1160
|
-
const Y = Value.Cast(T, { x: 1 })
|
|
1160
|
+
const Y = Value.Cast(T, { x: 1 }) // const Y = { x: 1, y: 0 }
|
|
1161
1161
|
|
|
1162
|
-
const Z = Value.Cast(T, { x: 1, y: 2, z: 3 })
|
|
1162
|
+
const Z = Value.Cast(T, { x: 1, y: 2, z: 3 }) // const Z = { x: 1, y: 2 }
|
|
1163
1163
|
```
|
|
1164
1164
|
|
|
1165
1165
|
<a name='values-decode'></a>
|
|
1166
1166
|
|
|
1167
1167
|
### Decode
|
|
1168
1168
|
|
|
1169
|
-
Use the Decode function to decode a value from a type or throw if the value is invalid. The return value will infer as the
|
|
1169
|
+
Use the Decode function to decode a value from a type, or throw if the value is invalid. The return value will infer as the decoded type. This function will run Transform codecs if available.
|
|
1170
1170
|
|
|
1171
1171
|
```typescript
|
|
1172
|
-
const A = Type.Decode(Type.String(), 'hello')
|
|
1172
|
+
const A = Type.Decode(Type.String(), 'hello') // const A = 'hello'
|
|
1173
1173
|
|
|
1174
|
-
const B = Type.Decode(Type.String(), 42)
|
|
1174
|
+
const B = Type.Decode(Type.String(), 42) // throw
|
|
1175
1175
|
```
|
|
1176
1176
|
<a name='values-decode'></a>
|
|
1177
1177
|
|
|
1178
1178
|
### Encode
|
|
1179
1179
|
|
|
1180
|
-
Use the Encode function to encode a value
|
|
1180
|
+
Use the Encode function to encode a value to a type, or throw if the value is invalid. The return value will infer as the encoded type. This function will run Transform codecs if available.
|
|
1181
|
+
|
|
1181
1182
|
```typescript
|
|
1182
|
-
const A = Type.Encode(Type.String(), 'hello')
|
|
1183
|
+
const A = Type.Encode(Type.String(), 'hello') // const A = 'hello'
|
|
1183
1184
|
|
|
1184
|
-
const B = Type.Encode(Type.String(), 42)
|
|
1185
|
+
const B = Type.Encode(Type.String(), 42) // throw
|
|
1185
1186
|
```
|
|
1186
1187
|
|
|
1187
1188
|
<a name='values-equal'></a>
|
|
@@ -1191,7 +1192,7 @@ const B = Type.Encode(Type.String(), 42) // throw
|
|
|
1191
1192
|
Use the Equal function to deeply check for value equality.
|
|
1192
1193
|
|
|
1193
1194
|
```typescript
|
|
1194
|
-
const R = Value.Equal(
|
|
1195
|
+
const R = Value.Equal( // const R = true
|
|
1195
1196
|
{ x: 1, y: 2, z: 3 },
|
|
1196
1197
|
{ x: 1, y: 2, z: 3 }
|
|
1197
1198
|
)
|
|
@@ -1204,65 +1205,65 @@ const R = Value.Equal( // const R = true
|
|
|
1204
1205
|
Use the Hash function to create a [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) non cryptographic hash of a value.
|
|
1205
1206
|
|
|
1206
1207
|
```typescript
|
|
1207
|
-
const A = Value.Hash({ x: 1, y: 2, z: 3 })
|
|
1208
|
+
const A = Value.Hash({ x: 1, y: 2, z: 3 }) // const A = 2910466848807138541n
|
|
1208
1209
|
|
|
1209
|
-
const B = Value.Hash({ x: 1, y: 4, z: 3 })
|
|
1210
|
+
const B = Value.Hash({ x: 1, y: 4, z: 3 }) // const B = 1418369778807423581n
|
|
1210
1211
|
```
|
|
1211
1212
|
|
|
1212
1213
|
<a name='values-diff'></a>
|
|
1213
1214
|
|
|
1214
1215
|
### Diff
|
|
1215
1216
|
|
|
1216
|
-
Use the Diff function to
|
|
1217
|
+
Use the Diff function to generate a sequence of edits that will transform one value into another.
|
|
1217
1218
|
|
|
1218
1219
|
```typescript
|
|
1219
|
-
const E = Value.Diff(
|
|
1220
|
-
{ x: 1, y: 2, z: 3 },
|
|
1221
|
-
{ y: 4, z: 5, w: 6 }
|
|
1222
|
-
)
|
|
1223
|
-
|
|
1224
|
-
|
|
1220
|
+
const E = Value.Diff( // const E = [
|
|
1221
|
+
{ x: 1, y: 2, z: 3 }, // { type: 'update', path: '/y', value: 4 },
|
|
1222
|
+
{ y: 4, z: 5, w: 6 } // { type: 'update', path: '/z', value: 5 },
|
|
1223
|
+
) // { type: 'insert', path: '/w', value: 6 },
|
|
1224
|
+
// { type: 'delete', path: '/x' }
|
|
1225
|
+
// ]
|
|
1225
1226
|
```
|
|
1226
1227
|
|
|
1227
1228
|
<a name='values-patch'></a>
|
|
1228
1229
|
|
|
1229
1230
|
### Patch
|
|
1230
1231
|
|
|
1231
|
-
Use the Patch function to apply
|
|
1232
|
+
Use the Patch function to apply a sequence of edits.
|
|
1232
1233
|
|
|
1233
1234
|
```typescript
|
|
1234
1235
|
const A = { x: 1, y: 2 }
|
|
1235
1236
|
|
|
1236
1237
|
const B = { x: 3 }
|
|
1237
1238
|
|
|
1238
|
-
const E = Value.Diff(A, B)
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1239
|
+
const E = Value.Diff(A, B) // const E = [
|
|
1240
|
+
// { type: 'update', path: '/x', value: 3 },
|
|
1241
|
+
// { type: 'delete', path: '/y' }
|
|
1242
|
+
// ]
|
|
1242
1243
|
|
|
1243
|
-
const C = Value.Patch<typeof B>(A, E)
|
|
1244
|
+
const C = Value.Patch<typeof B>(A, E) // const C = { x: 3 }
|
|
1244
1245
|
```
|
|
1245
1246
|
|
|
1246
1247
|
<a name='values-errors'></a>
|
|
1247
1248
|
|
|
1248
1249
|
### Errors
|
|
1249
1250
|
|
|
1250
|
-
Use the Errors function enumerate validation errors.
|
|
1251
|
+
Use the Errors function to enumerate validation errors.
|
|
1251
1252
|
|
|
1252
1253
|
```typescript
|
|
1253
1254
|
const T = Type.Object({ x: Type.Number(), y: Type.Number() })
|
|
1254
1255
|
|
|
1255
|
-
const R = [...Value.Errors(T, { x: '42' })]
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1256
|
+
const R = [...Value.Errors(T, { x: '42' })] // const R = [{
|
|
1257
|
+
// schema: { type: 'number' },
|
|
1258
|
+
// path: '/x',
|
|
1259
|
+
// value: '42',
|
|
1260
|
+
// message: 'Expected number'
|
|
1261
|
+
// }, {
|
|
1262
|
+
// schema: { type: 'number' },
|
|
1263
|
+
// path: '/y',
|
|
1264
|
+
// value: undefined,
|
|
1265
|
+
// message: 'Expected number'
|
|
1266
|
+
// }]
|
|
1266
1267
|
```
|
|
1267
1268
|
|
|
1268
1269
|
<a name='values-mutate'></a>
|
|
@@ -1272,20 +1273,15 @@ const R = [...Value.Errors(T, { x: '42' })] // const R = [{
|
|
|
1272
1273
|
Use the Mutate function to perform a deep mutable value assignment while retaining internal references.
|
|
1273
1274
|
|
|
1274
1275
|
```typescript
|
|
1275
|
-
const Y = { z: 1 }
|
|
1276
|
-
|
|
1277
|
-
const
|
|
1278
|
-
|
|
1279
|
-
const A = { x: X } // const A = { x: { y: { z: 1 } } }
|
|
1280
|
-
|
|
1276
|
+
const Y = { z: 1 } // const Y = { z: 1 }
|
|
1277
|
+
const X = { y: Y } // const X = { y: { z: 1 } }
|
|
1278
|
+
const A = { x: X } // const A = { x: { y: { z: 1 } } }
|
|
1281
1279
|
|
|
1282
|
-
Value.Mutate(A, { x: { y: { z: 2 } } })
|
|
1280
|
+
Value.Mutate(A, { x: { y: { z: 2 } } }) // const A' = { x: { y: { z: 2 } } }
|
|
1283
1281
|
|
|
1284
|
-
const R0 = A.x.y.z === 2
|
|
1285
|
-
|
|
1286
|
-
const
|
|
1287
|
-
|
|
1288
|
-
const R2 = A.x === X // const R2 = true
|
|
1282
|
+
const R0 = A.x.y.z === 2 // const R0 = true
|
|
1283
|
+
const R1 = A.x.y === Y // const R1 = true
|
|
1284
|
+
const R2 = A.x === X // const R2 = true
|
|
1289
1285
|
```
|
|
1290
1286
|
|
|
1291
1287
|
<a name='values-pointer'></a>
|
|
@@ -1299,18 +1295,16 @@ import { ValuePointer } from '@sinclair/typebox/value'
|
|
|
1299
1295
|
|
|
1300
1296
|
const A = { x: 0, y: 0, z: 0 }
|
|
1301
1297
|
|
|
1302
|
-
ValuePointer.Set(A, '/x', 1)
|
|
1303
|
-
|
|
1304
|
-
ValuePointer.Set(A, '/
|
|
1305
|
-
|
|
1306
|
-
ValuePointer.Set(A, '/z', 1) // const A' = { x: 1, y: 1, z: 1 }
|
|
1298
|
+
ValuePointer.Set(A, '/x', 1) // const A' = { x: 1, y: 0, z: 0 }
|
|
1299
|
+
ValuePointer.Set(A, '/y', 1) // const A' = { x: 1, y: 1, z: 0 }
|
|
1300
|
+
ValuePointer.Set(A, '/z', 1) // const A' = { x: 1, y: 1, z: 1 }
|
|
1307
1301
|
```
|
|
1308
1302
|
|
|
1309
1303
|
<a name='typeregistry'></a>
|
|
1310
1304
|
|
|
1311
1305
|
## TypeRegistry
|
|
1312
1306
|
|
|
1313
|
-
The TypeBox type system can be extended with additional types and formats using the TypeRegistry and FormatRegistry modules. These modules integrate deeply with TypeBox's internal type checking infrastructure and can be used to create application specific types, or
|
|
1307
|
+
The TypeBox type system can be extended with additional types and formats using the TypeRegistry and FormatRegistry modules. These modules integrate deeply with TypeBox's internal type checking infrastructure and can be used to create application specific types, or register schematics for alternative specifications.
|
|
1314
1308
|
|
|
1315
1309
|
<a name='typeregistry-type'></a>
|
|
1316
1310
|
|
|
@@ -1323,9 +1317,8 @@ import { TypeRegistry, Kind } from '@sinclair/typebox'
|
|
|
1323
1317
|
|
|
1324
1318
|
TypeRegistry.Set('Foo', (schema, value) => value === 'foo')
|
|
1325
1319
|
|
|
1326
|
-
const A = Value.Check({ [Kind]: 'Foo' }, 'foo')
|
|
1327
|
-
|
|
1328
|
-
const B = Value.Check({ [Kind]: 'Foo' }, 'bar') // const B = false
|
|
1320
|
+
const A = Value.Check({ [Kind]: 'Foo' }, 'foo') // const A = true
|
|
1321
|
+
const B = Value.Check({ [Kind]: 'Foo' }, 'bar') // const B = false
|
|
1329
1322
|
```
|
|
1330
1323
|
|
|
1331
1324
|
<a name='typeregistry-format'></a>
|
|
@@ -1341,16 +1334,15 @@ FormatRegistry.Set('foo', (value) => value === 'foo')
|
|
|
1341
1334
|
|
|
1342
1335
|
const T = Type.String({ format: 'foo' })
|
|
1343
1336
|
|
|
1344
|
-
const A = Value.Check(T, 'foo')
|
|
1345
|
-
|
|
1346
|
-
const B = Value.Check(T, 'bar') // const B = false
|
|
1337
|
+
const A = Value.Check(T, 'foo') // const A = true
|
|
1338
|
+
const B = Value.Check(T, 'bar') // const B = false
|
|
1347
1339
|
```
|
|
1348
1340
|
|
|
1349
1341
|
<a name='typecheck'></a>
|
|
1350
1342
|
|
|
1351
1343
|
## TypeCheck
|
|
1352
1344
|
|
|
1353
|
-
TypeBox types target Json Schema Draft 7 and are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for TypeBox types that offers high performance compilation and value
|
|
1345
|
+
TypeBox types target Json Schema Draft 7 and are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for TypeBox types that offers high performance compilation and value checking.
|
|
1354
1346
|
|
|
1355
1347
|
The following sections detail using Ajv and the TypeBox compiler infrastructure.
|
|
1356
1348
|
|
|
@@ -1392,14 +1384,14 @@ const validate = ajv.compile(Type.Object({
|
|
|
1392
1384
|
z: Type.Number()
|
|
1393
1385
|
}))
|
|
1394
1386
|
|
|
1395
|
-
const R = validate({ x: 1, y: 2, z: 3 })
|
|
1387
|
+
const R = validate({ x: 1, y: 2, z: 3 }) // const R = true
|
|
1396
1388
|
```
|
|
1397
1389
|
|
|
1398
1390
|
<a name='typecheck-typecompiler'></a>
|
|
1399
1391
|
|
|
1400
1392
|
### TypeCompiler
|
|
1401
1393
|
|
|
1402
|
-
The TypeBox TypeCompiler is a high performance JIT compiler that transforms TypeBox types into optimized JavaScript validation routines. The compiler is tuned for fast compilation as well as fast assertion. It is built to serve as a validation backend that can be integrated into larger applications
|
|
1394
|
+
The TypeBox TypeCompiler is a high performance JIT validation compiler that transforms TypeBox types into optimized JavaScript validation routines. The compiler is tuned for fast compilation as well as fast value assertion. It is built to serve as a validation backend that can be integrated into larger applications. It can also be used for code generation.
|
|
1403
1395
|
|
|
1404
1396
|
The TypeCompiler is provided as an optional import.
|
|
1405
1397
|
|
|
@@ -1410,64 +1402,66 @@ import { TypeCompiler } from '@sinclair/typebox/compiler'
|
|
|
1410
1402
|
Use the Compile function to JIT compile a type. Note that compilation is generally an expensive operation and should only be performed once per type during application start up. TypeBox does not cache previously compiled types, and applications are expected to hold references to each compiled type for the lifetime of the application.
|
|
1411
1403
|
|
|
1412
1404
|
```typescript
|
|
1413
|
-
const C = TypeCompiler.Compile(Type.Object({
|
|
1414
|
-
x: Type.Number(),
|
|
1415
|
-
y: Type.Number(),
|
|
1416
|
-
z: Type.Number()
|
|
1417
|
-
}))
|
|
1405
|
+
const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck<TObject<{
|
|
1406
|
+
x: Type.Number(), // x: TNumber;
|
|
1407
|
+
y: Type.Number(), // y: TNumber;
|
|
1408
|
+
z: Type.Number() // z: TNumber;
|
|
1409
|
+
})) // }>>
|
|
1418
1410
|
|
|
1419
|
-
const R = C.Check({ x: 1, y: 2, z: 3 })
|
|
1411
|
+
const R = C.Check({ x: 1, y: 2, z: 3 }) // const R = true
|
|
1420
1412
|
```
|
|
1421
1413
|
|
|
1422
|
-
Use the Errors function to generate diagnostic errors for a value. The Errors function will return an iterator that when enumerated; will perform an exhaustive check across the entire value yielding any error found. For performance, this function should only be called after failed Check. Applications may also choose to yield only the first value to avoid exhaustive error generation.
|
|
1414
|
+
Use the Errors function to generate diagnostic errors for a value. The Errors function will return an iterator that when enumerated; will perform an exhaustive check across the entire value yielding any error found. For performance, this function should only be called after a failed Check. Applications may also choose to yield only the first value to avoid exhaustive error generation.
|
|
1423
1415
|
|
|
1424
1416
|
```typescript
|
|
1425
|
-
const C = TypeCompiler.Compile(Type.Object({
|
|
1426
|
-
x: Type.Number(),
|
|
1427
|
-
y: Type.Number(),
|
|
1428
|
-
z: Type.Number()
|
|
1429
|
-
}))
|
|
1417
|
+
const C = TypeCompiler.Compile(Type.Object({ // const C: TypeCheck<TObject<{
|
|
1418
|
+
x: Type.Number(), // x: TNumber;
|
|
1419
|
+
y: Type.Number(), // y: TNumber;
|
|
1420
|
+
z: Type.Number() // z: TNumber;
|
|
1421
|
+
})) // }>>
|
|
1430
1422
|
|
|
1431
1423
|
const value = { }
|
|
1432
1424
|
|
|
1433
|
-
const first = C.Errors(value).First()
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
const all = [...C.Errors(value)]
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1425
|
+
const first = C.Errors(value).First() // const first = {
|
|
1426
|
+
// schema: { type: 'number' },
|
|
1427
|
+
// path: '/x',
|
|
1428
|
+
// value: undefined,
|
|
1429
|
+
// message: 'Expected number'
|
|
1430
|
+
// }
|
|
1431
|
+
|
|
1432
|
+
const all = [...C.Errors(value)] // const all = [{
|
|
1433
|
+
// schema: { type: 'number' },
|
|
1434
|
+
// path: '/x',
|
|
1435
|
+
// value: undefined,
|
|
1436
|
+
// message: 'Expected number'
|
|
1437
|
+
// }, {
|
|
1438
|
+
// schema: { type: 'number' },
|
|
1439
|
+
// path: '/y',
|
|
1440
|
+
// value: undefined,
|
|
1441
|
+
// message: 'Expected number'
|
|
1442
|
+
// }, {
|
|
1443
|
+
// schema: { type: 'number' },
|
|
1444
|
+
// path: '/z',
|
|
1445
|
+
// value: undefined,
|
|
1446
|
+
// message: 'Expected number'
|
|
1447
|
+
// }]
|
|
1456
1448
|
```
|
|
1457
|
-
|
|
1449
|
+
|
|
1450
|
+
Use the Code function to generate assertion functions as strings. This function can be used to create high performance assertions that can be written to disk as importable modules. The following generates code to check a string.
|
|
1451
|
+
|
|
1458
1452
|
```typescript
|
|
1459
|
-
const C = TypeCompiler.Code(Type.String(
|
|
1460
|
-
|
|
1461
|
-
|
|
1462
|
-
|
|
1463
|
-
|
|
1453
|
+
const C = TypeCompiler.Code(Type.String()) // const C = `return function check(value) {
|
|
1454
|
+
// return (
|
|
1455
|
+
// (typeof value === 'string')
|
|
1456
|
+
// )
|
|
1457
|
+
// }`
|
|
1464
1458
|
```
|
|
1465
1459
|
|
|
1466
1460
|
<a name='typesystem'></a>
|
|
1467
1461
|
|
|
1468
1462
|
## TypeSystem
|
|
1469
1463
|
|
|
1470
|
-
The TypeBox TypeSystem
|
|
1464
|
+
The TypeBox TypeSystem module provides functionality to define types above and beyond the built-in Json and JavaScript type sets. They also manage TypeBox's localization options (i18n) for error message generation and can control various assertion policies used when type checking. Configurations made to the TypeSystem module are observed by the TypeCompiler, Value and Error modules.
|
|
1471
1465
|
|
|
1472
1466
|
<a name='typesystem-types'></a>
|
|
1473
1467
|
|
|
@@ -1482,13 +1476,11 @@ const StringSet = TypeSystem.Type<Set<string>>('StringSet', (options, value) =>
|
|
|
1482
1476
|
return value instanceof Set && [...value].every(value => typeof value === 'string')
|
|
1483
1477
|
})
|
|
1484
1478
|
|
|
1485
|
-
const T = StringSet({})
|
|
1479
|
+
const T = StringSet({}) // Pass options if any
|
|
1486
1480
|
|
|
1487
|
-
const A = Value.Check(T, new Set())
|
|
1488
|
-
|
|
1489
|
-
const
|
|
1490
|
-
|
|
1491
|
-
const C = Value.Check(T, new Set([1])) // const C = false
|
|
1481
|
+
const A = Value.Check(T, new Set()) // const A = true
|
|
1482
|
+
const B = Value.Check(T, new Set(['hello'])) // const B = true
|
|
1483
|
+
const C = Value.Check(T, new Set([1])) // const C = false
|
|
1492
1484
|
|
|
1493
1485
|
```
|
|
1494
1486
|
|
|
@@ -1505,21 +1497,20 @@ const F = TypeSystem.Format('foo', value => value === 'Foo')
|
|
|
1505
1497
|
|
|
1506
1498
|
const T = Type.String({ format: F })
|
|
1507
1499
|
|
|
1508
|
-
const A = Value.Check(T, 'foo')
|
|
1509
|
-
|
|
1510
|
-
const B = Value.Check(T, 'bar') // const B = false
|
|
1500
|
+
const A = Value.Check(T, 'foo') // const A = true
|
|
1501
|
+
const B = Value.Check(T, 'bar') // const B = false
|
|
1511
1502
|
```
|
|
1512
1503
|
|
|
1513
1504
|
<a name='typesystem-errors'></a>
|
|
1514
1505
|
|
|
1515
1506
|
### Errors
|
|
1516
1507
|
|
|
1517
|
-
Use the TypeSystemErrorFunction
|
|
1508
|
+
Use the TypeSystemErrorFunction to override validation error messages. This can be used to localize errors or create error messages for user defined types.
|
|
1518
1509
|
|
|
1519
1510
|
```typescript
|
|
1520
1511
|
import { TypeSystemErrorFunction, ValueErrorType, DefaultErrorFunction } from '@sinclair/typebox/system'
|
|
1521
1512
|
|
|
1522
|
-
TypeSystemErrorFunction.Set((schema, errorType) => {// i18n override
|
|
1513
|
+
TypeSystemErrorFunction.Set((schema, errorType) => { // i18n override
|
|
1523
1514
|
switch(errorType) {
|
|
1524
1515
|
/* en-US */ case ValueErrorType.String: return 'Expected string'
|
|
1525
1516
|
/* fr-FR */ case ValueErrorType.Number: return 'Nombre attendu'
|
|
@@ -1527,37 +1518,37 @@ TypeSystemErrorFunction.Set((schema, errorType) => {// i18n override
|
|
|
1527
1518
|
/* en-US */ default: return DefaultErrorFunction(schema, errorType)
|
|
1528
1519
|
}
|
|
1529
1520
|
})
|
|
1530
|
-
const T = Type.Object({
|
|
1521
|
+
const T = Type.Object({ // const T = { ... }
|
|
1531
1522
|
x: Type.String(),
|
|
1532
1523
|
y: Type.Number(),
|
|
1533
1524
|
z: Type.Boolean()
|
|
1534
1525
|
})
|
|
1535
|
-
const E = [...Value.Errors(T, {
|
|
1536
|
-
x: null,
|
|
1537
|
-
y: null,
|
|
1538
|
-
z: null
|
|
1539
|
-
})]
|
|
1540
|
-
|
|
1541
|
-
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1553
|
-
|
|
1526
|
+
const E = [...Value.Errors(T, { // const E = [{
|
|
1527
|
+
x: null, // type: 48,
|
|
1528
|
+
y: null, // schema: { ... },
|
|
1529
|
+
z: null // path: '/x',
|
|
1530
|
+
})] // value: null,
|
|
1531
|
+
// message: 'Expected string'
|
|
1532
|
+
// }, {
|
|
1533
|
+
// type: 34,
|
|
1534
|
+
// schema: { ... },
|
|
1535
|
+
// path: '/y',
|
|
1536
|
+
// value: null,
|
|
1537
|
+
// message: 'Nombre attendu'
|
|
1538
|
+
// }, {
|
|
1539
|
+
// type: 14,
|
|
1540
|
+
// schema: { ... },
|
|
1541
|
+
// path: '/z',
|
|
1542
|
+
// value: null,
|
|
1543
|
+
// message: '예상 부울'
|
|
1544
|
+
// }]
|
|
1554
1545
|
```
|
|
1555
1546
|
|
|
1556
1547
|
<a name='typesystem-policies'></a>
|
|
1557
1548
|
|
|
1558
1549
|
### Policies
|
|
1559
1550
|
|
|
1560
|
-
TypeBox
|
|
1551
|
+
TypeBox validates using standard Json Schema assertion policies by default. The TypeSystemPolicy module can override some of these to have TypeBox check values inline with TypeScript static assertions. It also provides overrides for certain checking rules related to non-serializable values (such as void) which can be useful in Json based protocols such as JsonRpc-2.
|
|
1561
1552
|
|
|
1562
1553
|
The following overrides are available.
|
|
1563
1554
|
|
|
@@ -1582,7 +1573,7 @@ TypeSystemPolicy.AllowArrayObject = true
|
|
|
1582
1573
|
|
|
1583
1574
|
TypeSystemPolicy.AllowNaN = true
|
|
1584
1575
|
|
|
1585
|
-
// Allow void
|
|
1576
|
+
// Allow void types to check with undefined and null (default is false)
|
|
1586
1577
|
//
|
|
1587
1578
|
// Used to signal void return on Json-RPC 2.0 protocol
|
|
1588
1579
|
|
|
@@ -1601,7 +1592,7 @@ TypeBox offers a web based code generation tool that can convert TypeScript type
|
|
|
1601
1592
|
|
|
1602
1593
|
## TypeBox Codegen
|
|
1603
1594
|
|
|
1604
|
-
TypeBox provides
|
|
1595
|
+
TypeBox provides a code generation library that can be used to automate type translation between TypeScript and TypeBox. This library also includes functionality to transform TypeScript types to other ecosystem libraries.
|
|
1605
1596
|
|
|
1606
1597
|
[TypeBox Codegen Link Here](https://github.com/sinclairzx81/typebox-codegen)
|
|
1607
1598
|
|
|
@@ -1609,7 +1600,7 @@ TypeBox provides an auxilary code generation library that can be used to automat
|
|
|
1609
1600
|
|
|
1610
1601
|
## Ecosystem
|
|
1611
1602
|
|
|
1612
|
-
The following
|
|
1603
|
+
The following is a list of community packages that offer general tooling, extended functionality and framework integration support for TypeBox.
|
|
1613
1604
|
|
|
1614
1605
|
| Package | Description |
|
|
1615
1606
|
| ------------- | ------------- |
|