@sinclair/typebox 0.26.0-dev → 0.26.0-dev.1

package/compiler/compiler.d.ts

@@ -6,7 +6,7 @@ export declare class TypeCheck<T extends Types.TSchema> {
     private readonly checkFunc;
     private readonly code;
     constructor(schema: T, checkFunc: CheckFunction, code: string);
-    /** Returns the generated validation code used to validate this type. */
+    /** Returns the generated assertion code used to validate this type. */
     Code(): string;
     /** Returns an iterator for each error in this value. */
     Errors(value: unknown): IterableIterator<ValueError>;
@@ -26,7 +26,7 @@ export declare class TypeCompilerPreflightCheckError extends Error {
 }
 /** Compiles Types for Runtime Type Checking */
 export declare namespace TypeCompiler {
-    /** Returns the generated validation code used to validate this type. */
+    /** Returns the generated assertion code used to validate this type. */
     function Code<T extends Types.TSchema>(schema: T): string;
     /** Compiles the given type for runtime type checking. This compiler only accepts known TypeBox types non-inclusive of unsafe types. */
     function Compile<T extends Types.TSchema>(schema: T): TypeCheck<T>;

package/compiler/compiler.js

@@ -41,7 +41,7 @@ class TypeCheck {
         this.checkFunc = checkFunc;
         this.code = code;
     }
-    /** Returns the generated validation code used to validate this type. */
+    /** Returns the generated assertion code used to validate this type. */
     Code() {
         return this.code;
     }
@@ -504,7 +504,7 @@ var TypeCompiler;
         const locals = GetLocals();
         return `${locals.join('\n')}\nreturn ${check}`;
     }
-    /** Returns the generated validation code used to validate this type. */
+    /** Returns the generated assertion code used to validate this type. */
     function Code(schema) {
         if (!Types.TypeGuard.TSchema(schema))
             throw new TypeCompilerPreflightCheckError(schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.26.0-dev",
+  "version": "0.26.0-dev.1",
   "description": "JSONSchema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "typescript",

package/readme.md

@@ -777,7 +777,7 @@ const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
 type T = Static<typeof T>                            // type T = string
 ```
 
-The `Type.Unsafe(...)` type allows specific or non-standard OpenAPI schematics can be constructed.
+The `Type.Unsafe(...)` type allows for the expression of specific OpenAPI schema representations.
 
 ```typescript
 import { Type, Static, TSchema } from '@sinclair/typebox'
@@ -812,7 +812,7 @@ type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
 
 ### Guards
 
-TypeBox provides a `TypeGuard` module used for type value assertions and reflection.
+TypeBox provides a `TypeGuard` module for reflection and type assertion.
 
 ```typescript
 import { Type, TypeGuard } from '@sinclair/typebox'
@@ -1029,15 +1029,15 @@ ValuePointer.Set(A, '/z', 1)                         // const A = { x: 1, y: 1,
 
 ## TypeCheck
 
-TypeBox types targets JSON Schema draft 6 so is immediately compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for high performance compilation and value assertion.
+TypeBox types target JSON Schema draft 6 so are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for high performance compilation and value assertion.
 
-The following details using both Ajv and TypeBox's compiler infrastructure.
+The following sections detail using Ajv and TypeBox's compiler infrastructure.
 
 <a name='typecheck-ajv'></a>
 
 ## Ajv
 
-The following shows the recommended setup for Ajv with additional string formats.
+The following shows the recommended setup for Ajv.
 
 ```bash
 $ npm install ajv ajv-formats --save
@@ -1078,7 +1078,7 @@ const R = C({ x: 1, y: 2, z: 3 })                    // const R = true
 
 ### TypeCompiler
 
-The TypeBox TypeCompiler is a high performance JIT compiler that compiles TypeBox types into optimized JavaScript validation routines. The compiler is tuned both for fast compilation and value assertion. It is designed primarily for integrating into application frameworks but can also be used as a general purpose validator.
+The TypeBox TypeCompiler is a high performance JIT compiler that transforms TypeBox types into optimized JavaScript validation routines. The compiler is tuned for fast compilation as well as fast value assertion. It is designed to serve as a validation backend that can be integrated into larger applications; but can also be used as a general purpose validator.
 
 The TypeCompiler is provided as an optional import.
 
@@ -1098,7 +1098,7 @@ const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObje
 const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true
 ```
 
-Use the `Errors(...)` function to produce diagnostics for a value. The `Errors(...)` function will return an iterator that will perform an exhaustive check across the value and yield any error found. For performance, this function should only be called after failed `Check(...)`.
+Use the `Errors(...)` function to produce diagnostic errors for a value. The `Errors(...)` function will return an iterator that if enumerated; will perform an exhaustive check across the entire value and yield any error found. For performance, this function should only be called after failed `Check(...)`. Applications may also choose to yield only the first value to avoid exhaustive error generation.
 
 ```typescript
 const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
@@ -1181,7 +1181,7 @@ const R = Value.Check(T, { x: 1, y: 2 })              // const R = true
 
 ### Formats
 
-Use the `Format(...)` function to create a custom string formats. The following creates a custom string format that checks for lowercase strings.
+Use the `Format(...)` function to create a custom string format. The following creates a custom string format that checks for lowercase strings.
 
 ```typescript
 TypeSystem.Format('lowercase', value => value === value.toLowerCase()) // format should be lowercase

package/typebox.d.ts

@@ -520,6 +520,8 @@ export declare namespace KeyResolver {
 export declare class TypeBuilder {
     /** `[Utility]` Creates a schema without `static` and `params` types */
     protected Create<T>(schema: Omit<T, 'static' | 'params'>): T;
+    /** `[Utility]` Clones a schema or properties object */
+    protected Clone<T extends TSchema | TProperties>(schema: T, options?: SchemaOptions): T;
     /** `[Standard]` Omits compositing symbols from this schema */
     Strict<T extends TSchema>(schema: T): T;
 }
@@ -542,11 +544,11 @@ export declare class StandardTypeBuilder extends TypeBuilder {
     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 extends the right */
+    /** `[Standard]` A conditional type expression that will return the true type if the left type extends the right */
     Extends<L extends TSchema, R extends TSchema, T extends TSchema, U extends TSchema>(left: L, right: R, trueType: T, falseType: U, options?: SchemaOptions): TExtends<L, R, T, U>;
-    /** `[Standard]` Excludes from left any type that is not assignable to the right. */
+    /** `[Standard]` Excludes from the left type any type that is not assignable to the right */
     Exclude<L extends TSchema, R extends TSchema>(left: L, right: R, options?: SchemaOptions): TExclude<L, R>;
-    /** `[Standard]` Extracts from left any type that is assignable to the right. */
+    /** `[Standard]` Extracts from left left any type that is assignable to the right */
     Extract<L extends TSchema, R extends TSchema>(left: L, right: R, options?: SchemaOptions): TExtract<L, R>;
     /** `[Standard]` Creates an Integer type */
     Integer(options?: NumericOptions<number>): TInteger;
@@ -567,7 +569,7 @@ export declare class StandardTypeBuilder extends TypeBuilder {
     Null(options?: SchemaOptions): TNull;
     /** `[Standard]` Creates a Number type */
     Number(options?: NumericOptions<number>): TNumber;
-    /** `[Standard]` Creates a Object type */
+    /** `[Standard]` Creates an Object type */
     Object<T extends TProperties>(properties: T, options?: ObjectOptions): TObject<T>;
     /** `[Standard]` Creates a mapped type whose keys are omitted from the given type */
     Omit<T extends TSchema, K extends (keyof Static<T>)[]>(schema: T, keys: readonly [...K], options?: SchemaOptions): TOmit<T, K[number]>;
@@ -607,7 +609,7 @@ export declare class StandardTypeBuilder extends TypeBuilder {
     Unsafe<T>(options?: UnsafeOptions): TUnsafe<T>;
 }
 export declare class ExtendedTypeBuilder extends StandardTypeBuilder {
-    /** `[Extended]` Creates a BigInt */
+    /** `[Extended]` Creates a BigInt type */
     BigInt(options?: NumericOptions<bigint>): TBigInt;
     /** `[Extended]` Extracts the ConstructorParameters from the given Constructor type */
     ConstructorParameters<T extends TConstructor<any[], any>>(schema: T, options?: SchemaOptions): TConstructorParameters<T>;

package/typebox.js

@@ -85,7 +85,7 @@ var ReferenceRegistry;
     function DerefOne(schema) {
         if (TypeGuard.TRef(schema) || TypeGuard.TSelf(schema)) {
             if (!references.has(schema.$ref))
-                throw Error(`ReferenceRegistry: Cannot deref schema with $id '${schema.$ref}`);
+                throw Error(`ReferenceRegistry: Cannot deref schema with $id '${schema.$ref}'`);
             return references.get(schema.$ref);
         }
         else {
@@ -1469,6 +1469,12 @@ class TypeBuilder {
         ReferenceRegistry.Set(schema);
         return schema;
     }
+    /** `[Utility]` Clones a schema or properties object */
+    Clone(schema, options = {}) {
+        const clone = TypeClone.Clone(schema, options);
+        ReferenceRegistry.Set(clone);
+        return clone;
+    }
     /** `[Standard]` Omits compositing symbols from this schema */
     Strict(schema) {
         return JSON.parse(JSON.stringify(schema));
@@ -1484,11 +1490,11 @@ class StandardTypeBuilder extends TypeBuilder {
     // ----------------------------------------------------------------------
     /** `[Modifier]` Creates a Optional property */
     Optional(schema) {
-        return { [exports.Modifier]: 'Optional', ...TypeClone.Clone(schema, {}) };
+        return { [exports.Modifier]: 'Optional', ...this.Clone(schema, {}) };
     }
     /** `[Modifier]` Creates a ReadonlyOptional property */
     ReadonlyOptional(schema) {
-        return { [exports.Modifier]: 'ReadonlyOptional', ...TypeClone.Clone(schema, {}) };
+        return { [exports.Modifier]: 'ReadonlyOptional', ...this.Clone(schema, {}) };
     }
     /** `[Modifier]` Creates a Readonly object or property */
     Readonly(schema) {
@@ -1538,35 +1544,35 @@ class StandardTypeBuilder extends TypeBuilder {
         const anyOf = values.map((value) => (typeof value === 'string' ? { [exports.Kind]: 'Literal', type: 'string', const: value } : { [exports.Kind]: 'Literal', type: 'number', const: value }));
         return this.Create({ ...options, [exports.Kind]: 'Union', anyOf });
     }
-    /** `[Standard]` A conditional type expression that will return the true type if the left extends the right */
+    /** `[Standard]` A conditional type expression that will return the true type if the left type extends the right */
     Extends(left, right, trueType, falseType, options = {}) {
         switch (TypeExtends.Extends(ReferenceRegistry.Deref(left), ReferenceRegistry.Deref(right))) {
             case TypeExtendsResult.Union:
-                return this.Union([TypeClone.Clone(trueType, options), TypeClone.Clone(falseType, options)]);
+                return this.Union([this.Clone(trueType, options), this.Clone(falseType, options)]);
             case TypeExtendsResult.True:
-                return TypeClone.Clone(trueType, options);
+                return this.Clone(trueType, options);
             case TypeExtendsResult.False:
-                return TypeClone.Clone(falseType, options);
+                return this.Clone(falseType, options);
         }
     }
-    /** `[Standard]` Excludes from left any type that is not assignable to the right. */
+    /** `[Standard]` Excludes from the left type any type that is not assignable to the right */
     Exclude(left, right, options = {}) {
         if (TypeGuard.TUnion(left)) {
             const narrowed = left.anyOf.filter((inner) => TypeExtends.Extends(inner, right) === TypeExtendsResult.False);
-            return (narrowed.length === 1 ? TypeClone.Clone(narrowed[0], options) : this.Union(narrowed, options));
+            return (narrowed.length === 1 ? this.Clone(narrowed[0], options) : this.Union(narrowed, options));
         }
         else {
-            return (TypeExtends.Extends(left, right) !== TypeExtendsResult.False ? this.Never(options) : TypeClone.Clone(left, options));
+            return (TypeExtends.Extends(left, right) !== TypeExtendsResult.False ? this.Never(options) : this.Clone(left, options));
         }
     }
-    /** `[Standard]` Extracts from left any type that is assignable to the right. */
+    /** `[Standard]` Extracts from left left any type that is assignable to the right */
     Extract(left, right, options = {}) {
         if (TypeGuard.TUnion(left)) {
             const narrowed = left.anyOf.filter((inner) => TypeExtends.Extends(inner, right) !== TypeExtendsResult.False);
-            return (narrowed.length === 1 ? TypeClone.Clone(narrowed[0], options) : this.Union(narrowed, options));
+            return (narrowed.length === 1 ? this.Clone(narrowed[0], options) : this.Union(narrowed, options));
         }
         else {
-            return (TypeExtends.Extends(left, right) !== TypeExtendsResult.False ? TypeClone.Clone(left, options) : this.Never(options));
+            return (TypeExtends.Extends(left, right) !== TypeExtendsResult.False ? this.Clone(left, options) : this.Never(options));
         }
     }
     /** `[Standard]` Creates an Integer type */
@@ -1577,9 +1583,9 @@ class StandardTypeBuilder extends TypeBuilder {
         if (allOf.length === 0)
             return exports.Type.Never();
         if (allOf.length === 1)
-            return TypeClone.Clone(allOf[0], options);
+            return this.Clone(allOf[0], options);
         const objects = allOf.every((schema) => TypeGuard.TObject(schema));
-        const cloned = allOf.map((schema) => TypeClone.Clone(schema, {}));
+        const cloned = allOf.map((schema) => this.Clone(schema, {}));
         if (options.unevaluatedProperties === false || TypeGuard.TSchema(options.unevaluatedProperties) || objects) {
             return this.Create({ ...options, [exports.Kind]: 'Intersect', type: 'object', allOf: cloned });
         }
@@ -1618,22 +1624,22 @@ class StandardTypeBuilder extends TypeBuilder {
     Number(options = {}) {
         return this.Create({ ...options, [exports.Kind]: 'Number', type: 'number' });
     }
-    /** `[Standard]` Creates a Object type */
+    /** `[Standard]` Creates an Object type */
     Object(properties, options = {}) {
         const keys = globalThis.Object.keys(properties);
         const optional = keys.filter((key) => TypeGuard.TOptional(properties[key]) || TypeGuard.TReadonlyOptional(properties[key]));
         const required = keys.filter((name) => !optional.includes(name));
         if (required.length > 0) {
-            return this.Create({ ...options, [exports.Kind]: 'Object', type: 'object', properties: TypeClone.Clone(properties, {}), required });
+            return this.Create({ ...options, [exports.Kind]: 'Object', type: 'object', properties: this.Clone(properties, {}), required });
         }
         else {
-            return this.Create({ ...options, [exports.Kind]: 'Object', type: 'object', properties: TypeClone.Clone(properties, {}) });
+            return this.Create({ ...options, [exports.Kind]: 'Object', type: 'object', properties: this.Clone(properties, {}) });
         }
     }
     Omit(schema, unresolved, options = {}) {
         const keys = TypeGuard.TUnionLiteral(unresolved) ? unresolved.anyOf.map((schema) => schema.const) : unresolved;
         // prettier-ignore
-        return ObjectMap.Map(TypeClone.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
+        return ObjectMap.Map(this.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
             if (schema.required) {
                 schema.required = schema.required.filter((key) => !keys.includes(key));
                 if (schema.required.length === 0)
@@ -1666,7 +1672,7 @@ class StandardTypeBuilder extends TypeBuilder {
             }
         }
         // prettier-ignore
-        return ObjectMap.Map(TypeClone.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
+        return ObjectMap.Map(this.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
             delete schema.required;
             globalThis.Object.keys(schema.properties).forEach(key => Apply(schema.properties[key]));
             return schema;
@@ -1675,7 +1681,7 @@ class StandardTypeBuilder extends TypeBuilder {
     Pick(schema, unresolved, options = {}) {
         const keys = TypeGuard.TUnionLiteral(unresolved) ? unresolved.anyOf.map((schema) => schema.const) : unresolved;
         // prettier-ignore
-        return ObjectMap.Map(TypeClone.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
+        return ObjectMap.Map(this.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
             if (schema.required) {
                 schema.required = schema.required.filter((key) => keys.includes(key));
                 if (schema.required.length === 0)
@@ -1698,7 +1704,7 @@ class StandardTypeBuilder extends TypeBuilder {
         }
         if (TypeGuard.TUnion(key)) {
             if (key.anyOf.every((schema) => TypeGuard.TLiteral(schema) && (typeof schema.const === 'string' || typeof schema.const === 'number'))) {
-                const properties = key.anyOf.reduce((acc, literal) => ({ ...acc, [literal.const]: TypeClone.Clone(schema, {}) }), {});
+                const properties = key.anyOf.reduce((acc, literal) => ({ ...acc, [literal.const]: this.Clone(schema, {}) }), {});
                 return this.Object(properties, { ...options, [exports.Hint]: 'Record' });
             }
             else
@@ -1748,7 +1754,7 @@ class StandardTypeBuilder extends TypeBuilder {
             }
         }
         // prettier-ignore
-        return ObjectMap.Map(TypeClone.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
+        return ObjectMap.Map(this.Clone(ReferenceRegistry.Deref(schema), {}), (schema) => {
             schema.required = globalThis.Object.keys(schema.properties);
             globalThis.Object.keys(schema.properties).forEach(key => Apply(schema.properties[key]));
             return schema;
@@ -1771,8 +1777,8 @@ class StandardTypeBuilder extends TypeBuilder {
         if (anyOf.length === 0)
             return this.Never(options);
         if (anyOf.length === 1)
-            return TypeClone.Clone(anyOf[0], options);
-        const cloned = anyOf.map((schema) => TypeClone.Clone(schema, {}));
+            return this.Clone(anyOf[0], options);
+        const cloned = anyOf.map((schema) => this.Clone(schema, {}));
         return this.Create({ ...options, [exports.Kind]: 'Union', anyOf: cloned });
     }
     /** `[Standard]` Creates an Unknown type */
@@ -1789,7 +1795,7 @@ exports.StandardTypeBuilder = StandardTypeBuilder;
 // TypeBuilder
 // -------------------------------------------------------------------------------------
 class ExtendedTypeBuilder extends StandardTypeBuilder {
-    /** `[Extended]` Creates a BigInt */
+    /** `[Extended]` Creates a BigInt type */
     BigInt(options = {}) {
         return this.Create({ ...options, [exports.Kind]: 'BigInt', type: 'null', typeOf: 'BigInt' });
     }
@@ -1827,7 +1833,7 @@ class ExtendedTypeBuilder extends StandardTypeBuilder {
     }
     /** `[Extended]` Extracts the InstanceType from the given Constructor */
     InstanceType(schema, options = {}) {
-        return TypeClone.Clone(schema.returns, options);
+        return this.Clone(schema.returns, options);
     }
     /** `[Extended]` Extracts the Parameters from the given Function type */
     Parameters(schema, options = {}) {
@@ -1843,7 +1849,7 @@ class ExtendedTypeBuilder extends StandardTypeBuilder {
     }
     /** `[Extended]` Extracts the ReturnType from the given Function */
     ReturnType(schema, options = {}) {
-        return TypeClone.Clone(schema.returns, options);
+        return this.Clone(schema.returns, options);
     }
     /** `[Extended]` Creates a Symbol type */
     Symbol(options) {