@sinclair/typebox 0.34.15 → 0.34.17

package/build/esm/value/check/check.mjs

@@ -42,6 +42,9 @@ function IsDefined(value) {
 function FromAny(schema, references, value) {
     return true;
 }
+function FromArgument(schema, references, value) {
+    return true;
+}
 function FromArray(schema, references, value) {
     if (!IsArray(value))
         return false;
@@ -390,6 +393,8 @@ function Visit(schema, references, value) {
     switch (schema_[Kind]) {
         case 'Any':
             return FromAny(schema_, references_, value);
+        case 'Argument':
+            return FromArgument(schema_, references_, value);
         case 'Array':
             return FromArray(schema_, references_, value);
         case 'AsyncIterator':

package/build/esm/value/create/create.mjs

@@ -34,6 +34,9 @@ function FromAny(schema, references) {
         return {};
     }
 }
+function FromArgument(schema, references) {
+    return {};
+}
 function FromArray(schema, references) {
     if (schema.uniqueItems === true && !HasPropertyKey(schema, 'default')) {
         throw new ValueCreateError(schema, 'Array with the uniqueItems constraint requires a default value');
@@ -392,6 +395,8 @@ function Visit(schema, references) {
     switch (schema_[Kind]) {
         case 'Any':
             return FromAny(schema_, references_);
+        case 'Argument':
+            return FromArgument(schema_, references_);
         case 'Array':
             return FromArray(schema_, references_);
         case 'AsyncIterator':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.34.15",
+  "version": "0.34.17",
   "description": "Json Schema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "typescript",
@@ -62,6 +62,16 @@
         "default": "./build/esm/errors/index.mjs"
       }
     },
+    "./parser": {
+      "require": {
+        "types": "./build/cjs/parser/index.d.ts",
+        "default": "./build/cjs/parser/index.js"
+      },
+      "import": {
+        "types": "./build/esm/parser/index.d.mts",
+        "default": "./build/esm/parser/index.mjs"
+      }
+    },
     "./syntax": {
       "require": {
         "types": "./build/cjs/syntax/index.d.ts",

package/parser/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../build/cjs/parser/index.js",
+  "types": "../build/cjs/parser/index.d.ts"
+}

package/readme.md

@@ -77,10 +77,6 @@ License MIT
   - [Transform](#types-transform)
   - [Guard](#types-guard)
   - [Unsafe](#types-unsafe)
-- [Syntax](#syntax)
-  - [Parse](#syntax-parse)
-  - [Static](#syntax-static)
-  - [Limits](#syntax-limits)
 - [Values](#values)
   - [Assert](#values-assert)
   - [Create](#values-create)
@@ -100,6 +96,11 @@ License MIT
   - [Errors](#values-errors)
   - [Mutate](#values-mutate)
   - [Pointer](#values-pointer)
+- [Syntax](#syntax)
+  - [Type](#syntax-type)
+  - [Options](#syntax-options)
+  - [Parameters](#syntax-parameters)
+  - [Generics](#syntax-generics)
 - [TypeRegistry](#typeregistry)
   - [Type](#typeregistry-type)
   - [Format](#typeregistry-format)
@@ -730,46 +731,42 @@ Object properties can be modified with Readonly and Optional. The following tabl
 
 ### Generic Types
 
-Generic types can be created with functions. TypeBox types extend the TSchema interface so you should constrain parameters to this type. The following creates a generic Vector type.
+Generic types can be created with generic functions
 
 ```typescript
-import { Type, type Static, type TSchema } from '@sinclair/typebox'
-
-const Vector = <T extends TSchema>(T: T) => 
-  Type.Object({                                      // type Vector<T> = {
-    x: T,                                            //   x: T,
-    y: T,                                            //   y: T,
-    z: T                                             //   z: T
-  })                                                 // }
+const Nullable = <T extends TSchema>(T: T) => {     // type Nullable<T> = T | null
+  return Type.Union([T, Type.Null())
+}
 
-const NumberVector = Vector(Type.Number())           // type NumberVector = Vector<number>
+const T = Nullable(Type.String())                  // type T = Nullable<string>
 ```
 
-Generic types are often used to create aliases for complex types. The following creates a Nullable generic type.
+Generic types can also be created with Argument types
 
 ```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
+const Vector = Type.Object({                        // type Vector<A_0, A_1, A_2> = {
+  x: Type.Argument(0),                              //   x: A_0,
+  y: Type.Argument(1),                              //   y: A_1,
+  z: Type.Argument(2),                              //   z: A_2
+})                                                  // }
+
+const T = Type.Instantiate(Vector, [                // type T = Vector<
+  Type.Boolean(),                                   //   boolean, 
+  Type.Number(),                                    //   number,
+  Type.String()                                     //   string
+])                                                  // >
 ```
 
 <a name='types-recursive'></a>
 
 ### Recursive Types
 
-Use the Recursive function to create a singular recursive type.
+Use the Recursive function to create recursive types
 
 ```typescript
-const Node = Type.Recursive(Self => Type.Object({    // const Node = {
+const Node = Type.Recursive(This => Type.Object({    // const Node = {
   id: Type.String(),                                 //   $id: 'Node',
-  nodes: Type.Array(Self)                            //   type: 'object',
+  nodes: Type.Array(This)                            //   type: 'object',
 }), { $id: 'Node' })                                 //   properties: {
                                                      //     id: {
                                                      //       type: 'string'
@@ -1044,162 +1041,6 @@ if(TypeGuard.IsString(T)) {
 }
 ```
 
-<a name='syntax'></a>
-
-## Syntax Types
-
-TypeBox has support for parsing TypeScript type annotations directly into TypeBox types. This feature supports both runtime and static parsing, with TypeBox implementing TypeScript parsers within the TypeScript type system itself. Syntax Types use the TypeBox Json Schema representations as an AST target for TypeScript types, providing a direct mapping between TypeScript syntax and Json Schema. Syntax Types are offered as a syntactical frontend to the Standard Type Builder API.
-
-This feature is available via optional import.
-
-```typescript
-import { Parse } from '@sinclair/typebox/syntax'
-```
-
-<a name='syntax-parse'></a>
-
-### Parse
-
-Use the Parse function to transform a TypeScript type annotation into a TypeBox type. This function will return the parsed TypeBox type or undefined on 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
-                                                    // }>
-```
-
-Syntax Types can compose with Standard Types created via the Type Builder API
-
-```typescript
-const T = Type.Object({                             // const T: TObject<{
-  x: Parse('number'),                               //   x: TNumber,
-  y: Parse('string'),                               //   y: TString,
-  z: Parse('boolean')                               //   z: TBoolean
-})                                                  // }>
-```
-
-Standard Types can also be passed to and referenced within Syntax Types.
-
-```typescript
-const X = Type.Number()
-const Y = Type.String()
-const Z = Type.Boolean()
-
-const T = Parse({ X, Y, Z }, `{ 
-  x: X, 
-  y: Y, 
-  z: Z 
-}`)
-```
-
-Syntax Types also support Module parsing.
-
-```typescript
-const Foo = Parse(`module Foo {
-
-  export type PartialUser = Pick<User, 'id'> & Partial<Omit<User, 'id'>>
-
-  export interface User {
-    id: string
-    name: string
-    email: string
-  }
-
-}`)
-
-const PartialUser = Foo.Import('PartialUser')       // TImport<{...}, 'PartialUser'>
-
-type PartialUser = Static<typeof PartialUser>       // type PartialUser = {
-                                                    //   id: string,
-                                                    // } & {
-                                                    //   name?: string,
-                                                    //   email?: string,
-                                                    // }
-```
-
-<a name='syntax-static'></a>
-
-### Static
-
-Syntax Types provide two Static types specific to inferring TypeBox and TypeScript types 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
-
-TypeBox parses TypeScript types directly within the TypeScript type system. This process does come with an inference cost, which scales with the size and complexity of the types being parsed. Although TypeBox strives to optimize Syntax Types, users should be aware 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.
-      } 
-    }
-  }  
-}`)
-```
-
-If Syntax Types exceed TypeScript's instantiation limits, users are advised to fall back to the Standard Type Builder API. Alternatively, TypeBox offers a `ParseOnly` function that parses the TypeScript syntax at runtime without statically inferring the schema.
-
-```typescript
-import { ParseOnly } from '@sinclair/typebox/syntax'
-
-// const A: TSchema | undefined 
-
-const A = ParseOnly(`{
-  x: {
-    y: {
-      z: {
-        w: 1
-      } 
-    }
-  }  
-}`)
-```
-
-For more information on static parsing, refer to the [ParseBox](https://github.com/sinclairzx81/parsebox) project.
-
 <a name='values'></a>
 
 ## Values
@@ -1490,6 +1331,86 @@ ValuePointer.Set(A, '/y', 1)                         // A' = { x: 1, y: 1, z: 0
 ValuePointer.Set(A, '/z', 1)                         // A' = { x: 1, y: 1, z: 1 }
 ```
 
+
+
+<a name='syntax'></a>
+
+## Syntax Types
+
+TypeBox provides optional support for runtime and type level parsing from TypeScript syntax.
+
+```typescript
+import { Syntax } from '@sinclair/typebox/syntax'
+```
+
+<a name='syntax-type'></a>
+
+### Type
+
+Use the Syntax function to create TypeBox type from TypeScript syntax.
+
+```typescript
+const T = Syntax(`{ x: number, y: number }`)        // const T: TObject<{
+                                                    //   x: TNumber
+                                                    //   y: TNumber
+                                                    // }>
+```
+
+<a name='syntax-options'></a>
+
+### Options
+
+Options can be passed to types on the last parameter
+
+```typescript
+const T = Syntax(`number`, {                      // const T = {
+  minimum: 0,                                     //   type: 'number',
+  maximum: 10                                     //   minimum: 0,
+})                                                //   maximum: 10
+                                                  // }
+```
+
+<a name="syntax-parameters"></a>
+
+### Parameters
+
+Syntax types can be parameterized to accept exterior types.
+
+```typescript
+const T = Syntax('number')
+
+const S = Syntax({ T }, `{ x: T, y: T, z: T }`)     // const S: TObject<{
+                                                    //   x: TNumber,
+                                                    //   y: TNumber,
+                                                    //   z: TNumber
+                                                    // }>
+```
+
+<a name="syntax-generics"></a>
+
+### Generics
+
+Generic types can be created by passing Argument types as parameters.
+
+```typescript
+// Generic Vector Type
+
+const Vector = Syntax({                             // type Vector<X, Y, Z> = {
+  X: Type.Argument(0),                              //   x: X
+  Y: Type.Argument(1),                              //   y: Y,
+  Z: Type.Argument(2)                               //   z: Z
+},                                                  // }
+`{                            
+  x: X,
+  y: Y,
+  z: Z
+}`)
+
+// Instanced Vector Type 
+
+const Up = Syntax({ Vector }, `Vector<0, 1, 0>`)    // type Up = Vector<0, 1, 0>
+```
+
 <a name='typeregistry'></a>
 
 ## TypeRegistry
@@ -1778,8 +1699,10 @@ The following is a list of community packages that offer general tooling, extend
 | [schema2typebox](https://github.com/xddq/schema2typebox)  | Creating TypeBox code from Json Schemas |
 | [sveltekit-superforms](https://github.com/ciscoheat/sveltekit-superforms)  | A comprehensive SvelteKit form library for server and client validation |
 | [ts2typebox](https://github.com/xddq/ts2typebox) | Creating TypeBox code from Typescript types |
+| [typebox-cli](https://github.com/gsuess/typebox-cli) | Generate Schema with typebox from the CLI |
 | [typebox-form-parser](https://github.com/jtlapp/typebox-form-parser) | Parses form and query data based on TypeBox schemas |
 
+
 <a name='benchmark'></a>
 
 ## Benchmark

package/build/cjs/syntax/parse.d.ts

@@ -1,15 +0,0 @@
-import * as Types from '../type/index';
-import { Static } from './parsebox/index';
-import { Main } from './static';
-/** `[Syntax]` Infers a TypeBox type from TypeScript syntax. */
-export type StaticParseAsSchema<Context extends Record<PropertyKey, Types.TSchema>, Code extends string> = Static.Parse<Main, Code, Context>[0];
-/** `[Syntax]` Infers a TypeScript type from TypeScript syntax. */
-export type StaticParseAsType<Context extends Record<PropertyKey, Types.TSchema>, Code extends string> = StaticParseAsSchema<Context, Code> extends infer Type extends Types.TSchema ? Types.StaticDecode<Type> : undefined;
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-export declare function Parse<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): StaticParseAsSchema<Context, Code>;
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-export declare function Parse<Code extends string>(code: Code, options?: Types.SchemaOptions): StaticParseAsSchema<{}, Code>;
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax. This function does not infer the type. */
-export declare function ParseOnly<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined;
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax */
-export declare function ParseOnly<Code extends string>(code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined;

package/build/cjs/syntax/parse.js

@@ -1,19 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Parse = Parse;
-exports.ParseOnly = ParseOnly;
-const Types = require("../type/index");
-const runtime_1 = require("./runtime");
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-function Parse(...args) {
-    return ParseOnly.apply(null, args);
-}
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax. This function does not infer the type. */
-function ParseOnly(...args) {
-    const withContext = typeof args[0] === 'string' ? false : true;
-    const [context, code, options] = withContext ? [args[0], args[1], args[2] || {}] : [{}, args[0], args[1] || {}];
-    const type = runtime_1.Module.Parse('Main', code, context)[0];
-    // Note: Parsing may return either a ModuleInstance or Type. We only apply options on the Type.
-    return Types.KindGuard.IsSchema(type) ? Types.CloneType(type, options) : type;
-}

package/build/esm/syntax/parse.d.mts

@@ -1,15 +0,0 @@
-import * as Types from '../type/index.mjs';
-import { Static } from './parsebox/index.mjs';
-import { Main } from './static.mjs';
-/** `[Syntax]` Infers a TypeBox type from TypeScript syntax. */
-export type StaticParseAsSchema<Context extends Record<PropertyKey, Types.TSchema>, Code extends string> = Static.Parse<Main, Code, Context>[0];
-/** `[Syntax]` Infers a TypeScript type from TypeScript syntax. */
-export type StaticParseAsType<Context extends Record<PropertyKey, Types.TSchema>, Code extends string> = StaticParseAsSchema<Context, Code> extends infer Type extends Types.TSchema ? Types.StaticDecode<Type> : undefined;
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-export declare function Parse<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): StaticParseAsSchema<Context, Code>;
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-export declare function Parse<Code extends string>(code: Code, options?: Types.SchemaOptions): StaticParseAsSchema<{}, Code>;
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax. This function does not infer the type. */
-export declare function ParseOnly<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined;
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax */
-export declare function ParseOnly<Code extends string>(code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined;

package/build/esm/syntax/parse.mjs

@@ -1,14 +0,0 @@
-import * as Types from '../type/index.mjs';
-import { Module } from './runtime.mjs';
-/** `[Syntax]` Parses a TypeBox type from TypeScript syntax. */
-export function Parse(...args) {
-    return ParseOnly.apply(null, args);
-}
-/** `[Syntax]` Parses a TypeBox TSchema from TypeScript syntax. This function does not infer the type. */
-export function ParseOnly(...args) {
-    const withContext = typeof args[0] === 'string' ? false : true;
-    const [context, code, options] = withContext ? [args[0], args[1], args[2] || {}] : [{}, args[0], args[1] || {}];
-    const type = Module.Parse('Main', code, context)[0];
-    // Note: Parsing may return either a ModuleInstance or Type. We only apply options on the Type.
-    return Types.KindGuard.IsSchema(type) ? Types.CloneType(type, options) : type;
-}