@sinclair/typebox 0.24.7 → 0.24.8

package/compiler/compiler.d.ts

@@ -1,4 +1,4 @@
-import { TypeError } from './errors';
+import { ValueError } from '../value/errors';
 import * as Types from '../typebox';
 export declare type CheckFunction = (value: unknown) => boolean;
 export declare class TypeCheck<T extends Types.TSchema> {
@@ -7,14 +7,14 @@ export declare class TypeCheck<T extends Types.TSchema> {
     private readonly checkFunc;
     private readonly code;
     constructor(schema: T, additional: Types.TSchema[], checkFunc: CheckFunction, code: string);
-    /** Returns the generated validation code used to validate this type */
+    /** Returns the generated validation code used to validate this type. */
     Code(): string;
-    /** Returns an iterator for each type error found in this value */
-    Errors(value: unknown): Generator<TypeError>;
+    /** Returns an iterator for each error in this value. */
+    Errors(value: unknown): IterableIterator<ValueError>;
     /** Returns true if the value matches the given type. */
     Check(value: unknown): value is Types.Static<T>;
 }
 export declare namespace TypeCompiler {
     /** 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, additional?: Types.TSchema[]): TypeCheck<T>;
+    function Compile<T extends Types.TSchema>(schema: T, references?: Types.TSchema[]): TypeCheck<T>;
 }

package/compiler/compiler.js

@@ -28,7 +28,7 @@ THE SOFTWARE.
 ---------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypeCompiler = exports.TypeCheck = void 0;
-const errors_1 = require("./errors");
+const errors_1 = require("../value/errors");
 const Types = require("../typebox");
 // -------------------------------------------------------------------
 // TypeCheck
@@ -44,13 +44,13 @@ class TypeCheck {
         this.checkFunc = checkFunc;
         this.code = code;
     }
-    /** Returns the generated validation code used to validate this type */
+    /** Returns the generated validation code used to validate this type. */
     Code() {
         return this.code;
     }
-    /** Returns an iterator for each type error found in this value */
+    /** Returns an iterator for each error in this value. */
     Errors(value) {
-        return errors_1.TypeErrors.Errors(this.schema, this.additional, value);
+        return errors_1.ValueErrors.Errors(this.schema, this.additional, value);
     }
     /** Returns true if the value matches the given type. */
     Check(value) {
@@ -66,65 +66,65 @@ var TypeCompiler;
     // -------------------------------------------------------------------
     // Schemas
     // -------------------------------------------------------------------
-    function* Any(schema, path) {
+    function* Any(schema, value) {
         yield '(true)';
     }
-    function* Array(schema, path) {
+    function* Array(schema, value) {
         const expr = [...Visit(schema.items, `value`)].map((condition) => condition).join(' && ');
-        yield `(Array.isArray(${path}) && ${path}.every(value => ${expr}))`;
+        yield `(Array.isArray(${value}) && ${value}.every(value => ${expr}))`;
     }
-    function* Boolean(schema, path) {
-        yield `(typeof ${path} === 'boolean')`;
+    function* Boolean(schema, value) {
+        yield `(typeof ${value} === 'boolean')`;
     }
-    function* Constructor(schema, path) {
-        yield* Visit(schema.yields, path);
+    function* Constructor(schema, value) {
+        yield* Visit(schema.returns, value);
     }
-    function* Function(schema, path) {
-        yield `(typeof ${path} === 'function')`;
+    function* Function(schema, value) {
+        yield `(typeof ${value} === 'function')`;
     }
-    function* Integer(schema, path) {
-        yield `(typeof ${path} === 'number' && Number.isInteger(${path}))`;
+    function* Integer(schema, value) {
+        yield `(typeof ${value} === 'number' && Number.isInteger(${value}))`;
         if (schema.multipleOf)
-            yield `(${path} % ${schema.multipleOf} === 0)`;
+            yield `(${value} % ${schema.multipleOf} === 0)`;
         if (schema.exclusiveMinimum)
-            yield `(${path} > ${schema.exclusiveMinimum})`;
+            yield `(${value} > ${schema.exclusiveMinimum})`;
         if (schema.exclusiveMaximum)
-            yield `(${path} < ${schema.exclusiveMaximum})`;
+            yield `(${value} < ${schema.exclusiveMaximum})`;
         if (schema.minimum)
-            yield `(${path} >= ${schema.minimum})`;
+            yield `(${value} >= ${schema.minimum})`;
         if (schema.maximum)
-            yield `(${path} <= ${schema.maximum})`;
+            yield `(${value} <= ${schema.maximum})`;
     }
-    function* Literal(schema, path) {
+    function* Literal(schema, value) {
         if (typeof schema.const === 'string') {
-            yield `(${path} === '${schema.const}')`;
+            yield `(${value} === '${schema.const}')`;
         }
         else {
-            yield `(${path} === ${schema.const})`;
+            yield `(${value} === ${schema.const})`;
         }
     }
-    function* Null(schema, path) {
-        yield `(${path} === null)`;
+    function* Null(schema, value) {
+        yield `(${value} === null)`;
     }
-    function* Number(schema, path) {
-        yield `(typeof ${path} === 'number')`;
+    function* Number(schema, value) {
+        yield `(typeof ${value} === 'number')`;
         if (schema.multipleOf)
-            yield `(${path} % ${schema.multipleOf} === 0)`;
+            yield `(${value} % ${schema.multipleOf} === 0)`;
         if (schema.exclusiveMinimum)
-            yield `(${path} > ${schema.exclusiveMinimum})`;
+            yield `(${value} > ${schema.exclusiveMinimum})`;
         if (schema.exclusiveMaximum)
-            yield `(${path} < ${schema.exclusiveMaximum})`;
+            yield `(${value} < ${schema.exclusiveMaximum})`;
         if (schema.minimum)
-            yield `(${path} >= ${schema.minimum})`;
+            yield `(${value} >= ${schema.minimum})`;
         if (schema.maximum)
-            yield `(${path} <= ${schema.maximum})`;
+            yield `(${value} <= ${schema.maximum})`;
     }
-    function* Object(schema, path) {
-        yield `(typeof ${path} === 'object' && ${path} !== null && !Array.isArray(${path}))`;
+    function* Object(schema, value) {
+        yield `(typeof ${value} === 'object' && ${value} !== null && !Array.isArray(${value}))`;
         if (schema.minProperties !== undefined)
-            yield `(Object.keys(${path}).length >= ${schema.minProperties})`;
+            yield `(Object.keys(${value}).length >= ${schema.minProperties})`;
         if (schema.maxProperties !== undefined)
-            yield `(Object.keys(${path}).length <= ${schema.maxProperties})`;
+            yield `(Object.keys(${value}).length <= ${schema.maxProperties})`;
         const propertyKeys = globalThis.Object.keys(schema.properties);
         if (schema.additionalProperties === false) {
             // optimization: If the property key length matches the required keys length
@@ -132,36 +132,36 @@ var TypeCompiler;
             // of the property key length. This is because exhaustive testing for values
             // will occur in subsequent property tests.
             if (schema.required && schema.required.length === propertyKeys.length) {
-                yield `(Object.keys(${path}).length === ${propertyKeys.length})`;
+                yield `(Object.keys(${value}).length === ${propertyKeys.length})`;
             }
             else {
                 const keys = `[${propertyKeys.map((key) => `'${key}'`).join(', ')}]`;
-                yield `(Object.keys(${path}).every(key => ${keys}.includes(key)))`;
+                yield `(Object.keys(${value}).every(key => ${keys}.includes(key)))`;
             }
         }
         for (const propertyKey of propertyKeys) {
             const propertySchema = schema.properties[propertyKey];
             if (schema.required && schema.required.includes(propertyKey)) {
-                yield* Visit(propertySchema, `${path}.${propertyKey}`);
+                yield* Visit(propertySchema, `${value}.${propertyKey}`);
             }
             else {
-                const expr = [...Visit(propertySchema, `${path}.${propertyKey}`)].map((condition) => condition).join(' && ');
-                yield `(${path}.${propertyKey} === undefined ? true : (${expr}))`;
+                const expr = [...Visit(propertySchema, `${value}.${propertyKey}`)].map((condition) => condition).join(' && ');
+                yield `(${value}.${propertyKey} === undefined ? true : (${expr}))`;
             }
         }
     }
-    function* Promise(schema, path) {
-        yield `(typeof value === 'object' && typeof ${path}.then === 'function')`;
+    function* Promise(schema, value) {
+        yield `(typeof value === 'object' && typeof ${value}.then === 'function')`;
     }
-    function* Record(schema, path) {
-        yield `(typeof ${path} === 'object' && ${path} !== null && !Array.isArray(${path}))`;
+    function* Record(schema, value) {
+        yield `(typeof ${value} === 'object' && ${value} !== null && !Array.isArray(${value}))`;
         const [keyPattern, valueSchema] = globalThis.Object.entries(schema.patternProperties)[0];
         const local = PushLocal(`const local = new RegExp(/${keyPattern}/)`);
-        yield `(Object.keys(${path}).every(key => ${local}.test(key)))`;
+        yield `(Object.keys(${value}).every(key => ${local}.test(key)))`;
         const expr = [...Visit(valueSchema, 'value')].map((condition) => condition).join(' && ');
-        yield `(Object.values(${path}).every(value => ${expr}))`;
+        yield `(Object.values(${value}).every(value => ${expr}))`;
     }
-    function* Ref(schema, path) {
+    function* Ref(schema, value) {
         // reference: referenced schemas can originate from either additional
         // schemas or inline in the schema itself. Ideally the recursive
         // path should align to reference path. Consider for review.
@@ -174,50 +174,50 @@ var TypeCompiler;
             PushLocal(body);
         }
         const func = CreateFunctionName(schema.$ref);
-        yield `(${func}(${path}))`;
+        yield `(${func}(${value}))`;
     }
-    function* Self(schema, path) {
+    function* Self(schema, value) {
         const func = CreateFunctionName(schema.$ref);
-        yield `(${func}(${path}))`;
+        yield `(${func}(${value}))`;
     }
-    function* String(schema, path) {
-        yield `(typeof ${path} === 'string')`;
+    function* String(schema, value) {
+        yield `(typeof ${value} === 'string')`;
         if (schema.pattern !== undefined) {
             const local = PushLocal(`const local = new RegExp('${schema.pattern}');`);
-            yield `(${local}.test(${path}))`;
+            yield `(${local}.test(${value}))`;
         }
     }
-    function* Tuple(schema, path) {
-        yield `(Array.isArray(${path}))`;
+    function* Tuple(schema, value) {
+        yield `(Array.isArray(${value}))`;
         if (schema.items === undefined)
-            return yield `(${path}.length === 0)`;
-        yield `(${path}.length === ${schema.maxItems})`;
+            return yield `(${value}.length === 0)`;
+        yield `(${value}.length === ${schema.maxItems})`;
         for (let i = 0; i < schema.items.length; i++) {
-            const expr = [...Visit(schema.items[i], `${path}[${i}]`)].map((condition) => condition).join(' && ');
+            const expr = [...Visit(schema.items[i], `${value}[${i}]`)].map((condition) => condition).join(' && ');
             yield `(${expr})`;
         }
     }
-    function* Undefined(schema, path) {
-        yield `${path} === undefined`;
+    function* Undefined(schema, value) {
+        yield `(${value} === undefined)`;
     }
-    function* Union(schema, path) {
-        const exprs = schema.anyOf.map((schema) => [...Visit(schema, path)].map((condition) => condition).join(' && '));
+    function* Union(schema, value) {
+        const exprs = schema.anyOf.map((schema) => [...Visit(schema, value)].map((condition) => condition).join(' && '));
         yield `(${exprs.join(' || ')})`;
     }
-    function* Uint8Array(schema, path) {
-        yield `(${path} instanceof Uint8Array)`;
+    function* Uint8Array(schema, value) {
+        yield `(${value} instanceof Uint8Array)`;
         if (schema.maxByteLength)
-            yield `(${path}.length <= ${schema.maxByteLength})`;
+            yield `(${value}.length <= ${schema.maxByteLength})`;
         if (schema.minByteLength)
-            yield `(${path}.length >= ${schema.minByteLength})`;
+            yield `(${value}.length >= ${schema.minByteLength})`;
     }
-    function* Unknown(schema, path) {
+    function* Unknown(schema, value) {
         yield '(true)';
     }
-    function* Void(schema, path) {
-        yield `(${path} === null)`;
+    function* Void(schema, value) {
+        yield `(${value} === null)`;
     }
-    function* Visit(schema, path) {
+    function* Visit(schema, value) {
         // reference: referenced schemas can originate from either additional
         // schemas or inline in the schema itself. Ideally the recursive
         // path should align to reference path. Consider for review.
@@ -227,53 +227,53 @@ var TypeCompiler;
             const name = CreateFunctionName(schema.$id);
             const body = CreateFunction(name, conditions);
             PushLocal(body);
-            yield `(${name}(${path}))`;
+            yield `(${name}(${value}))`;
             return;
         }
         const anySchema = schema;
         switch (anySchema[Types.Kind]) {
             case 'Any':
-                return yield* Any(anySchema, path);
+                return yield* Any(anySchema, value);
             case 'Array':
-                return yield* Array(anySchema, path);
+                return yield* Array(anySchema, value);
             case 'Boolean':
-                return yield* Boolean(anySchema, path);
+                return yield* Boolean(anySchema, value);
             case 'Constructor':
-                return yield* Constructor(anySchema, path);
+                return yield* Constructor(anySchema, value);
             case 'Function':
-                return yield* Function(anySchema, path);
+                return yield* Function(anySchema, value);
             case 'Integer':
-                return yield* Integer(anySchema, path);
+                return yield* Integer(anySchema, value);
             case 'Literal':
-                return yield* Literal(anySchema, path);
+                return yield* Literal(anySchema, value);
             case 'Null':
-                return yield* Null(anySchema, path);
+                return yield* Null(anySchema, value);
             case 'Number':
-                return yield* Number(anySchema, path);
+                return yield* Number(anySchema, value);
             case 'Object':
-                return yield* Object(anySchema, path);
+                return yield* Object(anySchema, value);
             case 'Promise':
-                return yield* Promise(anySchema, path);
+                return yield* Promise(anySchema, value);
             case 'Record':
-                return yield* Record(anySchema, path);
+                return yield* Record(anySchema, value);
             case 'Ref':
-                return yield* Ref(anySchema, path);
+                return yield* Ref(anySchema, value);
             case 'Self':
-                return yield* Self(anySchema, path);
+                return yield* Self(anySchema, value);
             case 'String':
-                return yield* String(anySchema, path);
+                return yield* String(anySchema, value);
             case 'Tuple':
-                return yield* Tuple(anySchema, path);
+                return yield* Tuple(anySchema, value);
             case 'Undefined':
-                return yield* Undefined(anySchema, path);
+                return yield* Undefined(anySchema, value);
             case 'Union':
-                return yield* Union(anySchema, path);
+                return yield* Union(anySchema, value);
             case 'Uint8Array':
-                return yield* Uint8Array(anySchema, path);
+                return yield* Uint8Array(anySchema, value);
             case 'Unknown':
-                return yield* Unknown(anySchema, path);
+                return yield* Unknown(anySchema, value);
             case 'Void':
-                return yield* Void(anySchema, path);
+                return yield* Void(anySchema, value);
             default:
                 throw Error(`Unknown schema kind '${schema[Types.Kind]}'`);
         }
@@ -319,18 +319,18 @@ var TypeCompiler;
     // -------------------------------------------------------------------
     // Compile
     // -------------------------------------------------------------------
-    function Build(schema, additional = []) {
+    function Build(schema, references = []) {
         ClearLocals();
-        PushReferences(additional);
+        PushReferences(references);
         const conditions = [...Visit(schema, 'value')]; // locals populated during yield
         const locals = GetLocals();
         return `${locals.join('\n')}\nreturn ${CreateFunction('check', conditions)}`;
     }
     /** Compiles the given type for runtime type checking. This compiler only accepts known TypeBox types non-inclusive of unsafe types. */
-    function Compile(schema, additional = []) {
-        const code = Build(schema, additional);
+    function Compile(schema, references = []) {
+        const code = Build(schema, references);
         const func = globalThis.Function(code);
-        return new TypeCheck(schema, additional, func(), code);
+        return new TypeCheck(schema, references, func(), code);
     }
     TypeCompiler.Compile = Compile;
 })(TypeCompiler = exports.TypeCompiler || (exports.TypeCompiler = {}));

package/compiler/index.d.ts

@@ -1,2 +1,2 @@
 export * from './compiler';
-export * from './errors';
+export * from '../value/errors';

package/compiler/index.js

@@ -38,4 +38,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./compiler"), exports);
-__exportStar(require("./errors"), exports);
+__exportStar(require("../value/errors"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.24.7",
+  "version": "0.24.8",
   "description": "JSONSchema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "json-schema",

package/readme.md

@@ -450,7 +450,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const T = Type.Undefined()     │ type T = undefined          │ const T = {                    │
-│                                │                             │   type: 'object'               │
+│                                │                             │   type: 'object',              │
 │                                │                             │   specialized: 'Undefined'     │
 │                                │                             │ }                              │
 │                                │                             │                                │
@@ -607,36 +607,51 @@ type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
 
 ### Values
 
-TypeBox can construct default values for types. TypeBox will create reasonable defaults for any given type, or produce values based on the schemas the `default` value if specified.
+TypeBox can create values from types. It creates reasonable defaults for each value which can overrided by specifying a `default` value.
 
 ```typescript
 import { Value } from '@sinclair/typebox/value'
-import { Type }  from '@sinclair/typebox'
+import { Type } from '@sinclair/typebox'
 
 const T = Type.Object({
   x: Type.Number({ default: 1 }),
-  y: Type.Number({ default: 2 }),
-  z: Type.Number()
+  y: Type.Number(),
 })
 
 const V = Value.Create(T)                            // const V = {
                                                      //   x: 1,
-                                                     //   y: 2,
-                                                     //   z: 0
+                                                     //   y: 0,
                                                      // }
 ```
+TypeBox also allows values to be upgraded to match the schematics of a given type. The `Value.Cast(...)` function can be used to upgrade a value into a target type while retaining as much information of the original value as possible. Casts are immutable operations.
+
+```typescript
+import { Value } from '@sinclair/typebox/value'
+import { Type } from '@sinclair/typebox'
+
+const T = Type.Object({
+  x: Type.Number(),
+  y: Type.Number()
+})
+
+const A = Value.Cast(T, null)                          // const A = { x: 0, y: 0 }
+
+const B = Value.Cast(T, { x: 1 })                      // const B = { x: 1, y: 0 }
+
+const C = Value.Cast(T, { x: 1, y: 2, z: 3 })          // const C = { x: 1, y: 2 }
+```
 
 <a name="Guards"></a>
 
 ### Guards
 
-In some scenarios it may be helpful to test if an object is a valid TypeBox type. You can use the TypeGuard module to check an object conforms to a valid TypeBox schema representation. Consider the following.
+If reflecting on TypeBox types, it can be helpful to test if a value matches a TypeBox schematic. This can be achieved using the TypeGuard namespace. The TypeGuard namespace offers exhaustive checks for each known TypeBox type.
 
 ```typescript
 import { TypeGuard } from '@sinclair/typebox/guard'
 import { Type }  from '@sinclair/typebox'
 
-const T: any = Type.String()                         // T is any
+const T: any = {}                                    // T is any
 
 const { type } = T                                   // unsafe: type is any
 
@@ -647,8 +662,6 @@ if(TypeGuard.TString(T)) {
 
 ```
 
-
-
 <a name="Strict"></a>
 
 ### Strict
@@ -728,7 +741,7 @@ const ajv = addFormats(new Ajv({}), [
 //
 //--------------------------------------------------------------------------------------------
 
-const Vector = Type.Object({
+const T = Type.Object({
   x: Type.Number(),
   y: Type.Number(),
   z: Type.Number(),
@@ -740,7 +753,7 @@ const Vector = Type.Object({
 //
 //--------------------------------------------------------------------------------------------
 
-const OK = ajv.validate(Vector, { 
+const OK = ajv.validate(T, { 
   x: 1,
   y: 2,
   z: 3
@@ -753,7 +766,7 @@ Please refer to the official AJV [documentation](https://ajv.js.org/guide/gettin
 
 ### Compiler
 
-TypeBox includes a specialized type compiler that can be used as a runtime type checker in absense of a JSON Schema validator. This compiler is optimized for high throughput validation scenarios and generally performs better than AJV for most structural checks. Please note that this compiler is not fully JSON Schema compliant and is limited to TypeBox types only. The `TypeCompiler` contains a `Compile(T)` function that returns a `TypeCheck<T>` object that can be used to test the validity of a value as well as obtain errors.
+TypeBox includes a specialized `TypeCompiler` that can be used as a runtime type checker in lieu of a JSON Schema validator. This compiler is optimized for high throughput Web Socket messaging and can perform better than AJV for some structural checks. Please note that this compiler is not fully JSON Schema compliant and is limited to known TypeBox types only. The `TypeCompiler` contains a `Compile(T)` function that returns a `TypeCheck<T>` object that can be used to test the validity of a value as well as obtain errors.
 
 ```typescript
 import { TypeCompiler } from '@sinclair/typebox/compiler'
@@ -773,7 +786,7 @@ const OK = C.Check({
   z: 3 
 }) // -> true
 ```
-Errors can be obtained by calling the `Errors(...)` function. This function returns an iterator that may contain zero or more errors for the given value. For performance, you should only call `Errors(V)` if the `Check(V)` function returns false. 
+Errors can be obtained by calling the `Errors(...)` function. This function returns an iterator that may contain zero or more errors for the given value. For performance, you should only call `Errors(V)` if the `Check(V)` function returns `false`. 
 ```typescript
 const C = TypeCompiler.Compile(Type.Object({
   x: Type.Number(),
@@ -789,7 +802,7 @@ if(!C.Check(V)) {
   }
 }
 ```
-To inspect the generated validation code created by the compiler. You can call the `Code()` function on the `TypeCheck<T>` object.
+The TypeCompiler generates JavaScript validation routines types that are evaluated at runtime. You can inspect the generated code by calling the `Code()` function of the `TypeCheck<T>` object.
 
 ```typescript
 const C = TypeCompiler.Compile(Type.String())
@@ -809,4 +822,4 @@ console.log(C.Code())
 
 ### Contribute
 
-TypeBox is open to community contribution, however please ensure you submit an open issue before submitting your pull request. The TypeBox project does preference open community discussion prior to accepting new features.
+TypeBox is open to community contribution. Please ensure you submit an open issue before submitting your pull request. The TypeBox project preferences open community discussion prior to accepting new features.

package/typebox.d.ts

@@ -22,12 +22,10 @@ export interface SchemaOptions {
     title?: string;
     /** Description of this schema */
     description?: string;
-    /** Default value hint for this schema */
+    /** Default value for this schema */
     default?: any;
     /** Example values matching this schema. */
     examples?: any;
-    /** Design metadata for this schema */
-    design?: DesignType;
     [prop: string]: any;
 }
 export interface TSchema extends SchemaOptions {

package/value/cast.d.ts

@@ -0,0 +1,5 @@
+import * as Types from '../typebox';
+export declare namespace ValueCast {
+    function Visit(schema: Types.TSchema, references: Types.TSchema[], value: any): any;
+    function Cast<T extends Types.TSchema, R extends Types.TSchema[]>(schema: T, references: [...R], value: any): Types.Static<T>;
+}