@sinclair/typebox 0.31.28 → 0.32.0-dev-2

package/readme.md

@@ -25,16 +25,10 @@
 $ npm install @sinclair/typebox --save
 ```
 
-#### Esm + Deno
-
-```typescript
-import { Type, Static } from 'https://esm.sh/@sinclair/typebox'
-```
-
 ## Example
 
 ```typescript
-import { Type, Static } from '@sinclair/typebox'
+import { Type, type Static } from '@sinclair/typebox'
 
 const T = Type.Object({                              // const T = {
   x: Type.Number(),                                  //   type: 'object',
@@ -90,6 +84,8 @@ License MIT
   - [Clone](#values-clone)
   - [Check](#values-check)
   - [Convert](#values-convert)
+  - [Default](#values-default)
+  - [Clean](#values-clean)
   - [Cast](#values-cast)
   - [Decode](#values-decode)
   - [Encode](#values-decode)
@@ -107,8 +103,6 @@ License MIT
   - [Ajv](#typecheck-ajv)
   - [TypeCompiler](#typecheck-typecompiler)
 - [TypeSystem](#typesystem)
-  - [Types](#typesystem-types)
-  - [Formats](#typesystem-formats)
   - [Errors](#typesystem-errors)
   - [Policies](#typesystem-policies)
 - [Workbench](#workbench)
@@ -127,7 +121,7 @@ License MIT
 The following shows general usage.
 
 ```typescript
-import { Type, Static } from '@sinclair/typebox'
+import { Type, type Static } from '@sinclair/typebox'
 
 //--------------------------------------------------------------------------------------------
 //
@@ -297,6 +291,22 @@ The following table lists the supported Json types. These types are fully compat
 │                                │                             │ }                              │
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
+│ const T = Type.Const({         │ type T = {                  │ const T = {                    │
+│   x: 1,                        │   readonly x: 1,            │   type: 'object',              │
+│   y: 2,                        │   readonly y: 2             │   required: ['x', 'y'],        │
+│ } as const)                    │ }                           │   properties: {                │
+│                                │                             │     x: {                       │
+│                                │                             │       type: 'number',          │
+│                                │                             │       const: 1                 │
+│                                │                             │     },                         │
+│                                │                             │     y: {                       │
+│                                │                             │       type: 'number',          │
+│                                │                             │       const: 2                 │
+│                                │                             │     }                          │
+│                                │                             │   }                            │
+│                                │                             │ }                              │
+│                                │                             │                                │
+├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const T = Type.KeyOf(          │ type T = keyof {            │ const T = {                    │
 │   Type.Object({                │   x: number,                │   anyOf: [{                    │
 │     x: Type.Number(),          │   y: number                 │     type: 'string',            │
@@ -697,7 +707,7 @@ Object properties can be modified with Readonly and Optional. The following tabl
 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.
 
 ```typescript
-import { Type, Static, TSchema } from '@sinclair/typebox'
+import { Type, type Static, type TSchema } from '@sinclair/typebox'
 
 const Vector = <T extends TSchema>(t: T) => Type.Object({ x: t, y: t, z: t })
 
@@ -737,20 +747,65 @@ type T = Static<typeof T>                            // type T = string | null
 
 ### Reference Types
 
-Reference types are supported with Ref.
+Reference types can be created with Type.Ref. These types infer the same as the target type.
 
 ```typescript
-const T = Type.String({ $id: 'T' })                  // const T = {
-                                                     //   $id: 'T',
-                                                     //   type: 'string'
-                                                     // } 
+const Vector = Type.Object({                         // const Vector = {
+  x: Type.Number(),                                  //   type: 'object',
+  y: Type.Number(),                                  //   required: ['x', 'y', 'z'],
+}, { $id: 'Vector' })                                //   properties: {
+                                                     //     x: { type: 'number' },
+                                                     //     y: { type: 'number' }
+                                                     //   },
+                                                     //   $id: 'Vector'
+                                                     // }
 
-const R = Type.Ref<typeof T>('T')                    // const R = {
-                                                     //   $ref: 'T'
+const VectorRef = Type.Ref(Vector)                   // const VectorRef = {
+                                                     //   $ref: 'Vector'
                                                      // }
 
-type R = Static<typeof R>                            // type R = string
+type VectorRef = Static<typeof VectorRef>            // type VectorRef = {
+                                                     //    x: number,
+                                                     //    y: number
+                                                     // }
 ```
+Use Type.Deref to dereference a type. This type will recursively reconstruct interior referenced types.
+```typescript
+const Vertex = Type.Object({                         // const Vertex = {
+  position: VectorRef,                               //   type: 'object',
+  texcoord: VectorRef,                               //   required: ['position', 'texcoord'],
+})                                                   //   properties: {
+                                                     //     position: { $ref: 'Vector' },
+                                                     //     texcoord: { $ref: 'Vector' }
+                                                     //   }
+                                                     // }
+
+const VertexDeref = Type.Deref(Vertex, [Vector])     // const VertexDeref = {
+                                                     //   type: 'object',
+                                                     //   required: ['position', 'texcoord'],
+                                                     //   properties: {
+                                                     //     position: {
+                                                     //       type: 'object',
+                                                     //       required: ['x', 'y', 'z'],
+                                                     //       properties: {
+                                                     //         x: { type: 'number' },
+                                                     //         y: { type: 'number' }
+                                                     //       }
+                                                     //     },
+                                                     //     texcoord: {
+                                                     //       type: 'object',
+                                                     //       required: ['x', 'y', 'z'],
+                                                     //       properties: {
+                                                     //         x: { type: 'number' },
+                                                     //         y: { type: 'number' }
+                                                     //       }
+                                                     //     }
+                                                     //   }
+                                                     // }
+
+
+```
+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.
 
 <a name='types-recursive'></a>
 
@@ -793,88 +848,80 @@ function test(node: Node) {
 
 ### Conditional Types
 
-TypeBox supports runtime conditional types with Extends. This type will perform a structural assignability check for the first two arguments and returns one of the second two arguments based on the result. The Extends type is modelled after TypeScript conditional types. The Exclude and Extract conditional types are also supported.
+TypeBox supports runtime conditional types with Extends. This type performs a structural assignability check for the first two arguments and will infer one of the second two arguments based on the result. The Extends type is designed to match the assignability rules of TypeScript conditional types. The conditional derived types Exclude and Extract are also supported.
 
 ```typescript
-// TypeScript
-
-type T0 = string extends number ? true : false       // type T0 = false
+// Extends
 
-type T1 = Extract<(1 | 2 | 3), 1>                    // type T1 = 1
+type T = string extends number ? true : false        // type T = false
 
-type T2 = Exclude<(1 | 2 | 3), 1>                    // type T2 = 2 | 3
-
-// TypeBox
-
-const T0 = Type.Extends(                             // const T0: TLiteral<false> = {
-  Type.String(),                                     //   type: 'boolean',
-  Type.Number(),                                     //   const: false
-  Type.Literal(true),                                // }
+const T = Type.Extends(                              // const T: TLiteral<false>
+  Type.String(), 
+  Type.Number(), 
+  Type.Literal(true), 
   Type.Literal(false)
 )
 
-const T1 = Type.Extract(                             // const T1: TLiteral<1> = {
-  Type.Union([                                       //   type: 'number',
-    Type.Literal(1),                                 //   const: 1
-    Type.Literal(2),                                 // }
+// Extract
+
+type T = Extract<1 | 2 | 3, 1>                       // type T = 1
+
+const T = Type.Extract(                              // const T: TLiteral<1> 
+  Type.Union([
+    Type.Literal(1),
+    Type.Literal(2), 
     Type.Literal(3) 
   ]), 
   Type.Literal(1)
 )
 
-const T2 = Type.Exclude(                             // const T2: TUnion<[
+// Exclude
+
+type T = Exclude<1 | 2 | 3, 1>                       // type T = 2 | 3
+
+const T = Type.Exclude(                              // const T: TUnion<[
   Type.Union([                                       //   TLiteral<2>,
     Type.Literal(1),                                 //   TLiteral<3>
-    Type.Literal(2),                                 // ]> = {
-    Type.Literal(3)                                  //   anyOf: [{
-  ]),                                                //     type: 'number',
-  Type.Literal(1)                                    //     const: 2
-)                                                    //   }, {
-                                                     //     type: 'number',
-                                                     //     const: 3
-                                                     //   }]
-                                                     // }
+    Type.Literal(2),                                 // ]>
+    Type.Literal(3)
+  ]),
+  Type.Literal(1)
+)
 ```
 
 <a name='types-templateliteral'></a>
 
 ### Template Literal Types
 
-TypeBox supports template literal types with TemplateLiteral. This type can be created using a string syntax that is similar to the TypeScript template literal syntax. This type can also be constructed by passing an array of Union and Literal types in sequence. The following example shows the string syntax.
+TypeBox supports template literal types with TemplateLiteral. This type can be created using a syntax similar to the TypeScript template literal syntax. TypeBox encodes template literals as regular expression string patterns which enable the template be checked via Json Schema. It also supports regular expression parsing, enabling template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.
 
 ```typescript
 // TypeScript
 
-type T = `option${'A'|'B'|'C'}`                      // type T = 'optionA' | 'optionB' | 'optionC'
+type K = `prop${'A'|'B'|'C'}`                        // type T = 'propA' | 'propB' | 'propC'
 
-type R = Record<T, string>                           // type R = {
-                                                     //   optionA: string
-                                                     //   optionB: string
-                                                     //   optionC: string
+type R = Record<K, string>                           // type R = {
+                                                     //   propA: string
+                                                     //   propB: string
+                                                     //   propC: string
                                                      // }
 
 // TypeBox
 
-const T = Type.TemplateLiteral('option${A|B|C}')     // const T = {
-                                                     //   pattern: '^option(A|B|C)$',
-                                                     //   type: 'string'
-                                                     // }
+const K = Type.TemplateLiteral('prop${A|B|C}')       // const K: TTemplateLiteral<[
+                                                     //   TLiteral<'prop'>,
+                                                     //   TUnion<[
+                                                     //      TLiteral<'A'>,
+                                                     //      TLiteral<'B'>,
+                                                     //      TLiteral<'C'>,
+                                                     //   ]>
+                                                     // ]>
 
-const R = Type.Record(T, Type.String())              // const R = {
-                                                     //   type: 'object',
-                                                     //   required: ['optionA', 'optionB'],
-                                                     //   properties: {
-                                                     //     optionA: {
-                                                     //       type: 'string'
-                                                     //     },
-                                                     //     optionB: {
-                                                     //       type: 'string'
-                                                     //     }
-                                                     //     optionC: {
-                                                     //       type: 'string'
-                                                     //     }
-                                                     //   }
-                                                     // }
+const R = Type.Record(K, Type.String())              // const R: TObject<{
+                                                     //   hello1: TString,
+                                                     //   hello2: TString,
+                                                     //   hello3: TString,
+                                                     // }>
 ```
 
 <a name='types-indexed'></a>
@@ -884,32 +931,24 @@ const R = Type.Record(T, Type.String())              // const R = {
 TypeBox supports Indexed Access Types with Index. This type enables uniform access to interior property and array element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
 
 ```typescript
-const T = Type.Object({                              // const T = {
-  x: Type.Number(),                                  //   type: 'object',
-  y: Type.String(),                                  //   required: ['x', 'y', 'z'],
-  z: Type.Boolean()                                  //   properties: {
-})                                                   //     x: { type: 'number' },
-                                                     //     y: { type: 'string' },
-                                                     //     z: { type: 'string' }
-                                                     //   }
-                                                     // }
+const T = Type.Object({                              // const T: TObject<{
+  x: Type.Number(),                                  //   x: TNumber,
+  y: Type.String(),                                  //   y: TString,
+  z: Type.Boolean()                                  //   z: TBoolean
+})                                                   // }>
 
-const A = Type.Index(T, ['x'])                       // const A = { type: 'number' }
+const A = Type.Index(T, ['x'])                       // const A: TNumber
 
-const B = Type.Index(T, ['x', 'y'])                  // const B = {
-                                                     //   anyOf: [
-                                                     //     { type: 'number' },
-                                                     //     { type: 'string' }
-                                                     //   ]
-                                                     // }
+const B = Type.Index(T, ['x', 'y'])                  // const B: TUnion<[
+                                                     //   TNumber,
+                                                     //   TString,
+                                                     // ]>
 
-const C = Type.Index(T, Type.KeyOf(T))               // const C = {
-                                                     //   anyOf: [
-                                                     //     { type: 'number' },
-                                                     //     { type: 'string' },
-                                                     //     { type: 'boolean' }
-                                                     //   ]
-                                                     // }
+const C = Type.Index(T, Type.KeyOf(T))               // const C: TUnion<[
+                                                     //   TNumber,
+                                                     //   TString,
+                                                     //   TBoolean
+                                                     // ]>
 ```
 
 <a name='types-rest'></a>
@@ -919,28 +958,17 @@ const C = Type.Index(T, Type.KeyOf(T))               // const C = {
 TypeBox provides the Rest type to uniformly extract variadic tuples from Intersect, Union and Tuple types. This type can be useful to remap variadic types into different forms. The following uses Rest to remap a Tuple into a Union.
 
 ```typescript
-const T = Type.Tuple([                               // const T = {
-  Type.String(),                                     //   type: 'array',
-  Type.Number()                                      //   items: [ 
-])                                                   //     { type: 'string' },
-                                                     //     { type: 'number' }
-                                                     //   ],
-                                                     //   additionalItems: false,
-                                                     //   minItems: 2,
-                                                     //   maxItems: 2,
-                                                     // }
+const T = Type.Tuple([                               // const T: TTuple<[
+  Type.String(),                                     //   TString,
+  Type.Number()                                      //   TNumber
+])                                                   // ]>
 
-const R = Type.Rest(T)                               // const R = [
-                                                     //   { type: 'string' },
-                                                     //   { type: 'number' }
-                                                     // ]
+const R = Type.Rest(T)                               // const R: [TString, TNumber]
 
-const U = Type.Union(R)                              // const U = {
-                                                     //   anyOf: [
-                                                     //     { type: 'string' },
-                                                     //     { type: 'number' }
-                                                     //   ]
-                                                     // }
+const U = Type.Union(R)                              // const T: TUnion<[
+                                                     //   TString,
+                                                     //   TNumber
+                                                     // ]>
 ```
 
 <a name='types-transform'></a>
@@ -1042,12 +1070,12 @@ type S = Static<typeof T>                            // type S = 'A' | 'B' | 'C'
 ```
 <a name='types-guard'></a>
 
-### Type Guard
+### TypeGuard
 
 TypeBox can type check its own types with the TypeGuard module. This module is written for reflection and provides structural tests for every TypeBox type. Functions of this module return `is` guards which can be used with TypeScript control flow assertions to obtain schema inference. The following guards that the value A is TString.
 
 ```typescript
-import { Type, Kind, TypeGuard } from '@sinclair/typebox'
+import { Type, TypeGuard } from '@sinclair/typebox'
 
 const A: unknown = { ... }
 
@@ -1144,6 +1172,44 @@ const R1 = Value.Convert(T, { x: '3.14' })           // const R1 = { x: 3.14 }
 const R2 = Value.Convert(T, { x: 'not a number' })   // const R2 = { x: 'not a number' }
 ```
 
+<a name='values-clean'></a>
+
+### Clean
+
+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.
+
+```typescript
+const T = Type.Object({ 
+  x: Type.Number(), 
+  y: Type.Number() 
+})
+
+const X = Value.Clean(T, null)                        // const 'X = null
+
+const Y = Value.Clean(T, { x: 1 })                    // const 'Y = { x: 1 }
+
+const Z = Value.Clean(T, { x: 1, y: 2, z: 3 })        // const 'Z = { x: 1, y: 2 }
+```
+
+<a name='values-default'></a>
+
+### Default
+
+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.
+
+```typescript
+const T = Type.Object({ 
+  x: Type.Number({ default: 0 }), 
+  y: Type.Number({ default: 0 })
+})
+
+const X = Value.Default(T, null)                        // const 'X = null - non-enumerable
+
+const Y = Value.Default(T, { })                         // const 'Y = { x: 0, y: 0 }
+
+const Z = Value.Default(T, { x: 1 })                    // const 'Z = { x: 1, y: 0 }
+```
+
 <a name='values-cast'></a>
 
 ### Cast
@@ -1311,7 +1377,7 @@ The TypeBox type system can be extended with additional types and formats using
 Use the TypeRegistry to register a new type. The Kind must match the registered type name.
 
 ```typescript
-import { TypeRegistry, Kind } from '@sinclair/typebox'
+import { TypeRegistry, Symbols } from '@sinclair/typebox'
 
 TypeRegistry.Set('Foo', (schema, value) => value === 'foo')
 
@@ -1461,44 +1527,6 @@ const C = TypeCompiler.Code(Type.String())           // const C = `return functi
 
 The TypeBox TypeSystem module provides functionality to define types above and beyond the built-in Json and JavaScript type sets. They also manage TypeBox's localization options (i18n) for error message generation and can control various assertion policies used when type checking. Configurations made to the TypeSystem module are observed by the TypeCompiler, Value and Error modules.
 
-<a name='typesystem-types'></a>
-
-### Types
-
-Use the TypeSystem Type function to register a user defined type.
-
-```typescript
-import { TypeSystem } from '@sinclair/typebox/system'
-
-const StringSet = TypeSystem.Type<Set<string>>('StringSet', (options, value) => {
-  return value instanceof Set && [...value].every(value => typeof value === 'string')
-})
-
-const T = StringSet({})                              // Pass options if any
-
-const A = Value.Check(T, new Set())                  // const A = true
-const B = Value.Check(T, new Set(['hello']))         // const B = true
-const C = Value.Check(T, new Set([1]))               // const C = false
-
-```
-
-<a name='typesystem-formats'></a>
-
-### Formats
-
-Use the TypeSystem Format function to register a string format.
-
-```typescript
-import { TypeSystem } from '@sinclair/typebox/system'
-
-const F = TypeSystem.Format('foo', value => value === 'Foo')   
-
-const T = Type.String({ format: F })
-
-const A = Value.Check(T, 'foo')                      // const A = true
-const B = Value.Check(T, 'bar')                      // const B = false
-```
-
 <a name='typesystem-errors'></a>
 
 ### Errors

package/errors/index.d.ts

@@ -1 +0,0 @@
-export * from './errors';

package/system/index.d.ts

@@ -1,2 +0,0 @@
-export { ValueErrorType } from '../errors/errors';
-export * from './system';

package/system/system.d.ts

@@ -1,48 +0,0 @@
-import { ValueErrorType } from '../errors/errors';
-import * as Types from '../typebox';
-export declare class TypeSystemDuplicateTypeKind extends Types.TypeBoxError {
-    constructor(kind: string);
-}
-export declare class TypeSystemDuplicateFormat extends Types.TypeBoxError {
-    constructor(kind: string);
-}
-/** Creates user defined types and formats and provides overrides for value checking behaviours */
-export declare namespace TypeSystem {
-    /** Creates a new type */
-    function Type<Type, Options = Record<PropertyKey, unknown>>(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;
-}
-/** Manages error message providers */
-export declare namespace TypeSystemErrorFunction {
-    /** Resets the error message function to en-us */
-    function Reset(): void;
-    /** Sets the error message function used to generate error messages */
-    function Set(callback: ErrorFunction): void;
-    /** Gets the error message function */
-    function Get(): ErrorFunction;
-}
-/** Shared assertion routines used by the value and errors modules */
-export declare namespace TypeSystemPolicy {
-    /** Sets whether TypeBox should assert optional properties using the TypeScript `exactOptionalPropertyTypes` assertion policy. The default is `false` */
-    let ExactOptionalPropertyTypes: boolean;
-    /** Sets whether arrays should be treated as a kind of objects. The default is `false` */
-    let AllowArrayObject: boolean;
-    /** Sets whether `NaN` or `Infinity` should be treated as valid numeric values. The default is `false` */
-    let AllowNaN: boolean;
-    /** Sets whether `null` should validate for void types. The default is `false` */
-    let AllowNullVoid: boolean;
-    /** Asserts this value using the ExactOptionalPropertyTypes policy */
-    function IsExactOptionalProperty(value: Record<keyof any, unknown>, key: string): boolean;
-    /** Asserts this value using the AllowArrayObjects policy */
-    function IsObjectLike(value: unknown): value is Record<keyof any, unknown>;
-    /** Asserts this value as a record using the AllowArrayObjects policy */
-    function IsRecordLike(value: unknown): value is Record<keyof any, unknown>;
-    /** Asserts this value using the AllowNaN policy */
-    function IsNumberLike(value: unknown): value is number;
-    /** Asserts this value using the AllowVoidNull policy */
-    function IsVoidLike(value: unknown): value is void;
-}
-export type ErrorFunction = (schema: Types.TSchema, type: ValueErrorType) => string;
-/** Creates an error message using en-US as the default locale */
-export declare function DefaultErrorFunction(schema: Types.TSchema, errorType: ValueErrorType): string;