@sinclair/typebox 0.33.22 → 0.34.1

package/readme.md

@@ -4,7 +4,7 @@
 
 <p>Json Schema Type Builder with Static Type Resolution for TypeScript</p>
 
-<img src="https://github.com/sinclairzx81/typebox/blob/master/typebox.png?raw=true" />
+<img src="https://raw.githubusercontent.com/sinclairzx81/typebox/refs/heads/master/typebox.png" />
 
 <br />
 <br />
@@ -68,8 +68,7 @@ License MIT
   - [Options](#types-options)
   - [Properties](#types-properties)
   - [Generics](#types-generics)
-  - [References](#types-references)
-  - [Recursive](#types-recursive)
+  - [Modules](#types-modules)
   - [Template Literal](#types-template-literal)
   - [Indexed](#types-indexed)
   - [Mapped](#types-mapped)
@@ -77,6 +76,13 @@ License MIT
   - [Transform](#types-transform)
   - [Guard](#types-guard)
   - [Unsafe](#types-unsafe)
+- [Syntax](#syntax)
+  - [Parse](#syntax-parse)
+  - [Compose](#syntax-compose)
+  - [Context](#syntax-context)
+  - [Module](#syntax-module)
+  - [Static](#syntax-static)
+  - [Limits](#syntax-limits)
 - [Values](#values)
   - [Assert](#values-assert)
   - [Create](#values-create)
@@ -764,103 +770,41 @@ const T = Nullable(Type.String())                    // const T = {
 type T = Static<typeof T>                            // type T = string | null
 ```
 
-<a name='types-references'></a>
+<a name='types-modules'></a>
 
-### Reference Types
+### Module Types
 
-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.
+TypeBox Modules are containers for related types. They function as namespaces and enable internal types to reference each other via string references. Modules support both singular and mutually recursive types. They provide a mechanism to create circular types irrespective of the order in which types are defined.
 
 ```typescript
-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 VectorRef = Type.Ref(Vector)                   // const VectorRef = {
-                                                     //   $ref: 'Vector'
-                                                     // }
-
-type VectorRef = Static<typeof VectorRef>            // type VectorRef = {
-                                                     //    x: number,
-                                                     //    y: number
-                                                     // }
-```
-Use Deref to dereference a type. This function will replace any interior reference with the target type.
-```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 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.
-
-<a name='types-recursive'></a>
+// The following creates a Module of circular recursive Types.
+
+const Module = Type.Module({
+  A: Type.Object({ 
+    b: Type.Ref('B') // Ref B:
+  }),
+  B: Type.Object({
+    c: Type.Ref('C') // Ref C:
+  }),
+  C: Type.Object({
+    a: Type.Ref('A') // Ref A:
+  }),
+})
 
-### Recursive Types
+// Module Types must be imported before use.
 
-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.
+const A = Module.Import('A')                     // const A: TImport<{...}, 'A'>
 
-```typescript
-const Node = Type.Recursive(This => Type.Object({    // const Node = {
-  id: Type.String(),                                 //   $id: 'Node',
-  nodes: Type.Array(This)                            //   type: 'object',
-}), { $id: 'Node' })                                 //   properties: {
-                                                     //     id: {
-                                                     //       type: 'string'
-                                                     //     },
-                                                     //     nodes: {
-                                                     //       type: 'array',
-                                                     //       items: {
-                                                     //         $ref: 'Node'
-                                                     //       }
-                                                     //     }
-                                                     //   },
-                                                     //   required: [
-                                                     //     'id',
-                                                     //     'nodes'
-                                                     //   ]
-                                                     // }
-
-type Node = Static<typeof Node>                      // type Node = {
-                                                     //   id: string
-                                                     //   nodes: Node[]
-                                                     // }
-
-function test(node: Node) {
-  const id = node.nodes[0].nodes[0].id               // id is string
-}
+type A = Static<typeof A>                        // type A = { 
+                                                 //   b: {
+                                                 //     c: {
+                                                 //       a: {
+                                                 //         b: ...
+                                                 //       }
+                                                 //     }
+                                                 //   }
+                                                 // }
 ```
 
 <a name='types-template-literal'></a>
@@ -1077,6 +1021,195 @@ if(TypeGuard.IsString(T)) {
 }
 ```
 
+<a name='syntax'></a>
+
+## Syntax Types
+
+TypeBox provides support for Syntax Types, enabling it to parse TypeScript syntax directly into TypeBox types. Syntax Types serve as a DSL frontend for TypeBox's type builder and are useful for converting existing TypeScript type definitions into Json Schema schematics.
+
+Syntax Types are provided via optional import.
+
+```typescript
+import { Parse } from '@sinclair/typebox/syntax'
+```
+
+<a name='syntax-parse'></a>
+
+### Parse
+
+Use the Parse function to convert a TypeScript string into a TypeBox type. TypeBox will infer the appropriate TSchema type or return undefined if there is a syntax error.
+
+```typescript
+const A = Parse('string')                           // const A: TString
+
+const B = Parse('[1, 2, 3]')                        // const B: TTuple<[
+                                                    //   TLiteral<1>,
+                                                    //   TLiteral<2>,
+                                                    //   TLiteral<3>
+                                                    // ]>
+
+const C = Parse(`{ x: number, y: number }`)         // const C: TObject<{
+                                                    //   x: TNumber
+                                                    //   y: TNumber
+                                                    // }>
+```
+
+
+
+<a name='syntax-compose'></a>
+
+### Compose
+
+Syntax Types are designed to be interchangeable with standard Types.
+
+```typescript
+const T = Type.Object({                             // const T: TObject<{
+  x: Parse('number'),                               //   x: TNumber,
+  y: Parse('number'),                               //   y: TNumber,
+  z: Parse('number')                                //   z: TNumber
+})                                                  // }>
+```
+
+<a name='syntax-module'></a>
+
+### Module
+
+Syntax Types also support Module parsing. This can provide a more terse syntax for creating Module definitions, but comes with an inference performance cost. Module parsing supports interface and type alias definitions. Generics types are currently unsupported. 
+
+```typescript
+const Module = Parse(`module {
+  
+  export interface User {
+    id: string
+    name: string
+    email: string
+  }
+ 
+  export type PartialUser = (
+    Pick<User, 'id'> &
+    Partial<Omit<User, 'id'>>
+  )
+
+}`)
+
+const PartialUser = Module.Import('PartialUser')    // TImport<{...}, 'PartialUser'>
+
+type PartialUser = Static<typeof PartialUser>       // type PartialUser = {
+                                                    //   id: string,
+                                                    // } & {
+                                                    //   name?: string,
+                                                    //   email?: string,
+                                                    // }
+```
+
+<a name='syntax-context'></a>
+
+### Context
+
+The Parse function accepts an initial Context argument, allowing external types to be passed into the parser.
+
+```typescript
+const T = Type.Object({                             // could be written as: Parse(`{
+  x: Type.Number(),                                 //   x: number,
+  y: Type.Number(),                                 //   y: number,
+  z: Type.Number()                                  //   z: number
+})                                                  // }`)
+
+const A = Parse({ T }, 'Partial<T>')                // const A: TObject<{
+                                                    //   x: TOptional<TNumber>,
+                                                    //   y: TOptional<TNumber>,
+                                                    //   z: TOptional<TNumber>
+                                                    // }>
+
+const B = Parse({ T }, 'keyof T')                   // const B: TUnion<[
+                                                    //   TLiteral<'x'>,
+                                                    //   TLiteral<'y'>,
+                                                    //   TLiteral<'z'>
+                                                    // ]>
+
+const C = Parse({ T }, 'T & { w: number }')         // const C: TIntersect<[TObject<{
+                                                    //    x: TNumber;
+                                                    //    y: TNumber;
+                                                    //    z: TNumber;
+                                                    // }>, TObject<{
+                                                    //    w: TNumber;
+                                                    // }>]>
+```
+
+<a name='syntax-static'></a>
+
+### Static
+
+Syntax Types provide two Static types for inferring TypeScript syntax from strings.
+
+```typescript
+import { StaticParseAsSchema, StaticParseAsType } from '@sinclair/typebox/syntax' 
+
+// Will infer as a TSchema
+
+type S = StaticParseAsSchema<{}, '{ x: number }'>   // type S: TObject<{
+                                                    //   x: TNumber
+                                                    // }>
+
+// Will infer as a type
+
+type T = StaticParseAsType<{}, '{ x: number }'>     // type T = {
+                                                    //  x: number
+                                                    //                       
+```
+
+
+<a name='syntax-limits'></a>
+
+### Limitations
+
+Syntax Types work by having TypeBox parse TypeScript syntax within the TypeScript type system. This approach can place some strain on the TypeScript compiler and language service, potentially affecting responsiveness. While TypeBox makes a best-effort attempt to optimize for Syntax Types, users should be mindful of the following structures:
+
+```typescript
+// Excessively wide structures will result in instantiation limits exceeding
+const A = Parse(`[
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+  0, 1, 2, 3, 4, 5, 6, 7,
+]`)
+
+// Excessively nested structures will result in instantiation limits exceeding
+const B = Parse(`{
+  x: {
+    y: {
+      z: {
+        w: 1 <-- Type instantiation is excessively deep and possibly infinite.
+      } 
+    }
+  }  
+}`)
+```
+
+In cases where Syntax Types busts through TypeScript instantiation limits, TypeBox offers a fallback ParseOnly function which will Parse the types at runtime, but not infer the type. This function can also be used for parsing non-constant strings.
+
+```typescript
+import { ParseOnly } from '@sinclair/typebox/syntax'
+
+// Where A is TSchema | undefined 
+
+const A = ParseOnly(`{
+  x: {
+    y: {
+      z: {
+        w: 1
+      } 
+    }
+  }  
+}`)
+```
+
+For more information on TypeBox's parsing infrastructure, refer to the [ParseBox](https://github.com/sinclairzx81/parsebox) project.
+
 <a name='values'></a>
 
 ## Values
@@ -1760,12 +1893,12 @@ The following table lists esbuild compiled and minified sizes for each TypeBox m
 ┌──────────────────────┬────────────┬────────────┬─────────────┐
 │ (index)              │ Compiled   │ Minified   │ Compression │
 ├──────────────────────┼────────────┼────────────┼─────────────┤
-│ typebox/compiler     │ '119.8 kb' │ ' 52.6 kb' │ '2.28 x'    │
-│ typebox/errors       │ ' 74.4 kb' │ ' 33.1 kb' │ '2.25 x'    │
-│ typebox/parse        │ '115.3 kb' │ ' 48.3 kb' │ '2.39 x'    │
+│ typebox/compiler     │ '122.4 kb' │ ' 53.4 kb' │ '2.29 x'    │
+│ typebox/errors       │ ' 67.6 kb' │ ' 29.6 kb' │ '2.28 x'    │
+│ typebox/syntax       │ '132.9 kb' │ ' 54.2 kb' │ '2.45 x'    │
 │ typebox/system       │ '  7.4 kb' │ '  3.2 kb' │ '2.33 x'    │
-│ typebox/value        │ '157.2 kb' │ ' 66.1 kb' │ '2.38 x'    │
-│ typebox              │ '127.3 kb' │ ' 53.3 kb' │ '2.39 x'    │
+│ typebox/value        │ '150.1 kb' │ ' 62.2 kb' │ '2.41 x'    │
+│ typebox              │ '106.8 kb' │ ' 43.2 kb' │ '2.47 x'    │
 └──────────────────────┴────────────┴────────────┴─────────────┘
 ```
 

package/build/cjs/type/deref/deref.d.ts

@@ -1,22 +0,0 @@
-import type { TSchema } from '../schema/index';
-import type { Evaluate } from '../helpers/index';
-import type { TTuple } from '../tuple/index';
-import type { TIntersect } from '../intersect/index';
-import type { TUnion } from '../union/index';
-import type { TPromise } from '../promise/index';
-import type { TAsyncIterator } from '../async-iterator/index';
-import type { TIterator } from '../iterator/index';
-import type { TArray } from '../array/index';
-import type { TConstructor } from '../constructor/index';
-import type { TFunction } from '../function/index';
-import type { TRef } from '../ref/index';
-import type { TObject, TProperties } from '../object/index';
-export type TFromRest<T extends TSchema[], Acc extends TSchema[] = []> = (T extends [infer L extends TSchema, ...infer R extends TSchema[]] ? TFromRest<R, [...Acc, TDeref<L>]> : Acc);
-type FromProperties<T extends TProperties> = Evaluate<{
-    [K in keyof T]: TDeref<T[K]>;
-}>;
-declare function FromProperties(properties: TProperties, references: TSchema[]): never;
-export type TDeref<T extends TSchema> = T extends TConstructor<infer S extends TSchema[], infer R extends TSchema> ? TConstructor<TFromRest<S>, TDeref<R>> : T extends TFunction<infer S extends TSchema[], infer R extends TSchema> ? TFunction<TFromRest<S>, TDeref<R>> : T extends TIntersect<infer S extends TSchema[]> ? TIntersect<TFromRest<S>> : T extends TUnion<infer S extends TSchema[]> ? TUnion<TFromRest<S>> : T extends TTuple<infer S extends TSchema[]> ? TTuple<TFromRest<S>> : T extends TObject<infer S extends TProperties> ? TObject<FromProperties<S>> : T extends TArray<infer S extends TSchema> ? TArray<TDeref<S>> : T extends TPromise<infer S extends TSchema> ? TPromise<TDeref<S>> : T extends TAsyncIterator<infer S extends TSchema> ? TAsyncIterator<TDeref<S>> : T extends TIterator<infer S extends TSchema> ? TIterator<TDeref<S>> : T extends TRef<infer S extends TSchema> ? TDeref<S> : T;
-/** `[Json]` Creates a dereferenced type */
-export declare function Deref<T extends TSchema>(schema: T, references: TSchema[]): TDeref<T>;
-export {};

package/build/cjs/type/deref/deref.js

@@ -1,106 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Deref = Deref;
-const type_1 = require("../clone/type");
-const index_1 = require("../discard/index");
-const value_1 = require("../guard/value");
-// ------------------------------------------------------------------
-// TypeGuard
-// ------------------------------------------------------------------
-const kind_1 = require("../guard/kind");
-function FromRest(schema, references) {
-    return schema.map((schema) => Deref(schema, references));
-}
-// prettier-ignore
-function FromProperties(properties, references) {
-    const Acc = {};
-    for (const K of globalThis.Object.getOwnPropertyNames(properties)) {
-        Acc[K] = Deref(properties[K], references);
-    }
-    return Acc;
-}
-// prettier-ignore
-function FromConstructor(schema, references) {
-    schema.parameters = FromRest(schema.parameters, references);
-    schema.returns = Deref(schema.returns, references);
-    return schema;
-}
-// prettier-ignore
-function FromFunction(schema, references) {
-    schema.parameters = FromRest(schema.parameters, references);
-    schema.returns = Deref(schema.returns, references);
-    return schema;
-}
-// prettier-ignore
-function FromIntersect(schema, references) {
-    schema.allOf = FromRest(schema.allOf, references);
-    return schema;
-}
-// prettier-ignore
-function FromUnion(schema, references) {
-    schema.anyOf = FromRest(schema.anyOf, references);
-    return schema;
-}
-// prettier-ignore
-function FromTuple(schema, references) {
-    if ((0, value_1.IsUndefined)(schema.items))
-        return schema;
-    schema.items = FromRest(schema.items, references);
-    return schema;
-}
-// prettier-ignore
-function FromArray(schema, references) {
-    schema.items = Deref(schema.items, references);
-    return schema;
-}
-// prettier-ignore
-function FromObject(schema, references) {
-    schema.properties = FromProperties(schema.properties, references);
-    return schema;
-}
-// prettier-ignore
-function FromPromise(schema, references) {
-    schema.item = Deref(schema.item, references);
-    return schema;
-}
-// prettier-ignore
-function FromAsyncIterator(schema, references) {
-    schema.items = Deref(schema.items, references);
-    return schema;
-}
-// prettier-ignore
-function FromIterator(schema, references) {
-    schema.items = Deref(schema.items, references);
-    return schema;
-}
-// prettier-ignore
-function FromRef(schema, references) {
-    const target = references.find(remote => remote.$id === schema.$ref);
-    if (target === undefined)
-        throw Error(`Unable to dereference schema with $id ${schema.$ref}`);
-    const discard = (0, index_1.Discard)(target, ['$id']);
-    return Deref(discard, references);
-}
-// prettier-ignore
-function DerefResolve(schema, references) {
-    return ((0, kind_1.IsConstructor)(schema) ? FromConstructor(schema, references) :
-        (0, kind_1.IsFunction)(schema) ? FromFunction(schema, references) :
-            (0, kind_1.IsIntersect)(schema) ? FromIntersect(schema, references) :
-                (0, kind_1.IsUnion)(schema) ? FromUnion(schema, references) :
-                    (0, kind_1.IsTuple)(schema) ? FromTuple(schema, references) :
-                        (0, kind_1.IsArray)(schema) ? FromArray(schema, references) :
-                            (0, kind_1.IsObject)(schema) ? FromObject(schema, references) :
-                                (0, kind_1.IsPromise)(schema) ? FromPromise(schema, references) :
-                                    (0, kind_1.IsAsyncIterator)(schema) ? FromAsyncIterator(schema, references) :
-                                        (0, kind_1.IsIterator)(schema) ? FromIterator(schema, references) :
-                                            (0, kind_1.IsRef)(schema) ? FromRef(schema, references) :
-                                                schema);
-}
-// ------------------------------------------------------------------
-// TDeref
-// ------------------------------------------------------------------
-/** `[Json]` Creates a dereferenced type */
-function Deref(schema, references) {
-    return DerefResolve((0, type_1.CloneType)(schema), (0, type_1.CloneRest)(references));
-}

package/build/cjs/type/deref/index.d.ts

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

package/build/cjs/type/strict/index.d.ts

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

package/build/cjs/type/strict/strict.d.ts

@@ -1,12 +0,0 @@
-import type { TSchema } from '../schema/index';
-export type TStrict<T extends TSchema> = T;
-/**
- * @deprecated `[Json]` Omits compositing symbols from this schema. It is recommended
- * to use the JSON parse/stringify to remove compositing symbols if needed. This
- * is how Strict works internally.
- *
- * ```typescript
- * JSON.parse(JSON.stringify(Type.String()))
- * ```
- */
-export declare function Strict<T extends TSchema>(schema: T): TStrict<T>;

package/build/cjs/type/strict/strict.js

@@ -1,16 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Strict = Strict;
-/**
- * @deprecated `[Json]` Omits compositing symbols from this schema. It is recommended
- * to use the JSON parse/stringify to remove compositing symbols if needed. This
- * is how Strict works internally.
- *
- * ```typescript
- * JSON.parse(JSON.stringify(Type.String()))
- * ```
- */
-function Strict(schema) {
-    return JSON.parse(JSON.stringify(schema));
-}

package/build/esm/type/deref/deref.d.mts

@@ -1,22 +0,0 @@
-import type { TSchema } from '../schema/index.mjs';
-import type { Evaluate } from '../helpers/index.mjs';
-import type { TTuple } from '../tuple/index.mjs';
-import type { TIntersect } from '../intersect/index.mjs';
-import type { TUnion } from '../union/index.mjs';
-import type { TPromise } from '../promise/index.mjs';
-import type { TAsyncIterator } from '../async-iterator/index.mjs';
-import type { TIterator } from '../iterator/index.mjs';
-import type { TArray } from '../array/index.mjs';
-import type { TConstructor } from '../constructor/index.mjs';
-import type { TFunction } from '../function/index.mjs';
-import type { TRef } from '../ref/index.mjs';
-import type { TObject, TProperties } from '../object/index.mjs';
-export type TFromRest<T extends TSchema[], Acc extends TSchema[] = []> = (T extends [infer L extends TSchema, ...infer R extends TSchema[]] ? TFromRest<R, [...Acc, TDeref<L>]> : Acc);
-type FromProperties<T extends TProperties> = Evaluate<{
-    [K in keyof T]: TDeref<T[K]>;
-}>;
-declare function FromProperties(properties: TProperties, references: TSchema[]): never;
-export type TDeref<T extends TSchema> = T extends TConstructor<infer S extends TSchema[], infer R extends TSchema> ? TConstructor<TFromRest<S>, TDeref<R>> : T extends TFunction<infer S extends TSchema[], infer R extends TSchema> ? TFunction<TFromRest<S>, TDeref<R>> : T extends TIntersect<infer S extends TSchema[]> ? TIntersect<TFromRest<S>> : T extends TUnion<infer S extends TSchema[]> ? TUnion<TFromRest<S>> : T extends TTuple<infer S extends TSchema[]> ? TTuple<TFromRest<S>> : T extends TObject<infer S extends TProperties> ? TObject<FromProperties<S>> : T extends TArray<infer S extends TSchema> ? TArray<TDeref<S>> : T extends TPromise<infer S extends TSchema> ? TPromise<TDeref<S>> : T extends TAsyncIterator<infer S extends TSchema> ? TAsyncIterator<TDeref<S>> : T extends TIterator<infer S extends TSchema> ? TIterator<TDeref<S>> : T extends TRef<infer S extends TSchema> ? TDeref<S> : T;
-/** `[Json]` Creates a dereferenced type */
-export declare function Deref<T extends TSchema>(schema: T, references: TSchema[]): TDeref<T>;
-export {};