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