@sinclair/typebox 0.26.0-dev.4 → 0.26.0

package/readme.md

@@ -4,7 +4,7 @@
 
 <p>JSON Schema Type Builder with Static Type Resolution for TypeScript</p>
 	
-<img src="./typebox.png" />
+<img src="https://github.com/sinclairzx81/typebox/blob/master/typebox.png?raw=true" />
 
 <br />
 <br />
@@ -62,9 +62,9 @@ type T = Static<typeof T>                            // type T = {
 
 ## Overview
 
-TypeBox is a runtime type builder that constructs in-memory JSON Schema objects that can be statically inferred as TypeScript types. The schemas produced by this library are designed to match the static type checking rules of the TypeScript compiler. TypeBox enables one to create a unified type that can be statically checked by TypeScript and runtime asserted using standard JSON Schema validation.
+TypeBox is a runtime type builder that creates in-memory JSON Schema objects that can be statically inferred as TypeScript types. The schemas produced by this library are designed to match the static type assertion rules of the TypeScript compiler. TypeBox enables one to create a unified type that can be statically checked by TypeScript and runtime asserted using standard JSON Schema validation.
 
-This library is designed to enable JSON schema to compose with the same flexibility as TypeScript's type system. It can be used as a simple tool to build up complex schemas or integrated into REST and RPC services to help validate data received over the wire. 
+This library is designed to enable JSON schema to compose with the same flexibility as TypeScript's type system. It can be used as a simple tool to build up complex schemas or integrated into REST or RPC services to help validate data received over the wire. 
 
 License MIT
 
@@ -189,13 +189,13 @@ function receive(value: T) {                         // ... as a Static Type
 
 ## Types
 
-TypeBox types are small JSON schema fragments which can compose into more complex types though function composition. Each fragment is strictly defined to match to the static type checking rules of TypeScript. TypeBox provides a Standard type set which produces standards compliant JSON schema as well as an Extended type set used to define native JavaScript constructs.
+TypeBox types are JSON schema fragments that can be composed into more complex types. Each fragment is structured such that a JSON schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox provides a set of Standard types which are used create JSON schema compliant schematics as well as an Extended type set used to create schematics for constructs native to JavaScript. 
 
 <a name='types-standard'></a>
 
 ### Standard Types
 
-The following table lists the Standard TypeBox types. These types are fully compatible with the JSON Schema specification.
+The following table lists the Standard TypeBox types. These types are fully compatible with the JSON Schema Draft 6 specification.
 
 ```typescript
 ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
@@ -457,17 +457,6 @@ The following table lists the Standard TypeBox types. These types are fully comp
 │                                │                             │                                │
 │                                │                             │                                │
 │                                │                             │                                │
-├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
-│ const A = Type.Object({        │ type T = {                  │ const T = {                    │
-│    x: Type.Number(),           │   x: number,                │   $id: 'T'                     │
-│    y: Type.Number()            │   y: number                 │   type: 'object',              │
-│ }, { $id: 'T' })               | }                           │   required: ['x', 'y'],        │
-│                                │                             │   properties: {                │
-│ const T = Type.Deref(          │                             │     x: { type: 'number' },     │
-│   Type.Ref(A)                  │                             │     y: { type: 'number' },     │
-│ )                              │                             │   }                            │
-│                                │                             │ }                              │
-│                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
 ```
 
@@ -475,9 +464,7 @@ The following table lists the Standard TypeBox types. These types are fully comp
 
 ### Extended Types
 
-TypeBox provides several extended types that can be used to produce schematics for common JavaScript constructs. These types cannot be used with standard JSON schema validators; but are useful to help frame schematics for RPC interfaces that may receive JSON validated data. Extended types are prefixed with the `[Extended]` doc comment for convenience.
-
-The following lists the supported types
+TypeBox provides several extended types that can be used to produce schematics for common JavaScript constructs. These types can not be used with standard JSON schema validators; but are useful to help frame schematics for RPC interfaces that may receive JSON validated data. Extended types are prefixed with the `[Extended]` doc comment for convenience. The following table lists the supported types.
 
 ```typescript
 ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
@@ -570,7 +557,7 @@ The following lists the supported types
 
 ### Modifiers
 
-TypeBox provides property modifier types that allow properties to be mapped with TypeScript `readonly` and `optional`. The following table shows the modifier types and how they map between TypeScript and JSON Schema.
+TypeBox provides modifiers that allow schema properties to be statically inferred as `readonly` or `optional`. The following table shows the supported modifiers and how they map between TypeScript and JSON Schema.
 
 ```typescript
 ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
@@ -614,7 +601,7 @@ TypeBox provides property modifier types that allow properties to be mapped with
 
 ### Options
 
-You can pass JSON Schema compliant options on the last argument of any type. Option property hints are provided for convenience.
+You can pass JSON Schema options on the last argument of any type. Option hints specific to each type are provided for convenience.
 
 ```typescript
 // String must be an email
@@ -644,7 +631,7 @@ const T = Type.Array(Type.Integer(), {               // const T = {
 
 ### Generic Types
 
-Generic types can be created with generic functions. The following creates a generic `Vector<T>` type. 
+Generic types can be created with generic functions constrained to type `TSchema`. The following creates a generic `Vector<T>` type.
 
 ```typescript
 import { Type, Static, TSchema } from '@sinclair/typebox'
@@ -661,6 +648,12 @@ const NumberVector = Vector(Type.Number())           // const NumberVector = {
                                                      //   }
                                                      // }
 
+type NumberVector = Static<typeof NumberVector>      // type NumberVector = {
+                                                     //   x: number,
+                                                     //   y: number,
+                                                     //   z: number
+                                                     // }
+
 const BooleanVector = Vector(Type.Boolean())         // const BooleanVector = {
                                                      //   type: 'object',
                                                      //   required: ['x', 'y', 'z'],
@@ -670,13 +663,34 @@ const BooleanVector = Vector(Type.Boolean())         // const BooleanVector = {
                                                      //     z: { type: 'boolean' }
                                                      //   }
                                                      // }
+
+type BooleanVector = Static<typeof BooleanVector>    // type BooleanVector = {
+                                                     //   x: boolean,
+                                                     //   y: boolean,
+                                                     //   z: boolean
+                                                     // }
+```
+
+The following creates a generic `Nullable<T>` type.
+
+```typescript
+const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])
+
+const T = Nullable(Type.String())                   // const T = {
+                                                    //   anyOf: [
+                                                    //     { type: 'string' },
+                                                    //     { type: 'null' }
+                                                    //   ]
+                                                    // }
+
+type T = Static<typeof T>                           // type T = string | null
 ```
 
 <a name='types-references'></a>
 
 ### Reference Types
 
-Reference types are supported with `Type.Ref(...)`. Use `Type.Deref(...)` to dereference a type. 
+Reference types are supported with `Type.Ref(...)`. The target type must specify a valid `$id`.
 
 ```typescript
 const T = Type.String({ $id: 'T' })                  // const T = {
@@ -687,11 +701,6 @@ const T = Type.String({ $id: 'T' })                  // const T = {
 const R = Type.Ref(T)                                // const R = {
                                                      //    $ref: 'T'
                                                      // }
-
-const U = Type.Deref(R)                              // const U = {
-                                                     //    $id: 'T',
-                                                     //    type: 'string'
-                                                     // }
 ```
 
 <a name='types-recursive'></a>
@@ -735,9 +744,9 @@ function test(node: Node) {
 
 ### Conditional Types
 
-Conditional types are supported with `Extends`, `Exclude` and `Extract`. These work the same as in TypeScript.
+Conditional types are supported with `Extends`, `Exclude` and `Extract`.
 
-#### TypeScript
+**TypeScript**
 
 ```typescript
 type T0 = string extends number ? true : false                                                 
@@ -747,7 +756,7 @@ type T1 = Extract<string | number, number>
 type T2 = Exclude<string | number, number>                                                     
 //   ^ string
 ```
-#### TypeBox
+**TypeBox**
 ```typescript
 const T0 = Type.Extends(Type.String(), Type.Number(), Type.Literal(true), Type.Literal(false)) 
 //    ^ TLiteral<false>
@@ -761,7 +770,7 @@ const T2 = Type.Exclude(Type.Union([Type.String(), Type.Number()]), Type.Number(
 
 ### Unsafe
 
-Use `Type.Unsafe(...)` to create custom schemas with user defined inference rules.
+Use `Type.Unsafe(...)` to create custom schematics with user defined inference rules.
 
 ```typescript
 const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
@@ -771,7 +780,7 @@ const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
 type T = Static<typeof T>                            // type T = string
 ```
 
-The `Type.Unsafe(...)` type allows for the expression of specific OpenAPI schema representations.
+The `Type.Unsafe(...)` type can be useful to express specific OpenAPI schema representations.
 
 ```typescript
 import { Type, Static, TSchema } from '@sinclair/typebox'
@@ -806,7 +815,7 @@ type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
 
 ### Guards
 
-TypeBox provides a `TypeGuard` module for reflection and type assertion.
+TypeBox provides a `TypeGuard` module that can be used for reflection and asserting values as types.
 
 ```typescript
 import { Type, TypeGuard } from '@sinclair/typebox'
@@ -823,7 +832,7 @@ if(TypeGuard.TString(T)) {
 
 ### Strict
 
-TypeBox schemas contain the `Kind` and `Modifier` symbol properties. These properties are used for type composition and runtime type reflection. These properties are not strictly valid JSON schema; so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict()` function that will omit these properties if necessary.
+TypeBox schemas contain the `Kind` and `Modifier` symbol properties. These properties are used for type composition and reflection. These properties are not strictly valid JSON schema; so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict()` function that will omit these properties if necessary.
 
 ```typescript
 const T = Type.Object({                              // const T = {
@@ -852,7 +861,7 @@ const U = Type.Strict(T)                             // const U = {
 
 ## Values
 
-TypeBox provides an optional utility module that can be used to perform common 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 additional import.
+TypeBox provides an optional utility module that can be used to perform common 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.
 
 ```typescript
 import { Value } from '@sinclair/typebox/value'
@@ -1222,33 +1231,37 @@ For additional comparative benchmarks, please refer to [typescript-runtime-type-
 This benchmark measures compilation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/measurement/module/compile.ts).
 
 ```typescript
-┌──────────────────┬────────────┬──────────────┬──────────────┬──────────────┐
-│     (index)      │ Iterations │     Ajv      │ TypeCompiler │ Performance  │
-├──────────────────┼────────────┼──────────────┼──────────────┼──────────────┤
-│           Number │    2000    │ '    451 ms' │ '     16 ms' │ '   28.19 x' │
-│           String │    2000    │ '    338 ms' │ '     14 ms' │ '   24.14 x' │
-│          Boolean │    2000    │ '    297 ms' │ '     13 ms' │ '   22.85 x' │
-│             Null │    2000    │ '    265 ms' │ '      8 ms' │ '   33.13 x' │
-│            RegEx │    2000    │ '    492 ms' │ '     18 ms' │ '   27.33 x' │
-│          ObjectA │    2000    │ '   2744 ms' │ '     55 ms' │ '   49.89 x' │
-│          ObjectB │    2000    │ '   3005 ms' │ '     44 ms' │ '   68.30 x' │
-│            Tuple │    2000    │ '   1283 ms' │ '     26 ms' │ '   49.35 x' │
-│            Union │    2000    │ '   1263 ms' │ '     27 ms' │ '   46.78 x' │
-│          Vector4 │    2000    │ '   1622 ms' │ '     23 ms' │ '   70.52 x' │
-│          Matrix4 │    2000    │ '    888 ms' │ '     12 ms' │ '   74.00 x' │
-│   Literal_String │    2000    │ '    344 ms' │ '     14 ms' │ '   24.57 x' │
-│   Literal_Number │    2000    │ '    389 ms' │ '      8 ms' │ '   48.63 x' │
-│  Literal_Boolean │    2000    │ '    374 ms' │ '      9 ms' │ '   41.56 x' │
-│     Array_Number │    2000    │ '    710 ms' │ '     12 ms' │ '   59.17 x' │
-│     Array_String │    2000    │ '    739 ms' │ '      9 ms' │ '   82.11 x' │
-│    Array_Boolean │    2000    │ '    732 ms' │ '      7 ms' │ '  104.57 x' │
-│    Array_ObjectA │    2000    │ '   3733 ms' │ '     42 ms' │ '   88.88 x' │
-│    Array_ObjectB │    2000    │ '   3602 ms' │ '     42 ms' │ '   85.76 x' │
-│      Array_Tuple │    2000    │ '   2204 ms' │ '     20 ms' │ '  110.20 x' │
-│      Array_Union │    2000    │ '   1533 ms' │ '     24 ms' │ '   63.88 x' │
-│    Array_Vector4 │    2000    │ '   2263 ms' │ '     21 ms' │ '  107.76 x' │
-│    Array_Matrix4 │    2000    │ '   1576 ms' │ '     14 ms' │ '  112.57 x' │
-└──────────────────┴────────────┴──────────────┴──────────────┴──────────────┘
+┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┐
+│          (index)           │ Iterations │     Ajv      │ TypeCompiler │ Performance  │
+├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┤
+│ Literal_String             │    1000    │ '    260 ms' │ '      8 ms' │ '   32.50 x' │
+│ Literal_Number             │    1000    │ '    198 ms' │ '      4 ms' │ '   49.50 x' │
+│ Literal_Boolean            │    1000    │ '    185 ms' │ '      5 ms' │ '   37.00 x' │
+│ Primitive_Number           │    1000    │ '    176 ms' │ '      9 ms' │ '   19.56 x' │
+│ Primitive_String           │    1000    │ '    161 ms' │ '      9 ms' │ '   17.89 x' │
+│ Primitive_String_Pattern   │    1000    │ '    215 ms' │ '     12 ms' │ '   17.92 x' │
+│ Primitive_Boolean          │    1000    │ '    133 ms' │ '      5 ms' │ '   26.60 x' │
+│ Primitive_Null             │    1000    │ '    143 ms' │ '      8 ms' │ '   17.88 x' │
+│ Object_Unconstrained       │    1000    │ '   1181 ms' │ '     38 ms' │ '   31.08 x' │
+│ Object_Constrained         │    1000    │ '   1168 ms' │ '     32 ms' │ '   36.50 x' │
+│ Tuple_Primitive            │    1000    │ '    557 ms' │ '     16 ms' │ '   34.81 x' │
+│ Tuple_Object               │    1000    │ '   1119 ms' │ '     17 ms' │ '   65.82 x' │
+│ Composite_Intersect        │    1000    │ '    569 ms' │ '     22 ms' │ '   25.86 x' │
+│ Composite_Union            │    1000    │ '    513 ms' │ '     23 ms' │ '   22.30 x' │
+│ Math_Vector4               │    1000    │ '    802 ms' │ '     10 ms' │ '   80.20 x' │
+│ Math_Matrix4               │    1000    │ '    395 ms' │ '     12 ms' │ '   32.92 x' │
+│ Array_Primitive_Number     │    1000    │ '    282 ms' │ '      8 ms' │ '   35.25 x' │
+│ Array_Primitive_String     │    1000    │ '    321 ms' │ '      5 ms' │ '   64.20 x' │
+│ Array_Primitive_Boolean    │    1000    │ '    364 ms' │ '      5 ms' │ '   72.80 x' │
+│ Array_Object_Unconstrained │    1000    │ '   1573 ms' │ '     18 ms' │ '   87.39 x' │
+│ Array_Object_Constrained   │    1000    │ '   1270 ms' │ '     20 ms' │ '   63.50 x' │
+│ Array_Tuple_Primitive      │    1000    │ '    973 ms' │ '     18 ms' │ '   54.06 x' │
+│ Array_Tuple_Object         │    1000    │ '   1253 ms' │ '     16 ms' │ '   78.31 x' │
+│ Array_Composite_Intersect  │    1000    │ '    927 ms' │ '     20 ms' │ '   46.35 x' │
+│ Array_Composite_Union      │    1000    │ '   1123 ms' │ '     16 ms' │ '   70.19 x' │
+│ Array_Math_Vector4         │    1000    │ '   1068 ms' │ '     10 ms' │ '  106.80 x' │
+│ Array_Math_Matrix4         │    1000    │ '    488 ms' │ '      7 ms' │ '   69.71 x' │
+└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┘
 ```
 
 <a name='benchmark-validate'></a>
@@ -1258,35 +1271,39 @@ This benchmark measures compilation performance for varying types. You can revie
 This benchmark measures validation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/measurement/module/check.ts).
 
 ```typescript
-┌──────────────────┬────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
-│     (index)      │ Iterations │  ValueCheck  │     Ajv      │ TypeCompiler │ Performance  │
-├──────────────────┼────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
-│           Number │  1000000   │ '     30 ms' │ '      7 ms' │ '      6 ms' │ '    1.17 x' │
-│           String │  1000000   │ '     23 ms' │ '     21 ms' │ '     11 ms' │ '    1.91 x' │
-│          Boolean │  1000000   │ '     22 ms' │ '     21 ms' │ '     10 ms' │ '    2.10 x' │
-│             Null │  1000000   │ '     27 ms' │ '     20 ms' │ '     10 ms' │ '    2.00 x' │
-│            RegEx │  1000000   │ '    163 ms' │ '     47 ms' │ '     38 ms' │ '    1.24 x' │
-│          ObjectA │  1000000   │ '    654 ms' │ '     41 ms' │ '     24 ms' │ '    1.71 x' │
-│          ObjectB │  1000000   │ '   1173 ms' │ '     59 ms' │ '     41 ms' │ '    1.44 x' │
-│            Tuple │  1000000   │ '    124 ms' │ '     24 ms' │ '     17 ms' │ '    1.41 x' │
-│            Union │  1000000   │ '    332 ms' │ '     26 ms' │ '     16 ms' │ '    1.63 x' │
-│        Recursive │  1000000   │ '   3129 ms' │ '    412 ms' │ '    102 ms' │ '    4.04 x' │
-│          Vector4 │  1000000   │ '    147 ms' │ '     26 ms' │ '     13 ms' │ '    2.00 x' │
-│          Matrix4 │  1000000   │ '    576 ms' │ '     41 ms' │ '     28 ms' │ '    1.46 x' │
-│   Literal_String │  1000000   │ '     51 ms' │ '     21 ms' │ '     10 ms' │ '    2.10 x' │
-│   Literal_Number │  1000000   │ '     47 ms' │ '     21 ms' │ '     11 ms' │ '    1.91 x' │
-│  Literal_Boolean │  1000000   │ '     47 ms' │ '     21 ms' │ '     10 ms' │ '    2.10 x' │
-│     Array_Number │  1000000   │ '    490 ms' │ '     33 ms' │ '     18 ms' │ '    1.83 x' │
-│     Array_String │  1000000   │ '    502 ms' │ '     31 ms' │ '     25 ms' │ '    1.24 x' │
-│    Array_Boolean │  1000000   │ '    465 ms' │ '     33 ms' │ '     27 ms' │ '    1.22 x' │
-│    Array_ObjectA │  1000000   │ '  15463 ms' │ '   2470 ms' │ '   2052 ms' │ '    1.20 x' │
-│    Array_ObjectB │  1000000   │ '  18047 ms' │ '   2497 ms' │ '   2348 ms' │ '    1.06 x' │
-│      Array_Tuple │  1000000   │ '   1958 ms' │ '     99 ms' │ '     77 ms' │ '    1.29 x' │
-│      Array_Union │  1000000   │ '   5348 ms' │ '    254 ms' │ '     89 ms' │ '    2.85 x' │
-│  Array_Recursive │  1000000   │ '  54643 ms' │ '   8870 ms' │ '   1158 ms' │ '    7.66 x' │
-│    Array_Vector4 │  1000000   │ '   2724 ms' │ '    105 ms' │ '     48 ms' │ '    2.19 x' │
-│    Array_Matrix4 │  1000000   │ '  13821 ms' │ '    437 ms' │ '    266 ms' │ '    1.64 x' │
-└──────────────────┴────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
+┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
+│          (index)           │ Iterations │  ValueCheck  │     Ajv      │ TypeCompiler │ Performance  │
+├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
+│ Literal_String             │  1000000   │ '     26 ms' │ '      6 ms' │ '      6 ms' │ '    1.00 x' │
+│ Literal_Number             │  1000000   │ '     21 ms' │ '     19 ms' │ '     11 ms' │ '    1.73 x' │
+│ Literal_Boolean            │  1000000   │ '     19 ms' │ '     18 ms' │ '     10 ms' │ '    1.80 x' │
+│ Primitive_Number           │  1000000   │ '     24 ms' │ '     19 ms' │ '     11 ms' │ '    1.73 x' │
+│ Primitive_String           │  1000000   │ '     26 ms' │ '     17 ms' │ '     10 ms' │ '    1.70 x' │
+│ Primitive_String_Pattern   │  1000000   │ '    159 ms' │ '     45 ms' │ '     37 ms' │ '    1.22 x' │
+│ Primitive_Boolean          │  1000000   │ '     23 ms' │ '     17 ms' │ '     10 ms' │ '    1.70 x' │
+│ Primitive_Null             │  1000000   │ '     23 ms' │ '     18 ms' │ '     10 ms' │ '    1.80 x' │
+│ Object_Unconstrained       │  1000000   │ '    809 ms' │ '     35 ms' │ '     30 ms' │ '    1.17 x' │
+│ Object_Constrained         │  1000000   │ '   1060 ms' │ '     56 ms' │ '     45 ms' │ '    1.24 x' │
+│ Object_Recursive           │  1000000   │ '   4965 ms' │ '    397 ms' │ '    100 ms' │ '    3.97 x' │
+│ Tuple_Primitive            │  1000000   │ '    159 ms' │ '     22 ms' │ '     16 ms' │ '    1.38 x' │
+│ Tuple_Object               │  1000000   │ '    658 ms' │ '     31 ms' │ '     27 ms' │ '    1.15 x' │
+│ Composite_Intersect        │  1000000   │ '    695 ms' │ '     26 ms' │ '     22 ms' │ '    1.18 x' │
+│ Composite_Union            │  1000000   │ '    503 ms' │ '     24 ms' │ '     19 ms' │ '    1.26 x' │
+│ Math_Vector4               │  1000000   │ '    259 ms' │ '     22 ms' │ '     14 ms' │ '    1.57 x' │
+│ Math_Matrix4               │  1000000   │ '   1007 ms' │ '     40 ms' │ '     29 ms' │ '    1.38 x' │
+│ Array_Primitive_Number     │  1000000   │ '    262 ms' │ '     23 ms' │ '     17 ms' │ '    1.35 x' │
+│ Array_Primitive_String     │  1000000   │ '    241 ms' │ '     27 ms' │ '     24 ms' │ '    1.13 x' │
+│ Array_Primitive_Boolean    │  1000000   │ '    141 ms' │ '     23 ms' │ '     20 ms' │ '    1.15 x' │
+│ Array_Object_Unconstrained │  1000000   │ '   4976 ms' │ '     70 ms' │ '     67 ms' │ '    1.04 x' │
+│ Array_Object_Constrained   │  1000000   │ '   5234 ms' │ '    143 ms' │ '    120 ms' │ '    1.19 x' │
+│ Array_Object_Recursive     │  1000000   │ '  19605 ms' │ '   1909 ms' │ '    350 ms' │ '    5.45 x' │
+│ Array_Tuple_Primitive      │  1000000   │ '    706 ms' │ '     39 ms' │ '     32 ms' │ '    1.22 x' │
+│ Array_Tuple_Object         │  1000000   │ '   2951 ms' │ '     67 ms' │ '     63 ms' │ '    1.06 x' │
+│ Array_Composite_Intersect  │  1000000   │ '   2969 ms' │ '     49 ms' │ '     44 ms' │ '    1.11 x' │
+│ Array_Composite_Union      │  1000000   │ '   2191 ms' │ '     77 ms' │ '     41 ms' │ '    1.88 x' │
+│ Array_Math_Vector4         │  1000000   │ '   1164 ms' │ '     41 ms' │ '     25 ms' │ '    1.64 x' │
+│ Array_Math_Matrix4         │  1000000   │ '   4903 ms' │ '    115 ms' │ '     99 ms' │ '    1.16 x' │
+└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
 ```
 
 <a name='benchmark-compression'></a>
@@ -1299,15 +1316,11 @@ The following table lists esbuild compiled and minified sizes for each TypeBox m
 ┌──────────────────────┬────────────┬────────────┬─────────────┐
 │       (index)        │  Compiled  │  Minified  │ Compression │
 ├──────────────────────┼────────────┼────────────┼─────────────┤
-│ typebox/compiler     │ ' 65.4 kb' │ ' 32.2 kb' │  '2.03 x'   │
-│ typebox/conditional  │ ' 45.5 kb' │ ' 18.6 kb' │  '2.45 x'   │
-│ typebox/custom       │ '  0.6 kb' │ '  0.2 kb' │  '2.61 x'   │
-│ typebox/format       │ '  0.6 kb' │ '  0.2 kb' │  '2.66 x'   │
-│ typebox/guard        │ ' 23.8 kb' │ ' 11.4 kb' │  '2.08 x'   │
-│ typebox/hash         │ '  4.2 kb' │ '  1.8 kb' │  '2.30 x'   │
-│ typebox/system       │ ' 14.0 kb' │ '  7.1 kb' │  '1.96 x'   │
-│ typebox/value        │ ' 90.0 kb' │ ' 41.8 kb' │  '2.15 x'   │
-│ typebox              │ ' 12.0 kb' │ '  6.4 kb' │  '1.89 x'   │
+│ typebox/compiler     │ '108.8 kb' │ ' 48.9 kb' │  '2.23 x'   │
+│ typebox/errors       │ ' 93.2 kb' │ ' 41.5 kb' │  '2.24 x'   │
+│ typebox/system       │ ' 60.0 kb' │ ' 24.6 kb' │  '2.43 x'   │
+│ typebox/value        │ '153.5 kb' │ ' 66.7 kb' │  '2.30 x'   │
+│ typebox              │ ' 58.7 kb' │ ' 24.1 kb' │  '2.43 x'   │
 └──────────────────────┴────────────┴────────────┴─────────────┘
 ```
 

package/system/system.d.ts

@@ -17,4 +17,8 @@ export declare namespace TypeSystem {
     function Type<Type, Options = object>(kind: string, check: (options: Options, value: unknown) => boolean): (options?: Partial<Options>) => Types.TUnsafe<Type>;
     /** Creates a new string format */
     function Format<F extends string>(format: F, check: (value: string) => boolean): F;
+    /** @deprecated Use `TypeSystem.Type()` instead. */
+    function CreateType<Type, Options = object>(kind: string, check: (options: Options, value: unknown) => boolean): (options?: Partial<Options>) => Types.TUnsafe<Type>;
+    /** @deprecated Use `TypeSystem.Format()` instead.  */
+    function CreateFormat<F extends string>(format: F, check: (value: string) => boolean): F;
 }

package/system/system.js

@@ -31,13 +31,13 @@ exports.TypeSystem = exports.TypeSystemDuplicateFormat = exports.TypeSystemDupli
 const Types = require("../typebox");
 class TypeSystemDuplicateTypeKind extends Error {
     constructor(kind) {
-        super(`Duplicate kind '${kind}' detected`);
+        super(`Duplicate type kind '${kind}' detected`);
     }
 }
 exports.TypeSystemDuplicateTypeKind = TypeSystemDuplicateTypeKind;
 class TypeSystemDuplicateFormat extends Error {
     constructor(kind) {
-        super(`Duplicate format '${kind}' detected`);
+        super(`Duplicate string format '${kind}' detected`);
     }
 }
 exports.TypeSystemDuplicateFormat = TypeSystemDuplicateFormat;
@@ -66,4 +66,17 @@ var TypeSystem;
         return format;
     }
     TypeSystem.Format = Format;
+    // ------------------------------------------------------------------------
+    // Deprecated
+    // ------------------------------------------------------------------------
+    /** @deprecated Use `TypeSystem.Type()` instead. */
+    function CreateType(kind, check) {
+        return Type(kind, check);
+    }
+    TypeSystem.CreateType = CreateType;
+    /** @deprecated Use `TypeSystem.Format()` instead.  */
+    function CreateFormat(format, check) {
+        return Format(format, check);
+    }
+    TypeSystem.CreateFormat = CreateFormat;
 })(TypeSystem = exports.TypeSystem || (exports.TypeSystem = {}));

package/typebox.d.ts

@@ -1,4 +1,3 @@
-export declare const Recursive: unique symbol;
 export declare const Modifier: unique symbol;
 export declare const Hint: unique symbol;
 export declare const Kind: unique symbol;
@@ -27,7 +26,7 @@ export type TReadonlyOptional<T extends TSchema> = T & {
 export interface SchemaOptions {
     $schema?: string;
     /** Id for this schema */
-    readonly $id?: string;
+    $id?: string;
     /** Title of this schema */
     title?: string;
     /** Description of this schema */
@@ -43,7 +42,6 @@ export interface TKind {
 }
 export interface TSchema extends SchemaOptions, TKind {
     [Modifier]?: string;
-    [Recursive]?: string;
     [Hint]?: string;
     params: unknown[];
     static: unknown;
@@ -84,16 +82,17 @@ export interface TBoolean extends TSchema {
     type: 'boolean';
 }
 export type TConstructorParameters<T extends TConstructor<TSchema[], TSchema>> = TTuple<T['parameters']>;
-export type TDeref<T> = T extends TRef<infer U> ? TDeref<U> : T;
 export type TInstanceType<T extends TConstructor<TSchema[], TSchema>> = T['returns'];
 export type TCompositeUnion<Left extends TSchema, Right extends TSchema> = Ensure<TUnion<[Left, Right]>>;
-export type TCompositeMerge<T extends TObject, Output extends Record<any, TSchema>> = Evaluate<{
-    [Key in keyof T['properties']]: Key extends keyof Output ? TCompositeUnion<T['properties'][Key], Output[Key]> : T['properties'][Key];
-} & {
-    [Key in keyof Output]: Key extends keyof T['properties'] ? TCompositeUnion<T['properties'][Key], Output[Key]> : Output[Key];
-}>;
-export type TCompositeReduce<T extends TObject[], Output extends {}> = T extends [infer L, ...infer R] ? TCompositeReduce<[...Assert<R, TObject[]>], TCompositeMerge<Assert<L, TObject>, Output>> : T extends [] ? Output : never;
-export type TComposite<T extends TObject[]> = Ensure<TObject<TCompositeReduce<T, {}>>>;
+export type TCompositeUnionLeft<T extends TObject, Acc extends TProperties> = {
+    [K in keyof T['properties']]: K extends keyof Acc ? TCompositeUnion<T['properties'][K], Acc[K]> : T['properties'][K];
+};
+export type TCompositeUnionRight<T extends TObject, Acc extends TProperties> = {
+    [K in keyof Acc]: K extends keyof T['properties'] ? TCompositeUnion<T['properties'][K], Acc[K]> : Acc[K];
+};
+export type TCompositeUnionObject<T extends TObject, Acc extends TProperties> = Evaluate<TCompositeUnionLeft<T, Acc> & TCompositeUnionRight<T, Acc>>;
+export type TCompositeProperties<T extends TObject[], Acc extends TProperties> = T extends [...infer L, infer R] ? TCompositeProperties<Assert<L, TObject[]>, TCompositeUnionObject<Assert<R, TObject>, Acc>> : T extends [] ? Acc : never;
+export type TComposite<T extends TObject[] = TObject[]> = Ensure<TObject<TCompositeProperties<T, {}>>>;
 export type TConstructorParameterArray<T extends readonly TSchema[], P extends unknown[]> = [...{
     [K in keyof T]: Static<Assert<T[K], TSchema>, P>;
 }];
@@ -170,9 +169,9 @@ export type TKeyOfTuple<T extends TSchema> = {
 } extends infer U ? UnionToTuple<Exclude<{
     [K in keyof U]: U[K];
 }[keyof U], undefined>> : never;
-export type TKeyOf<T extends TSchema = TSchema, D = TDeref<T>> = (D extends TIntersect ? TKeyOfTuple<T> : D extends TUnion ? TKeyOfTuple<T> : D extends TObject ? TKeyOfTuple<T> : [
+export type TKeyOf<T extends TSchema = TSchema> = (T extends TIntersect ? TKeyOfTuple<T> : T extends TUnion ? TKeyOfTuple<T> : T extends TObject ? TKeyOfTuple<T> : [
 ]) extends infer R ? TUnionResult<Assert<R, TSchema[]>> : never;
-export type TLiteralValue = string | number | boolean | bigint;
+export type TLiteralValue = string | number | boolean;
 export interface TLiteral<T extends TLiteralValue = TLiteralValue> extends TSchema {
     [Kind]: 'Literal';
     static: T;
@@ -242,7 +241,7 @@ export type TOmitArray<T extends TSchema[], K extends keyof any> = Assert<{
     [K2 in keyof T]: TOmit<Assert<T[K2], TSchema>, K>;
 }, TSchema[]>;
 export type TOmitProperties<T extends TProperties, K extends keyof any> = Evaluate<Assert<Omit<T, K>, TProperties>>;
-export type TOmit<T extends TSchema, K extends keyof any, D = TDeref<T>> = D extends TIntersect<infer S> ? TIntersect<TOmitArray<S, K>> : D extends TUnion<infer S> ? TUnion<TOmitArray<S, K>> : D extends TObject<infer S> ? TObject<TOmitProperties<S, K>> : D;
+export type TOmit<T extends TSchema, K extends keyof any> = T extends TIntersect<infer S> ? TIntersect<TOmitArray<S, K>> : T extends TUnion<infer S> ? TUnion<TOmitArray<S, K>> : T extends TObject<infer S> ? TObject<TOmitProperties<S, K>> : T;
 export type TParameters<T extends TFunction> = TTuple<T['parameters']>;
 export type TPartialArray<T extends TSchema[]> = Assert<{
     [K in keyof T]: TPartial<Assert<T[K], TSchema>>;
@@ -250,14 +249,14 @@ export type TPartialArray<T extends TSchema[]> = Assert<{
 export type TPartialProperties<T extends TProperties> = Evaluate<Assert<{
     [K in keyof T]: T[K] extends TReadonlyOptional<infer U> ? TReadonlyOptional<U> : T[K] extends TReadonly<infer U> ? TReadonlyOptional<U> : T[K] extends TOptional<infer U> ? TOptional<U> : TOptional<T[K]>;
 }, TProperties>>;
-export type TPartial<T extends TSchema, D = TDeref<T>> = D extends TIntersect<infer S> ? TIntersect<TPartialArray<S>> : D extends TUnion<infer S> ? TUnion<TPartialArray<S>> : D extends TObject<infer S> ? TObject<TPartialProperties<S>> : D;
+export type TPartial<T extends TSchema> = T extends TIntersect<infer S> ? TIntersect<TPartialArray<S>> : T extends TUnion<infer S> ? TUnion<TPartialArray<S>> : T extends TObject<infer S> ? TObject<TPartialProperties<S>> : T;
 export type TPickArray<T extends TSchema[], K extends keyof any> = {
     [K2 in keyof T]: TPick<Assert<T[K2], TSchema>, K>;
 };
 export type TPickProperties<T extends TProperties, K extends keyof any> = Pick<T, Assert<Extract<K, keyof T>, keyof T>> extends infer R ? ({
     [K in keyof R]: Assert<R[K], TSchema> extends TSchema ? R[K] : never;
 }) : never;
-export type TPick<T extends TSchema, K extends keyof any, D = TDeref<T>> = D extends TIntersect<infer S> ? TIntersect<TPickArray<S, K>> : D extends TUnion<infer S> ? TUnion<TPickArray<S, K>> : D extends TObject<infer S> ? TObject<TPickProperties<S, K>> : D;
+export type TPick<T extends TSchema, K extends keyof any> = T extends TIntersect<infer S> ? TIntersect<TPickArray<S, K>> : T extends TUnion<infer S> ? TUnion<TPickArray<S, K>> : T extends TObject<infer S> ? TObject<TPickProperties<S, K>> : T;
 export type TPromiseStatic<T extends TSchema, P extends unknown[]> = Promise<Static<T, P>>;
 export interface TPromise<T extends TSchema = TSchema> extends TSchema {
     [Kind]: 'Promise';
@@ -305,7 +304,7 @@ export type TRequiredArray<T extends TSchema[]> = Assert<{
 export type TRequiredProperties<T extends TProperties> = Evaluate<Assert<{
     [K in keyof T]: T[K] extends TReadonlyOptional<infer U> ? TReadonly<U> : T[K] extends TReadonly<infer U> ? TReadonly<U> : T[K] extends TOptional<infer U> ? U : T[K];
 }, TProperties>>;
-export type TRequired<T extends TSchema, D = TDeref<T>> = D extends TIntersect<infer S> ? TIntersect<TRequiredArray<S>> : D extends TUnion<infer S> ? TUnion<TRequiredArray<S>> : D extends TObject<infer S> ? TObject<TRequiredProperties<S>> : D;
+export type TRequired<T extends TSchema> = T extends TIntersect<infer S> ? TIntersect<TRequiredArray<S>> : T extends TUnion<infer S> ? TUnion<TRequiredArray<S>> : T extends TObject<infer S> ? TObject<TRequiredProperties<S>> : T;
 export type StringFormatOption = 'date-time' | 'time' | 'date' | 'email' | 'idn-email' | 'hostname' | 'idn-hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'iri' | 'uuid' | 'iri-reference' | 'uri-template' | 'json-pointer' | 'relative-json-pointer' | 'regex';
 export interface StringOptions<Format extends string> extends SchemaOptions {
     minLength?: number;
@@ -385,12 +384,15 @@ export interface TVoid extends TSchema {
     type: 'null';
     typeOf: 'Void';
 }
-/** Creates a static type from a TypeBox type */
+/** Creates a TypeScript static type from a TypeBox type */
 export type Static<T extends TSchema, P extends unknown[] = []> = (T & {
     params: P;
 })['static'];
 export type TypeRegistryValidationFunction<TSchema> = (schema: TSchema, value: unknown) => boolean;
+/** A registry for user defined types */
 export declare namespace TypeRegistry {
+    /** Returns the entries in this registry */
+    function Entries(): Map<string, TypeRegistryValidationFunction<any>>;
     /** Clears all user defined types */
     function Clear(): void;
     /** Returns true if this registry contains this kind */
@@ -400,21 +402,11 @@ export declare namespace TypeRegistry {
     /** Gets a custom validation function for a user defined type */
     function Get(kind: string): TypeRegistryValidationFunction<any> | undefined;
 }
-export declare namespace ReferenceRegistry {
-    /** Clears the reference registry */
-    function Clear(): void;
-    /** Returns true if this registry contains this schema */
-    function Has(schema: TSchema): boolean;
-    /** Sets this schema on this registry if a $id exists */
-    function Set(schema: TSchema): void;
-    /** Dereferences the schema one level deep */
-    function DerefOne(schema: TSchema): TSchema;
-    /** Dereferences the schema recursively */
-    function Deref(schema: TSchema): TSchema;
-}
 export type FormatRegistryValidationFunction = (value: string) => boolean;
-/** Provides functions to create user defined string formats */
+/** A registry for user defined string formats */
 export declare namespace FormatRegistry {
+    /** Returns the entries in this registry */
+    function Entries(): Map<string, FormatRegistryValidationFunction>;
     /** Clears all user defined string formats */
     function Clear(): void;
     /** Returns true if the user defined string format exists */
@@ -428,6 +420,7 @@ export declare class TypeGuardUnknownTypeError extends Error {
     readonly schema: unknown;
     constructor(schema: unknown);
 }
+/** Provides functions to test if JavaScript values are TypeBox types */
 export declare namespace TypeGuard {
     /** Returns true if the given schema is TAny */
     function TAny(schema: unknown): schema is TAny;
@@ -496,8 +489,8 @@ export declare namespace TypeGuard {
     /** Returns true if the given schema is TSchema */
     function TSchema(schema: unknown): schema is TSchema;
 }
+/** Fast undefined check used for properties of type undefined */
 export declare namespace ExtendsUndefined {
-    /** Fast undefined check for properties of type undefined */
     function Check(schema: TSchema): boolean;
 }
 export declare enum TypeExtendsResult {
@@ -508,7 +501,7 @@ export declare enum TypeExtendsResult {
 export declare namespace TypeExtends {
     function Extends(left: TSchema, right: TSchema): TypeExtendsResult;
 }
-/** Specialized Clone for Types. Clones and removes non self-referential identifiers */
+/** Specialized Clone for Types */
 export declare namespace TypeClone {
     /** Clones a type. This function will omit non-self referential identifiers on the cloned type. */
     function Clone<T extends TSchema>(schema: T, options: SchemaOptions): T;
@@ -538,10 +531,8 @@ export declare class StandardTypeBuilder extends TypeBuilder {
     Array<T extends TSchema>(items: T, options?: ArrayOptions): TArray<T>;
     /** `[Standard]` Creates a Boolean type */
     Boolean(options?: SchemaOptions): TBoolean;
-    /** `[Standard]` Creates a Composite object type that will Union any overlapping properties of the given Object array */
+    /** `[Standard]` Creates a Composite object type that will union any overlapping properties of the given object array */
     Composite<T extends TObject[]>(schemas: [...T], options?: ObjectOptions): TComposite<T>;
-    /** `[Standard]` Dereferences the given TRef to its target type */
-    Deref<T extends TRef>(schema: T): TDeref<T>;
     /** `[Standard]` Creates a Enum type */
     Enum<T extends Record<string, string | number>>(item: T, options?: SchemaOptions): TEnum<T>;
     /** `[Standard]` A conditional type expression that will return the true type if the left type extends the right */