@sinclair/typebox 0.24.5 → 0.24.8

package/{value/reflect.js → guard/index.js}

@@ -1,7 +1,7 @@
 "use strict";
 /*--------------------------------------------------------------------------
 
-@sinclair/typebox/value
+@sinclair/typebox/guards
 
 The MIT License (MIT)
 
@@ -26,17 +26,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Reflect = void 0;
-function Reflect(value) {
-    if (value === undefined)
-        return 'undefined';
-    if (value === null)
-        return 'null';
-    if (typeof value === 'object' && !globalThis.Array.isArray(value) && value !== null)
-        return 'object';
-    if (typeof value === 'object' && globalThis.Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-exports.Reflect = Reflect;
+__exportStar(require("./guard"), exports);

package/package.json

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

package/readme.md

@@ -62,6 +62,7 @@ License MIT
 - [Generic Types](#Generic-Types)
 - [Unsafe Types](#Unsafe-Types)
 - [Values](#Values)
+- [Guards](#Guards)
 - [Strict](#Strict)
 - [Validation](#Validation)
 - [Compiler](#Compiler)
@@ -435,7 +436,7 @@ In addition to JSON schema types, TypeBox provides several extended types that a
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const T = Type.Uint8Array()    │ type T = Uint8Array         │ const T = {                    │
-│                                │                             │   type: 'Uint8Array',          │
+│                                │                             │   type: 'object',              │
 │                                │                             │   specialized: 'Uint8Array'    │
 │                                │                             │ }                              │
 │                                │                             │                                │
@@ -449,7 +450,8 @@ In addition to JSON schema types, TypeBox provides several extended types that a
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const T = Type.Undefined()     │ type T = undefined          │ const T = {                    │
-│                                │                             │   type: 'undefined'            │
+│                                │                             │   type: 'object',              │
+│                                │                             │   specialized: 'Undefined'     │
 │                                │                             │ }                              │
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
@@ -600,28 +602,65 @@ const T = StringEnum(['A', 'B', 'C'])                // const T = {
 
 type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
 ```
+
 <a name="Values"></a>
 
 ### 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
+
+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 = {}                                    // T is any
+
+const { type } = T                                   // unsafe: type is any
+
+if(TypeGuard.TString(T)) {
+    
+  const { type } = T                                 // safe: type is 'string'
+}
+
+```
 
 <a name="Strict"></a>
 
@@ -702,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(),
@@ -714,7 +753,7 @@ const Vector = Type.Object({
 //
 //--------------------------------------------------------------------------------------------
 
-const OK = ajv.validate(Vector, { 
+const OK = ajv.validate(T, { 
   x: 1,
   y: 2,
   z: 3
@@ -727,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'
@@ -747,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(),
@@ -763,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())
@@ -783,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>;
+}

package/value/cast.js

@@ -0,0 +1,251 @@
+"use strict";
+/*--------------------------------------------------------------------------
+
+@sinclair/typebox/value
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Haydn Paterson (sinclair) <haydn.developer@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValueCast = void 0;
+const Types = require("../typebox");
+const create_1 = require("./create");
+const check_1 = require("./check");
+// --------------------------------------------------------------------------
+// Specialized Union Patch. Because a value can be one of many different
+// unions with properties potentially overlapping, we need a strategy
+// in which to resolve the appropriate schema to patch from.
+//
+// The following will score each union type found within the types anyOf
+// array. Typically this is executed for objects only, so the score is a
+// essentially a tally of how many properties are valid. The reasoning
+// here is the discriminator field would tip the scales in favor of that
+// union if other properties overlap and match.
+// --------------------------------------------------------------------------
+var UnionValueCast;
+(function (UnionValueCast) {
+    function Score(schema, references, value) {
+        let score = 0;
+        if (schema[Types.Kind] === 'Object' && typeof value === 'object' && value !== null) {
+            const objectSchema = schema;
+            const entries = globalThis.Object.entries(objectSchema.properties);
+            score += entries.reduce((acc, [key, schema]) => acc + (check_1.ValueCheck.Check(schema, references, value[key]) ? 1 : 0), 0);
+        }
+        return score;
+    }
+    function Select(schema, references, value) {
+        let select = schema.anyOf[0];
+        let best = 0;
+        for (const subschema of schema.anyOf) {
+            const score = Score(subschema, references, value);
+            if (score > best) {
+                select = subschema;
+                best = score;
+            }
+        }
+        return select;
+    }
+    function Create(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : ValueCast.Cast(Select(schema, references, value), references, value);
+    }
+    UnionValueCast.Create = Create;
+})(UnionValueCast || (UnionValueCast = {}));
+var ValueCast;
+(function (ValueCast) {
+    const ids = new Map();
+    function Any(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Array(schema, references, value) {
+        if (check_1.ValueCheck.Check(schema, references, value))
+            return value;
+        if (!globalThis.Array.isArray(value))
+            return create_1.ValueCreate.Create(schema, references);
+        return value.map((val) => Visit(schema.items, references, val));
+    }
+    function Boolean(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Constructor(schema, references, value) {
+        if (check_1.ValueCheck.Check(schema, references, value))
+            return create_1.ValueCreate.Create(schema, references);
+        const required = new Set(schema.returns.required || []);
+        const result = function () { };
+        for (const [key, property] of globalThis.Object.entries(schema.returns.properties)) {
+            if (!required.has(key) && value.prototype[key] === undefined)
+                continue;
+            result.prototype[key] = Visit(property, references, value.prototype[key]);
+        }
+        return result;
+    }
+    function Enum(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Function(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Integer(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Literal(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Null(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Number(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Object(schema, references, value) {
+        if (check_1.ValueCheck.Check(schema, references, value))
+            return value;
+        if (value === null || typeof value !== 'object')
+            return create_1.ValueCreate.Create(schema, references);
+        ids.set(schema.$id, schema);
+        const required = new Set(schema.required || []);
+        const result = {};
+        for (const [key, property] of globalThis.Object.entries(schema.properties)) {
+            if (!required.has(key) && value[key] === undefined)
+                continue;
+            result[key] = Visit(property, references, value[key]);
+        }
+        return result;
+    }
+    function Promise(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Record(schema, references, value) {
+        if (check_1.ValueCheck.Check(schema, references, value))
+            return value;
+        if (value === null || typeof value !== 'object' || globalThis.Array.isArray(value))
+            return create_1.ValueCreate.Create(schema, references);
+        const subschemaKey = globalThis.Object.keys(schema.patternProperties)[0];
+        const subschema = schema.patternProperties[subschemaKey];
+        const result = {};
+        for (const [propKey, propValue] of globalThis.Object.entries(value)) {
+            result[propKey] = Visit(subschema, references, propValue);
+        }
+        return result;
+    }
+    function Recursive(schema, references, value) {
+        throw Error('Cannot patch recursive schemas');
+    }
+    function Ref(schema, references, value) {
+        const reference = references.find((reference) => reference.$id === schema.$ref);
+        if (reference === undefined)
+            throw new Error(`CastValue.Ref: Cannot find schema with $id '${schema.$ref}'.`);
+        return Visit(reference, references, value);
+    }
+    function Self(schema, references, value) {
+        const reference = references.find((reference) => reference.$id === schema.$ref);
+        if (reference === undefined)
+            throw new Error(`CastValue.Self: Cannot find schema with $id '${schema.$ref}'.`);
+        return Visit(reference, references, value);
+    }
+    function String(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Tuple(schema, references, value) {
+        if (check_1.ValueCheck.Check(schema, references, value))
+            return value;
+        if (!globalThis.Array.isArray(value))
+            return create_1.ValueCreate.Create(schema, references);
+        if (schema.items === undefined)
+            return [];
+        return schema.items.map((schema, index) => Visit(schema, references, value[index]));
+    }
+    function Undefined(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Union(schema, references, value) {
+        return UnionValueCast.Create(schema, references, value);
+    }
+    function Uint8Array(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Unknown(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Void(schema, references, value) {
+        return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
+    }
+    function Visit(schema, references, value) {
+        const anyReferences = schema.$id === undefined ? references : [schema, ...references];
+        const anySchema = schema;
+        switch (schema[Types.Kind]) {
+            case 'Any':
+                return Any(anySchema, anyReferences, value);
+            case 'Array':
+                return Array(anySchema, anyReferences, value);
+            case 'Boolean':
+                return Boolean(anySchema, anyReferences, value);
+            case 'Constructor':
+                return Constructor(anySchema, anyReferences, value);
+            case 'Enum':
+                return Enum(anySchema, anyReferences, value);
+            case 'Function':
+                return Function(anySchema, anyReferences, value);
+            case 'Integer':
+                return Integer(anySchema, anyReferences, value);
+            case 'Literal':
+                return Literal(anySchema, anyReferences, value);
+            case 'Null':
+                return Null(anySchema, anyReferences, value);
+            case 'Number':
+                return Number(anySchema, anyReferences, value);
+            case 'Object':
+                return Object(anySchema, anyReferences, value);
+            case 'Promise':
+                return Promise(anySchema, anyReferences, value);
+            case 'Record':
+                return Record(anySchema, anyReferences, value);
+            case 'Rec':
+                return Recursive(anySchema, anyReferences, value);
+            case 'Ref':
+                return Ref(anySchema, anyReferences, value);
+            case 'Self':
+                return Self(anySchema, anyReferences, value);
+            case 'String':
+                return String(anySchema, anyReferences, value);
+            case 'Tuple':
+                return Tuple(anySchema, anyReferences, value);
+            case 'Undefined':
+                return Undefined(anySchema, anyReferences, value);
+            case 'Union':
+                return Union(anySchema, anyReferences, value);
+            case 'Uint8Array':
+                return Uint8Array(anySchema, anyReferences, value);
+            case 'Unknown':
+                return Unknown(anySchema, anyReferences, value);
+            case 'Void':
+                return Void(anySchema, anyReferences, value);
+            default:
+                throw Error(`Unknown schema kind '${schema[Types.Kind]}'`);
+        }
+    }
+    ValueCast.Visit = Visit;
+    function Cast(schema, references, value) {
+        return schema.$id === undefined ? Visit(schema, references, value) : Visit(schema, [schema, ...references], value);
+    }
+    ValueCast.Cast = Cast;
+})(ValueCast = exports.ValueCast || (exports.ValueCast = {}));

package/value/check.d.ts

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