@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.
Files changed (100) hide show
  1. package/build/import/compiler/compiler.d.mts +3 -2
  2. package/build/import/compiler/compiler.mjs +3 -2
  3. package/build/import/errors/errors.d.mts +2 -1
  4. package/build/import/errors/errors.mjs +2 -1
  5. package/build/import/index.d.mts +1 -0
  6. package/build/import/index.mjs +1 -0
  7. package/build/import/system/system.d.mts +3 -2
  8. package/build/import/system/system.mjs +3 -2
  9. package/build/import/type/error/error.d.mts +4 -0
  10. package/build/import/type/error/error.mjs +6 -0
  11. package/build/import/type/error/index.d.mts +1 -0
  12. package/build/import/type/error/index.mjs +1 -0
  13. package/build/import/type/extends/extends-check.d.mts +2 -1
  14. package/build/import/type/extends/extends-check.mjs +2 -1
  15. package/build/import/type/guard/type.d.mts +2 -1
  16. package/build/import/type/guard/type.mjs +2 -1
  17. package/build/import/type/index.d.mts +1 -0
  18. package/build/import/type/index.mjs +1 -0
  19. package/build/import/type/record/record.d.mts +1 -1
  20. package/build/import/type/template-literal/finite.d.mts +2 -1
  21. package/build/import/type/template-literal/finite.mjs +2 -1
  22. package/build/import/type/template-literal/generate.d.mts +3 -2
  23. package/build/import/type/template-literal/generate.mjs +2 -1
  24. package/build/import/type/template-literal/parse.d.mts +2 -1
  25. package/build/import/type/template-literal/parse.mjs +2 -1
  26. package/build/import/type/template-literal/pattern.d.mts +2 -1
  27. package/build/import/type/template-literal/pattern.mjs +2 -1
  28. package/build/import/value/cast/cast.d.mts +5 -4
  29. package/build/import/value/cast/cast.mjs +5 -4
  30. package/build/import/value/check/check.d.mts +2 -1
  31. package/build/import/value/check/check.mjs +2 -1
  32. package/build/import/value/convert/convert.d.mts +2 -1
  33. package/build/import/value/convert/convert.mjs +2 -1
  34. package/build/import/value/create/create.d.mts +7 -6
  35. package/build/import/value/create/create.mjs +7 -6
  36. package/build/import/value/delta/delta.d.mts +3 -2
  37. package/build/import/value/delta/delta.mjs +3 -2
  38. package/build/import/value/deref/deref.d.mts +2 -1
  39. package/build/import/value/deref/deref.mjs +2 -1
  40. package/build/import/value/hash/hash.d.mts +2 -1
  41. package/build/import/value/hash/hash.mjs +2 -1
  42. package/build/import/value/mutate/mutate.d.mts +3 -2
  43. package/build/import/value/mutate/mutate.mjs +3 -2
  44. package/build/import/value/pointer/pointer.d.mts +3 -2
  45. package/build/import/value/pointer/pointer.mjs +3 -2
  46. package/build/import/value/transform/decode.d.mts +3 -2
  47. package/build/import/value/transform/decode.mjs +3 -2
  48. package/build/import/value/transform/encode.d.mts +3 -2
  49. package/build/import/value/transform/encode.mjs +3 -2
  50. package/build/require/compiler/compiler.d.ts +3 -2
  51. package/build/require/compiler/compiler.js +61 -60
  52. package/build/require/errors/errors.d.ts +2 -1
  53. package/build/require/errors/errors.js +34 -33
  54. package/build/require/index.d.ts +1 -0
  55. package/build/require/index.js +154 -152
  56. package/build/require/system/system.d.ts +3 -2
  57. package/build/require/system/system.js +3 -2
  58. package/build/require/type/error/error.d.ts +4 -0
  59. package/build/require/type/error/error.js +11 -0
  60. package/build/require/type/error/index.d.ts +1 -0
  61. package/build/require/type/error/index.js +18 -0
  62. package/build/require/type/extends/extends-check.d.ts +2 -1
  63. package/build/require/type/extends/extends-check.js +172 -171
  64. package/build/require/type/guard/type.d.ts +2 -1
  65. package/build/require/type/guard/type.js +2 -1
  66. package/build/require/type/index.d.ts +1 -0
  67. package/build/require/type/index.js +1 -0
  68. package/build/require/type/record/record.d.ts +1 -1
  69. package/build/require/type/template-literal/finite.d.ts +2 -1
  70. package/build/require/type/template-literal/finite.js +2 -1
  71. package/build/require/type/template-literal/generate.d.ts +3 -2
  72. package/build/require/type/template-literal/generate.js +2 -1
  73. package/build/require/type/template-literal/parse.d.ts +2 -1
  74. package/build/require/type/template-literal/parse.js +3 -2
  75. package/build/require/type/template-literal/pattern.d.ts +2 -1
  76. package/build/require/type/template-literal/pattern.js +2 -1
  77. package/build/require/value/cast/cast.d.ts +5 -4
  78. package/build/require/value/cast/cast.js +36 -35
  79. package/build/require/value/check/check.d.ts +2 -1
  80. package/build/require/value/check/check.js +24 -23
  81. package/build/require/value/convert/convert.d.ts +2 -1
  82. package/build/require/value/convert/convert.js +32 -31
  83. package/build/require/value/create/create.d.ts +7 -6
  84. package/build/require/value/create/create.js +7 -6
  85. package/build/require/value/delta/delta.d.ts +3 -2
  86. package/build/require/value/delta/delta.js +20 -19
  87. package/build/require/value/deref/deref.d.ts +2 -1
  88. package/build/require/value/deref/deref.js +2 -1
  89. package/build/require/value/hash/hash.d.ts +2 -1
  90. package/build/require/value/hash/hash.js +2 -1
  91. package/build/require/value/mutate/mutate.d.ts +3 -2
  92. package/build/require/value/mutate/mutate.js +3 -2
  93. package/build/require/value/pointer/pointer.d.ts +3 -2
  94. package/build/require/value/pointer/pointer.js +3 -2
  95. package/build/require/value/transform/decode.d.ts +3 -2
  96. package/build/require/value/transform/decode.js +19 -18
  97. package/build/require/value/transform/encode.d.ts +3 -2
  98. package/build/require/value/transform/encode.js +20 -19
  99. package/package.json +1 -1
  100. 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 Json Schema produced by this library is designed to match the static type checking rules of the TypeScript compiler. TypeBox provides a unified type that can be statically checked by the TypeScript compiler and runtime asserted using standard Json Schema validation.
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 enables Json Schema to be created with the same expressiveness as TypeScript's type system. It can be used either as a simple tool to build up complex schematics or integrated into REST or RPC services to help validate data received over the wire.
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
- - [Modules](#types-modules)
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-modules'></a>
646
+ <a name='types-import'></a>
647
647
 
648
- ### Modules
648
+ ### Import
649
649
 
650
- TypeBox supports a modular type system that allows for selective type imports. Using selective imports can be helpful in resource constrained environments as it enables modern bundlers to tree shake unused types. This can lead to reduced bundle sizes.
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 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.
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>(t: T) => Type.Object({ x: t, y: t, z: t })
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()) // const NumberVector = {
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 more complex types. The following creates a Nullable generic type.
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 Type.Ref. These types infer the same as the target type.
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 Type.Deref to dereference a type. This will replace any `$ref` with the target type.
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 reference types do not contain structural information about the type they're referencing. This means they cannot be used directly with some type mapping types (such as Partial) that require structural information to operate. For applications that need mapping on references, use Type.Deref to dereference the type first.
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 singular recursive data structures. Recursive type inference is also supported. The following creates a recursive Node data structure.
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 literals with Type.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 expression patterns which enables the template to be checked by Json Schema validators. This type also supports regular expression parsing, enabling template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.
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-conditional'></a>
901
+ <a name='types-indexed'></a>
921
902
 
922
- ### Conditional Types
903
+ ### Indexed Access Types
923
904
 
924
- TypeBox supports runtime Conditional types with Type.Extends. This type runs a structural assignability check against the first and second 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.
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
- // Extends
928
-
929
- type T = string extends number ? true : false // type T = false
930
-
931
- const T = Type.Extends( // const T: TLiteral<false>
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
- // Exclude
914
+ const A = Type.Index(T, ['x']) // type A = T['x']
915
+ //
916
+ // ... evaluates as
917
+ //
918
+ // const A: TNumber
952
919
 
953
- type T = Exclude<1 | 2 | 3, 1> // type T = 2 | 3
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 T = Type.Exclude( // const T: TUnion<[
956
- Type.Union([ // TLiteral<2>,
957
- Type.Literal(1), // TLiteral<3>
958
- Type.Literal(2), // ]>
959
- Type.Literal(3)
960
- ]),
961
- Type.Literal(1)
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 Mapped types with Type.Mapped. This type accepts two arguments, the first a union of literal keys and the second a type mapping function which receives a mapping key `K`. The following remaps the type `T` to be `Partial<T>` using type mapping.
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 M = Type.Mapped(Type.KeyOf(T), K => { // type M = { [K in keyof T]?: T[K] }
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
- // ... runtime mapped as
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-indexed'></a>
964
+ <a name='types-conditional'></a>
992
965
 
993
- ### Indexed Access Types
966
+ ### Conditional Types
994
967
 
995
- TypeBox supports Indexed Access types with Type.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.
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
- const T = Type.Object({ // const T: TObject<{
999
- x: Type.Number(), // x: TNumber,
1000
- y: Type.String(), // y: TString,
1001
- z: Type.Boolean() // z: TBoolean
1002
- }) // }>
1003
-
1004
- const A = Type.Index(T, ['x']) // const A: TNumber
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
- const B = Type.Index(T, ['x', 'y']) // const B: TUnion<[
1007
- // TNumber,
1008
- // TString,
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
- const C = Type.Index(T, Type.KeyOf(T)) // const C: TUnion<[
1012
- // TNumber,
1013
- // TString,
1014
- // TBoolean
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 Intrinsic String Manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap String Literal, Template Literal and Union of Literal types.
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 modules. 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 module.
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 type check its own types with the TypeGuard module. This module is written for reflection and provides structural tests for every built-in 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 `T` is TString.
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: unknown = { [Kind]: 'String', type: 'string' }
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 utility module that can be used to perform structural operations on JavaScript values. This module includes functionality to create, check and cast values from types as well as check equality, clone, diff and patch JavaScript values. This module is provided via optional import.
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
- Removes excess properties from a value and returns the result. 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.
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
- Generates 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.
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 cast a value with a type. The cast function will retain as much information as possible from the original value.
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, or throw if the value is invalid. The return value will infer as the decoded type. This function will run Transform codecs if available.
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, or throw if the value is invalid. The return value will infer as the encoded type. This function will run Transform codecs if available.
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 } } }) // const 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) // const A' = { x: 1, y: 0, z: 0 }
1427
- ValuePointer.Set(A, '/y', 1) // const A' = { x: 1, y: 1, z: 0 }
1428
- ValuePointer.Set(A, '/z', 1) // const A' = { x: 1, y: 1, 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 create high performance assertions that can be written to disk as importable modules. The following generates code to check a string.
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 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.
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-RPC 2.0 protocol
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 used to automate type translation between TypeScript and TypeBox. This library also includes functionality to transform TypeScript types to other ecosystem libraries.
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 │ '118.7 kb' │ ' 52.5 kb' │ '2.26 x' │
1819
- │ typebox/errors │ ' 55.1 kb' │ ' 25.2 kb' │ '2.19 x' │
1820
- │ typebox/system │ ' 4.6 kb' │ ' 2.0 kb' │ '2.31 x' │
1821
- │ typebox/value │ '144.8 kb' │ ' 61.8 kb' │ '2.34 x' │
1822
- │ typebox │ ' 87.7 kb' │ ' 36.7 kb' │ '2.39 x' │
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