@sinclair/typebox 0.32.0-dev-22 → 0.32.0-dev-24
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/build/import/compiler/compiler.d.mts +3 -2
- package/build/import/compiler/compiler.mjs +3 -2
- package/build/import/errors/errors.d.mts +2 -1
- package/build/import/errors/errors.mjs +2 -1
- package/build/import/index.d.mts +1 -0
- package/build/import/index.mjs +1 -0
- package/build/import/system/system.d.mts +3 -2
- package/build/import/system/system.mjs +3 -2
- package/build/import/type/error/error.d.mts +4 -0
- package/build/import/type/error/error.mjs +6 -0
- package/build/import/type/error/index.d.mts +1 -0
- package/build/import/type/error/index.mjs +1 -0
- package/build/import/type/extends/extends-check.d.mts +2 -1
- package/build/import/type/extends/extends-check.mjs +2 -1
- package/build/import/type/guard/type.d.mts +2 -1
- package/build/import/type/guard/type.mjs +2 -1
- package/build/import/type/index.d.mts +1 -0
- package/build/import/type/index.mjs +1 -0
- package/build/import/type/record/record.d.mts +1 -1
- package/build/import/type/template-literal/finite.d.mts +2 -1
- package/build/import/type/template-literal/finite.mjs +2 -1
- package/build/import/type/template-literal/generate.d.mts +3 -2
- package/build/import/type/template-literal/generate.mjs +2 -1
- package/build/import/type/template-literal/parse.d.mts +2 -1
- package/build/import/type/template-literal/parse.mjs +2 -1
- package/build/import/type/template-literal/pattern.d.mts +2 -1
- package/build/import/type/template-literal/pattern.mjs +2 -1
- package/build/import/value/cast/cast.d.mts +5 -4
- package/build/import/value/cast/cast.mjs +5 -4
- package/build/import/value/check/check.d.mts +2 -1
- package/build/import/value/check/check.mjs +2 -1
- package/build/import/value/convert/convert.d.mts +2 -1
- package/build/import/value/convert/convert.mjs +2 -1
- package/build/import/value/create/create.d.mts +7 -6
- package/build/import/value/create/create.mjs +7 -6
- package/build/import/value/delta/delta.d.mts +3 -2
- package/build/import/value/delta/delta.mjs +3 -2
- package/build/import/value/deref/deref.d.mts +2 -1
- package/build/import/value/deref/deref.mjs +2 -1
- package/build/import/value/hash/hash.d.mts +2 -1
- package/build/import/value/hash/hash.mjs +2 -1
- package/build/import/value/mutate/mutate.d.mts +3 -2
- package/build/import/value/mutate/mutate.mjs +3 -2
- package/build/import/value/pointer/pointer.d.mts +3 -2
- package/build/import/value/pointer/pointer.mjs +3 -2
- package/build/import/value/transform/decode.d.mts +3 -2
- package/build/import/value/transform/decode.mjs +3 -2
- package/build/import/value/transform/encode.d.mts +3 -2
- package/build/import/value/transform/encode.mjs +3 -2
- package/build/require/compiler/compiler.d.ts +3 -2
- package/build/require/compiler/compiler.js +61 -60
- package/build/require/errors/errors.d.ts +2 -1
- package/build/require/errors/errors.js +34 -33
- package/build/require/index.d.ts +1 -0
- package/build/require/index.js +154 -152
- package/build/require/system/system.d.ts +3 -2
- package/build/require/system/system.js +3 -2
- package/build/require/type/error/error.d.ts +4 -0
- package/build/require/type/error/error.js +11 -0
- package/build/require/type/error/index.d.ts +1 -0
- package/build/require/type/error/index.js +18 -0
- package/build/require/type/extends/extends-check.d.ts +2 -1
- package/build/require/type/extends/extends-check.js +172 -171
- package/build/require/type/guard/type.d.ts +2 -1
- package/build/require/type/guard/type.js +2 -1
- package/build/require/type/index.d.ts +1 -0
- package/build/require/type/index.js +1 -0
- package/build/require/type/record/record.d.ts +1 -1
- package/build/require/type/template-literal/finite.d.ts +2 -1
- package/build/require/type/template-literal/finite.js +2 -1
- package/build/require/type/template-literal/generate.d.ts +3 -2
- package/build/require/type/template-literal/generate.js +2 -1
- package/build/require/type/template-literal/parse.d.ts +2 -1
- package/build/require/type/template-literal/parse.js +3 -2
- package/build/require/type/template-literal/pattern.d.ts +2 -1
- package/build/require/type/template-literal/pattern.js +2 -1
- package/build/require/value/cast/cast.d.ts +5 -4
- package/build/require/value/cast/cast.js +36 -35
- package/build/require/value/check/check.d.ts +2 -1
- package/build/require/value/check/check.js +24 -23
- package/build/require/value/convert/convert.d.ts +2 -1
- package/build/require/value/convert/convert.js +32 -31
- package/build/require/value/create/create.d.ts +7 -6
- package/build/require/value/create/create.js +7 -6
- package/build/require/value/delta/delta.d.ts +3 -2
- package/build/require/value/delta/delta.js +20 -19
- package/build/require/value/deref/deref.d.ts +2 -1
- package/build/require/value/deref/deref.js +2 -1
- package/build/require/value/hash/hash.d.ts +2 -1
- package/build/require/value/hash/hash.js +2 -1
- package/build/require/value/mutate/mutate.d.ts +3 -2
- package/build/require/value/mutate/mutate.js +3 -2
- package/build/require/value/pointer/pointer.d.ts +3 -2
- package/build/require/value/pointer/pointer.js +3 -2
- package/build/require/value/transform/decode.d.ts +3 -2
- package/build/require/value/transform/decode.js +19 -18
- package/build/require/value/transform/encode.d.ts +3 -2
- package/build/require/value/transform/encode.js +20 -19
- package/package.json +1 -1
- package/readme.md +117 -137
package/readme.md
CHANGED
|
@@ -51,9 +51,9 @@ type T = Static<typeof T> // type T = {
|
|
|
51
51
|
|
|
52
52
|
## Overview
|
|
53
53
|
|
|
54
|
-
TypeBox is a runtime type builder that creates in-memory Json Schema objects that infer as TypeScript types. The
|
|
54
|
+
TypeBox is a runtime type builder that creates in-memory Json Schema objects that infer as TypeScript types. The schematics 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 asserted using standard Json Schema validation.
|
|
55
55
|
|
|
56
|
-
This library
|
|
56
|
+
This library is designed to be a runtime type system with capabilities similar to TypeScript's static type system. It can be used as a simple tool to build up complex schematics or integrated into REST and RPC services to help validate data received over the wire.
|
|
57
57
|
|
|
58
58
|
License MIT
|
|
59
59
|
|
|
@@ -64,16 +64,16 @@ License MIT
|
|
|
64
64
|
- [Types](#types)
|
|
65
65
|
- [Json](#types-json)
|
|
66
66
|
- [JavaScript](#types-javascript)
|
|
67
|
-
- [
|
|
67
|
+
- [Import](#types-import)
|
|
68
68
|
- [Options](#types-options)
|
|
69
69
|
- [Properties](#types-properties)
|
|
70
70
|
- [Generics](#types-generics)
|
|
71
71
|
- [References](#types-references)
|
|
72
72
|
- [Recursive](#types-recursive)
|
|
73
73
|
- [Template Literal](#types-template-literal)
|
|
74
|
-
- [Conditional](#types-conditional)
|
|
75
|
-
- [Mapped](#types-mapped)
|
|
76
74
|
- [Indexed](#types-indexed)
|
|
75
|
+
- [Mapped](#types-mapped)
|
|
76
|
+
- [Conditional](#types-conditional)
|
|
77
77
|
- [Intrinsic](#types-intrinsic)
|
|
78
78
|
- [Transform](#types-transform)
|
|
79
79
|
- [Rest](#types-rest)
|
|
@@ -643,33 +643,25 @@ TypeBox provides an extended type set that can be used to create schematics for
|
|
|
643
643
|
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
|
|
644
644
|
```
|
|
645
645
|
|
|
646
|
-
<a name='types-
|
|
646
|
+
<a name='types-import'></a>
|
|
647
647
|
|
|
648
|
-
###
|
|
648
|
+
### Import
|
|
649
649
|
|
|
650
|
-
|
|
650
|
+
You can import Type to bring in the full type system. This is recommended for most users.
|
|
651
651
|
|
|
652
|
+
```typescript
|
|
653
|
+
import { Type, type Static } from '@sinclair/typebox'
|
|
654
|
+
```
|
|
655
|
+
You can also import types individually. This approach enables modern bundlers to tree shake unused types.
|
|
652
656
|
```typescript
|
|
653
657
|
import { Object, Number, String, Boolean, type Static } from '@sinclair/typebox'
|
|
654
|
-
|
|
655
|
-
const T = Object({ // const T: TObject<{
|
|
656
|
-
x: Number(), // x: TNumber,
|
|
657
|
-
y: String(), // y: TString,
|
|
658
|
-
z: Boolean() // z: TBoolean
|
|
659
|
-
}) // }>
|
|
660
|
-
|
|
661
|
-
type T = Static<typeof T> // type T = {
|
|
662
|
-
// x: number,
|
|
663
|
-
// y: string,
|
|
664
|
-
// z: boolean
|
|
665
|
-
// }
|
|
666
658
|
```
|
|
667
659
|
|
|
668
660
|
<a name='types-options'></a>
|
|
669
661
|
|
|
670
662
|
### Options
|
|
671
663
|
|
|
672
|
-
You can pass Json Schema options on the last argument of any type. Option hints specific to each type are provided for convenience.
|
|
664
|
+
You can pass Json Schema options on the last argument of any given type. Option hints specific to each type are provided for convenience.
|
|
673
665
|
|
|
674
666
|
```typescript
|
|
675
667
|
// String must be an email
|
|
@@ -742,31 +734,22 @@ Object properties can be modified with Readonly and Optional. The following tabl
|
|
|
742
734
|
|
|
743
735
|
### Generic Types
|
|
744
736
|
|
|
745
|
-
Generic types can be created with
|
|
737
|
+
Generic types can be created with functions. TypeBox types extend the TSchema interface so you should constrain parameters to this type. The following creates a generic Vector type.
|
|
746
738
|
|
|
747
739
|
```typescript
|
|
748
740
|
import { Type, type Static, type TSchema } from '@sinclair/typebox'
|
|
749
741
|
|
|
750
|
-
const Vector = <T extends TSchema>(
|
|
742
|
+
const Vector = <T extends TSchema>(T: T) =>
|
|
743
|
+
Type.Object({ // type Vector<T> = {
|
|
744
|
+
x: T, // x: T,
|
|
745
|
+
y: T, // y: T,
|
|
746
|
+
z: T // z: T
|
|
747
|
+
}) // }
|
|
751
748
|
|
|
752
|
-
const NumberVector = Vector(Type.Number()) //
|
|
753
|
-
// type: 'object',
|
|
754
|
-
// required: ['x', 'y', 'z'],
|
|
755
|
-
// properties: {
|
|
756
|
-
// x: { type: 'number' },
|
|
757
|
-
// y: { type: 'number' },
|
|
758
|
-
// z: { type: 'number' }
|
|
759
|
-
// }
|
|
760
|
-
// }
|
|
761
|
-
|
|
762
|
-
type NumberVector = Static<typeof NumberVector> // type NumberVector = {
|
|
763
|
-
// x: number,
|
|
764
|
-
// y: number,
|
|
765
|
-
// z: number
|
|
766
|
-
// }
|
|
749
|
+
const NumberVector = Vector(Type.Number()) // type NumberVector = Vector<number>
|
|
767
750
|
```
|
|
768
751
|
|
|
769
|
-
Generic types are often used to create aliases for
|
|
752
|
+
Generic types are often used to create aliases for complex types. The following creates a Nullable generic type.
|
|
770
753
|
|
|
771
754
|
```typescript
|
|
772
755
|
const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])
|
|
@@ -785,7 +768,7 @@ type T = Static<typeof T> // type T = string | null
|
|
|
785
768
|
|
|
786
769
|
### Reference Types
|
|
787
770
|
|
|
788
|
-
Reference types can be created with
|
|
771
|
+
Reference types can be created with Ref. These types infer the same as the target type but only store a named `$ref` to the target type.
|
|
789
772
|
|
|
790
773
|
```typescript
|
|
791
774
|
const Vector = Type.Object({ // const Vector = {
|
|
@@ -807,7 +790,7 @@ type VectorRef = Static<typeof VectorRef> // type VectorRef = {
|
|
|
807
790
|
// y: number
|
|
808
791
|
// }
|
|
809
792
|
```
|
|
810
|
-
Use
|
|
793
|
+
Use Deref to dereference a type. This function will replace any interior reference with the target type.
|
|
811
794
|
```typescript
|
|
812
795
|
const Vertex = Type.Object({ // const Vertex = {
|
|
813
796
|
position: VectorRef, // type: 'object',
|
|
@@ -840,16 +823,14 @@ const VertexDeref = Type.Deref(Vertex, [Vector]) // const VertexDeref = {
|
|
|
840
823
|
// }
|
|
841
824
|
// }
|
|
842
825
|
// }
|
|
843
|
-
|
|
844
|
-
|
|
845
826
|
```
|
|
846
|
-
Note that
|
|
827
|
+
Note that Ref types do not store structural information about the type they're referencing. Because of this, these types cannot be used with some mapping types (such as Partial or Pick). For applications that require mapping on Ref, use Deref to normalize the type first.
|
|
847
828
|
|
|
848
829
|
<a name='types-recursive'></a>
|
|
849
830
|
|
|
850
831
|
### Recursive Types
|
|
851
832
|
|
|
852
|
-
TypeBox supports
|
|
833
|
+
TypeBox supports recursive data structures with Recursive. This type wraps an interior type and provides it a `this` context that allows the type to reference itself. The following creates a recursive type. Singular recursive inference is also supported.
|
|
853
834
|
|
|
854
835
|
```typescript
|
|
855
836
|
const Node = Type.Recursive(This => Type.Object({ // const Node = {
|
|
@@ -886,7 +867,7 @@ function test(node: Node) {
|
|
|
886
867
|
|
|
887
868
|
### Template Literal Types
|
|
888
869
|
|
|
889
|
-
TypeBox supports template
|
|
870
|
+
TypeBox supports template literal types with TemplateLiteral. This type can be created using a syntax similar to the TypeScript template literal syntax or composed from exterior types. TypeBox encodes template literals as regular expressions which enables the template to be checked by Json Schema validators. This type also supports regular expression parsing that enables template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.
|
|
890
871
|
|
|
891
872
|
```typescript
|
|
892
873
|
// TypeScript
|
|
@@ -917,56 +898,50 @@ const R = Type.Record(K, Type.String()) // const R: TObject<{
|
|
|
917
898
|
// }>
|
|
918
899
|
```
|
|
919
900
|
|
|
920
|
-
<a name='types-
|
|
901
|
+
<a name='types-indexed'></a>
|
|
921
902
|
|
|
922
|
-
###
|
|
903
|
+
### Indexed Access Types
|
|
923
904
|
|
|
924
|
-
TypeBox supports
|
|
905
|
+
TypeBox supports indexed access types with Index. This type enables uniform access to interior property and element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
|
|
925
906
|
|
|
926
907
|
```typescript
|
|
927
|
-
//
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
Type.String(),
|
|
933
|
-
Type.Number(),
|
|
934
|
-
Type.Literal(true),
|
|
935
|
-
Type.Literal(false)
|
|
936
|
-
)
|
|
937
|
-
|
|
938
|
-
// Extract
|
|
939
|
-
|
|
940
|
-
type T = Extract<1 | 2 | 3, 1> // type T = 1
|
|
941
|
-
|
|
942
|
-
const T = Type.Extract( // const T: TLiteral<1>
|
|
943
|
-
Type.Union([
|
|
944
|
-
Type.Literal(1),
|
|
945
|
-
Type.Literal(2),
|
|
946
|
-
Type.Literal(3)
|
|
947
|
-
]),
|
|
948
|
-
Type.Literal(1)
|
|
949
|
-
)
|
|
908
|
+
const T = Type.Object({ // const T: TObject<{
|
|
909
|
+
x: Type.Number(), // x: TNumber,
|
|
910
|
+
y: Type.String(), // y: TString,
|
|
911
|
+
z: Type.Boolean() // z: TBoolean
|
|
912
|
+
}) // }>
|
|
950
913
|
|
|
951
|
-
//
|
|
914
|
+
const A = Type.Index(T, ['x']) // type A = T['x']
|
|
915
|
+
//
|
|
916
|
+
// ... evaluates as
|
|
917
|
+
//
|
|
918
|
+
// const A: TNumber
|
|
952
919
|
|
|
953
|
-
|
|
920
|
+
const B = Type.Index(T, ['x', 'y']) // type B = T['x' | 'y']
|
|
921
|
+
//
|
|
922
|
+
// ... evaluates as
|
|
923
|
+
//
|
|
924
|
+
// const B: TUnion<[
|
|
925
|
+
// TNumber,
|
|
926
|
+
// TString,
|
|
927
|
+
// ]>
|
|
954
928
|
|
|
955
|
-
const
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
929
|
+
const C = Type.Index(T, Type.KeyOf(T)) // type C = T[keyof T]
|
|
930
|
+
//
|
|
931
|
+
// ... evaluates as
|
|
932
|
+
//
|
|
933
|
+
// const C: TUnion<[
|
|
934
|
+
// TNumber,
|
|
935
|
+
// TString,
|
|
936
|
+
// TBoolean
|
|
937
|
+
// ]>
|
|
963
938
|
```
|
|
964
939
|
|
|
965
940
|
<a name='types-mapped'></a>
|
|
966
941
|
|
|
967
942
|
### Mapped Types
|
|
968
943
|
|
|
969
|
-
TypeBox supports
|
|
944
|
+
TypeBox supports mapped object types with Mapped. This type accepts two arguments, the first is a union type typically derived from KeyOf, the second is a mapping function that receives a mapping key `K` that can be used to index properties of a type. The following implements Partial using mapped types.
|
|
970
945
|
|
|
971
946
|
```typescript
|
|
972
947
|
const T = Type.Object({ // const T: TObject<{
|
|
@@ -975,61 +950,68 @@ const T = Type.Object({ // const T: TObject<{
|
|
|
975
950
|
z: Type.Boolean() // z: TBoolean
|
|
976
951
|
}) // }>
|
|
977
952
|
|
|
978
|
-
const
|
|
953
|
+
const P = Type.Mapped(Type.KeyOf(T), K => { // type P = { [K in keyof T]?: T[K] }
|
|
979
954
|
return Type.Optional(Type.Index(T, K)) //
|
|
980
|
-
}) //
|
|
981
|
-
|
|
982
|
-
//
|
|
983
|
-
//
|
|
984
|
-
// const M: TObject<{
|
|
955
|
+
}) // ... evaluated as
|
|
956
|
+
//
|
|
957
|
+
// const P: TObject<{
|
|
985
958
|
// x: TOptional<TNumber>,
|
|
986
959
|
// y: TOptional<TString>,
|
|
987
960
|
// z: TOptional<TBoolean>
|
|
988
961
|
// }>
|
|
989
962
|
```
|
|
990
963
|
|
|
991
|
-
<a name='types-
|
|
964
|
+
<a name='types-conditional'></a>
|
|
992
965
|
|
|
993
|
-
###
|
|
966
|
+
### Conditional Types
|
|
994
967
|
|
|
995
|
-
TypeBox supports
|
|
968
|
+
TypeBox supports runtime conditional types with Extends. This type performs a structural assignability check against the first (`left`) and second (`right`) arguments and will return either the third (`true`) or fourth (`false`) argument based on the result. The conditional types Exclude and Extract are also supported. The following shows both TypeScript and TypeBox examples of conditional types.
|
|
996
969
|
|
|
997
970
|
```typescript
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
971
|
+
// Extends
|
|
972
|
+
const T = Type.Extends( // type T = string extends number ? true : false
|
|
973
|
+
Type.String(), //
|
|
974
|
+
Type.Number(), // ... evaluated as
|
|
975
|
+
Type.Literal(true), //
|
|
976
|
+
Type.Literal(false) // const T: TLiteral<false>
|
|
977
|
+
)
|
|
1005
978
|
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
979
|
+
// Extract
|
|
980
|
+
const T = Type.Extract( // type T = Extract<1 | 2 | 3, 1>
|
|
981
|
+
Type.Union([ //
|
|
982
|
+
Type.Literal(1), // ... evaluated as
|
|
983
|
+
Type.Literal(2), //
|
|
984
|
+
Type.Literal(3) // const T: TLiteral<1>
|
|
985
|
+
]),
|
|
986
|
+
Type.Literal(1)
|
|
987
|
+
)
|
|
1010
988
|
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
989
|
+
// Exclude
|
|
990
|
+
const T = Type.Exclude( // type T = Exclude<1 | 2 | 3, 1>
|
|
991
|
+
Type.Union([ //
|
|
992
|
+
Type.Literal(1), // ... evaluated as
|
|
993
|
+
Type.Literal(2), //
|
|
994
|
+
Type.Literal(3) // const T: TUnion<[
|
|
995
|
+
]), // TLiteral<2>,
|
|
996
|
+
Type.Literal(1) // TLiteral<3>,
|
|
997
|
+
) // ]>
|
|
1016
998
|
```
|
|
1017
999
|
|
|
1018
1000
|
<a name='types-intrinsic'></a>
|
|
1019
1001
|
|
|
1020
1002
|
### Intrinsic Types
|
|
1021
1003
|
|
|
1022
|
-
TypeBox supports the TypeScript
|
|
1004
|
+
TypeBox supports the TypeScript intrinsic string manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap Literal, Template Literal and Union of Literal types.
|
|
1023
1005
|
|
|
1024
1006
|
```typescript
|
|
1025
1007
|
// TypeScript
|
|
1026
|
-
|
|
1027
1008
|
type A = Capitalize<'hello'> // type A = 'Hello'
|
|
1009
|
+
|
|
1028
1010
|
type B = Capitalize<'hello' | 'world'> // type C = 'Hello' | 'World'
|
|
1011
|
+
|
|
1029
1012
|
type C = Capitalize<`hello${1|2|3}`> // type B = 'Hello1' | 'Hello2' | 'Hello3'
|
|
1030
1013
|
|
|
1031
1014
|
// TypeBox
|
|
1032
|
-
|
|
1033
1015
|
const A = Type.Capitalize(Type.Literal('hello')) // const A: TLiteral<'Hello'>
|
|
1034
1016
|
|
|
1035
1017
|
const B = Type.Capitalize(Type.Union([ // const B: TUnion<[
|
|
@@ -1051,7 +1033,7 @@ const C = Type.Capitalize( // const C: TTemplateLitera
|
|
|
1051
1033
|
|
|
1052
1034
|
### Transform Types
|
|
1053
1035
|
|
|
1054
|
-
TypeBox supports value decoding and encoding with Transform types. These types work in tandem with the Encode and Decode functions available on the Value and TypeCompiler
|
|
1036
|
+
TypeBox supports value decoding and encoding with Transform types. These types work in tandem with the Encode and Decode functions available on the Value and TypeCompiler submodules. Transform types can be used to convert Json encoded values into constructs more natural to JavaScript. The following creates a Transform type to decode numbers into Dates using the Value submodule.
|
|
1055
1037
|
|
|
1056
1038
|
```typescript
|
|
1057
1039
|
import { Value } from '@sinclair/typebox/value'
|
|
@@ -1103,13 +1085,11 @@ const U = Type.Union(R) // const T: TUnion<[
|
|
|
1103
1085
|
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.
|
|
1104
1086
|
|
|
1105
1087
|
```typescript
|
|
1106
|
-
const T = Type.Unsafe<string>({ type: 'number' }) // const T = {
|
|
1107
|
-
// type: 'number'
|
|
1108
|
-
// }
|
|
1088
|
+
const T = Type.Unsafe<string>({ type: 'number' }) // const T = { type: 'number' }
|
|
1109
1089
|
|
|
1110
1090
|
type T = Static<typeof T> // type T = string - ?
|
|
1111
1091
|
```
|
|
1112
|
-
The Unsafe type is often used to create schematics for extended specifications like OpenAPI
|
|
1092
|
+
The Unsafe type is often used to create schematics for extended specifications like OpenAPI.
|
|
1113
1093
|
```typescript
|
|
1114
1094
|
|
|
1115
1095
|
const Nullable = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T> | null>({
|
|
@@ -1136,12 +1116,12 @@ type S = Static<typeof T> // type S = 'A' | 'B' | 'C'
|
|
|
1136
1116
|
|
|
1137
1117
|
### TypeGuard
|
|
1138
1118
|
|
|
1139
|
-
TypeBox can
|
|
1119
|
+
TypeBox can check its own types with the TypeGuard module. This module is written for type introspection and provides structural tests for every built-in TypeBox type. Functions of this module return `is` guards which can be used with control flow assertions to obtain schema inference for unknown values. The following guards that the value `T` is TString.
|
|
1140
1120
|
|
|
1141
1121
|
```typescript
|
|
1142
1122
|
import { TypeGuard, Kind } from '@sinclair/typebox'
|
|
1143
1123
|
|
|
1144
|
-
const T
|
|
1124
|
+
const T = { [Kind]: 'String', type: 'string' }
|
|
1145
1125
|
|
|
1146
1126
|
if(TypeGuard.IsString(T)) {
|
|
1147
1127
|
|
|
@@ -1182,7 +1162,7 @@ const U = Type.Strict(T) // const U = {
|
|
|
1182
1162
|
|
|
1183
1163
|
## Values
|
|
1184
1164
|
|
|
1185
|
-
TypeBox provides an optional
|
|
1165
|
+
TypeBox provides an optional Value submodule that can be used to perform structural operations on JavaScript values. This submodule includes functionality to create, check and cast values from types as well as check equality, clone, diff and patch JavaScript values. This submodule is provided via optional import.
|
|
1186
1166
|
|
|
1187
1167
|
```typescript
|
|
1188
1168
|
import { Value } from '@sinclair/typebox/value'
|
|
@@ -1240,7 +1220,7 @@ const R2 = Value.Convert(T, { x: 'not a number' }) // const R2 = { x: 'not a n
|
|
|
1240
1220
|
|
|
1241
1221
|
### Clean
|
|
1242
1222
|
|
|
1243
|
-
|
|
1223
|
+
Use Clean to remove excess properties from a value. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first.
|
|
1244
1224
|
|
|
1245
1225
|
```typescript
|
|
1246
1226
|
const T = Type.Object({
|
|
@@ -1259,7 +1239,7 @@ const Z = Value.Clean(T, { x: 1, y: 2, z: 3 }) // const 'Z = { x: 1, y: 2
|
|
|
1259
1239
|
|
|
1260
1240
|
### Default
|
|
1261
1241
|
|
|
1262
|
-
|
|
1242
|
+
Use Default to generate missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first.
|
|
1263
1243
|
|
|
1264
1244
|
```typescript
|
|
1265
1245
|
const T = Type.Object({
|
|
@@ -1278,7 +1258,7 @@ const Z = Value.Default(T, { x: 1 }) // const 'Z = { x: 1, y:
|
|
|
1278
1258
|
|
|
1279
1259
|
### Cast
|
|
1280
1260
|
|
|
1281
|
-
Use the Cast function to
|
|
1261
|
+
Use the Cast function to upcast a value into a target type. This function will retain as much infomation as possible from the original value. The Cast function is intended to be used in data migration scenarios where existing values need to be upgraded to match a modified type.
|
|
1282
1262
|
|
|
1283
1263
|
```typescript
|
|
1284
1264
|
const T = Type.Object({ x: Type.Number(), y: Type.Number() }, { additionalProperties: false })
|
|
@@ -1294,7 +1274,7 @@ const Z = Value.Cast(T, { x: 1, y: 2, z: 3 }) // const Z = { x: 1, y: 2 }
|
|
|
1294
1274
|
|
|
1295
1275
|
### Decode
|
|
1296
1276
|
|
|
1297
|
-
Use the Decode function to decode a value from a type
|
|
1277
|
+
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.
|
|
1298
1278
|
|
|
1299
1279
|
```typescript
|
|
1300
1280
|
const A = Value.Decode(Type.String(), 'hello') // const A = 'hello'
|
|
@@ -1305,7 +1285,7 @@ const B = Value.Decode(Type.String(), 42) // throw
|
|
|
1305
1285
|
|
|
1306
1286
|
### Encode
|
|
1307
1287
|
|
|
1308
|
-
Use the Encode function to encode a value to a type
|
|
1288
|
+
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.
|
|
1309
1289
|
|
|
1310
1290
|
```typescript
|
|
1311
1291
|
const A = Value.Encode(Type.String(), 'hello') // const A = 'hello'
|
|
@@ -1405,7 +1385,7 @@ const Y = { z: 1 } // const Y = { z: 1 }
|
|
|
1405
1385
|
const X = { y: Y } // const X = { y: { z: 1 } }
|
|
1406
1386
|
const A = { x: X } // const A = { x: { y: { z: 1 } } }
|
|
1407
1387
|
|
|
1408
|
-
Value.Mutate(A, { x: { y: { z: 2 } } }) //
|
|
1388
|
+
Value.Mutate(A, { x: { y: { z: 2 } } }) // A' = { x: { y: { z: 2 } } }
|
|
1409
1389
|
|
|
1410
1390
|
const R0 = A.x.y.z === 2 // const R0 = true
|
|
1411
1391
|
const R1 = A.x.y === Y // const R1 = true
|
|
@@ -1423,9 +1403,9 @@ import { ValuePointer } from '@sinclair/typebox/value'
|
|
|
1423
1403
|
|
|
1424
1404
|
const A = { x: 0, y: 0, z: 0 }
|
|
1425
1405
|
|
|
1426
|
-
ValuePointer.Set(A, '/x', 1) //
|
|
1427
|
-
ValuePointer.Set(A, '/y', 1) //
|
|
1428
|
-
ValuePointer.Set(A, '/z', 1) //
|
|
1406
|
+
ValuePointer.Set(A, '/x', 1) // A' = { x: 1, y: 0, z: 0 }
|
|
1407
|
+
ValuePointer.Set(A, '/y', 1) // A' = { x: 1, y: 1, z: 0 }
|
|
1408
|
+
ValuePointer.Set(A, '/z', 1) // A' = { x: 1, y: 1, z: 1 }
|
|
1429
1409
|
```
|
|
1430
1410
|
|
|
1431
1411
|
<a name='typeregistry'></a>
|
|
@@ -1575,7 +1555,7 @@ const all = [...C.Errors(value)] // const all = [{
|
|
|
1575
1555
|
// }]
|
|
1576
1556
|
```
|
|
1577
1557
|
|
|
1578
|
-
Use the Code function to generate assertion functions as strings. This function can be used to
|
|
1558
|
+
Use the Code function to generate assertion functions as strings. This function can be used to generate code that can be written to disk as importable modules. This technique is sometimes referred to as Ahead of Time (AOT) compilation. The following generates code to check a string.
|
|
1579
1559
|
|
|
1580
1560
|
```typescript
|
|
1581
1561
|
const C = TypeCompiler.Code(Type.String()) // const C = `return function check(value) {
|
|
@@ -1595,7 +1575,7 @@ The TypeBox TypeSystem module provides configurations to use either Json Schema
|
|
|
1595
1575
|
|
|
1596
1576
|
### Policies
|
|
1597
1577
|
|
|
1598
|
-
TypeBox validates using standard Json Schema assertion policies by default. The TypeSystemPolicy module can override some of these to have TypeBox
|
|
1578
|
+
TypeBox validates using standard Json Schema assertion policies by default. The TypeSystemPolicy module can override some of these to have TypeBox assert values inline with TypeScript static checks. It also provides overrides for certain checking rules related to non-serializable values (such as void) which can be helpful in Json based protocols such as Json Rpc 2.0.
|
|
1599
1579
|
|
|
1600
1580
|
The following overrides are available.
|
|
1601
1581
|
|
|
@@ -1622,7 +1602,7 @@ TypeSystemPolicy.AllowNaN = true
|
|
|
1622
1602
|
|
|
1623
1603
|
// Allow void types to check with undefined and null (default is false)
|
|
1624
1604
|
//
|
|
1625
|
-
// Used to signal void return on Json-
|
|
1605
|
+
// Used to signal void return on Json-Rpc 2.0 protocol
|
|
1626
1606
|
|
|
1627
1607
|
TypeSystemPolicy.AllowNullVoid = true
|
|
1628
1608
|
```
|
|
@@ -1686,7 +1666,7 @@ TypeBox offers a web based code generation tool that can convert TypeScript type
|
|
|
1686
1666
|
|
|
1687
1667
|
## TypeBox Codegen
|
|
1688
1668
|
|
|
1689
|
-
TypeBox provides a code generation library that can be
|
|
1669
|
+
TypeBox provides a code generation library that can be integrated into toolchains to automate type translation between TypeScript and TypeBox. This library also includes functionality to transform TypeScript types to other ecosystem libraries.
|
|
1690
1670
|
|
|
1691
1671
|
[TypeBox Codegen Link Here](https://github.com/sinclairzx81/typebox-codegen)
|
|
1692
1672
|
|
|
@@ -1815,11 +1795,11 @@ The following table lists esbuild compiled and minified sizes for each TypeBox m
|
|
|
1815
1795
|
┌──────────────────────┬────────────┬────────────┬─────────────┐
|
|
1816
1796
|
│ (index) │ Compiled │ Minified │ Compression │
|
|
1817
1797
|
├──────────────────────┼────────────┼────────────┼─────────────┤
|
|
1818
|
-
│ typebox/compiler │ '
|
|
1819
|
-
│ typebox/errors │ ' 55.
|
|
1820
|
-
│ typebox/system │ ' 4.
|
|
1821
|
-
│ typebox/value │ '
|
|
1822
|
-
│ typebox │ '
|
|
1798
|
+
│ typebox/compiler │ '119.9 kb' │ ' 52.5 kb' │ '2.29 x' │
|
|
1799
|
+
│ typebox/errors │ ' 55.5 kb' │ ' 25.2 kb' │ '2.21 x' │
|
|
1800
|
+
│ typebox/system │ ' 4.7 kb' │ ' 2.0 kb' │ '2.33 x' │
|
|
1801
|
+
│ typebox/value │ '146.8 kb' │ ' 61.9 kb' │ '2.37 x' │
|
|
1802
|
+
│ typebox │ ' 90.7 kb' │ ' 37.7 kb' │ '2.40 x' │
|
|
1823
1803
|
└──────────────────────┴────────────┴────────────┴─────────────┘
|
|
1824
1804
|
```
|
|
1825
1805
|
|