@sinclair/typebox 0.25.18 → 0.25.19

package/package.json

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

package/readme.md

@@ -96,10 +96,11 @@ License MIT
   - [Errors](#values-errors)
   - [Pointer](#values-pointer)
 - [TypeCheck](#typecheck)
-  - [Ajv](#typecheck-ajv)
   - [TypeCompiler](#typecheck-typecompiler)
-  - [Custom Types](#typecheck-custom-types)
-  - [Custom Formats](#typecheck-custom-formats)
+  - [Ajv](#typecheck-ajv)
+- [TypeSystem](#typecheck)
+  - [Types](#typesystem-types)
+  - [Formats](#typesystem-formats)
 - [Benchmark](#benchmark)
   - [Compile](#benchmark-compile)
   - [Validate](#benchmark-validate)
@@ -936,6 +937,71 @@ TypeBox targets JSON Schema Draft 6 and is built and tested against the Ajv JSON
 
 The following sections detail using these validators.
 
+<a name='typecheck-typecompiler'></a>
+
+### TypeCompiler
+
+TypeBox includes an high performance just-in-time (JIT) compiler and type checker that can be used in applications that require extremely fast validation. Note that this compiler is optimized for TypeBox types only where the schematics are known in advance.
+
+The compiler module is provided as an optional import.
+
+```typescript
+import { TypeCompiler } from '@sinclair/typebox/compiler'
+```
+
+Use the `Compile(...)` function to compile a type.
+
+```typescript
+const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
+  x: Type.Number(),                                  //     x: TNumber;
+  y: Type.Number(),                                  //     y: TNumber;
+  z: Type.Number()                                   //     z: TNumber;
+}))                                                  // }>>
+
+const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true
+```
+
+Validation errors can be read with the `Errors(...)` function.
+
+```typescript
+const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
+  x: Type.Number(),                                  //     x: TNumber;
+  y: Type.Number(),                                  //     y: TNumber;
+  z: Type.Number()                                   //     z: TNumber;
+}))                                                  // }>>
+
+const value = { }
+
+const errors = [...C.Errors(value)]                  // const errors = [{
+                                                     //   schema: { type: 'number' },
+                                                     //   path: '/x',
+                                                     //   value: undefined,
+                                                     //   message: 'Expected number'
+                                                     // }, {
+                                                     //   schema: { type: 'number' },
+                                                     //   path: '/y',
+                                                     //   value: undefined,
+                                                     //   message: 'Expected number'
+                                                     // }, {
+                                                     //   schema: { type: 'number' },
+                                                     //   path: '/z',
+                                                     //   value: undefined,
+                                                     //   message: 'Expected number'
+                                                     // }]
+```
+
+Compiled routines can be inspected with the `.Code()` function.
+
+```typescript
+const C = TypeCompiler.Compile(Type.String())        // const C: TypeCheck<TString>
+
+console.log(C.Code())                                // return function check(value) {
+                                                     //   return (
+                                                     //     (typeof value === 'string')
+                                                     //   )
+                                                     // }
+```
+
 <a name='typecheck-ajv'></a>
 
 ### Ajv
@@ -1066,125 +1132,87 @@ const R = ajv.validate(Type.Object({                 // const R = true
 </details>
 
 
-<a name='typecheck-typecompiler'></a>
+<a name='typesystem'></a>
 
-### TypeCompiler
+## TypeSystem
 
-TypeBox provides an optional high performance just-in-time (JIT) compiler and type checker that can be used in applications that require extremely fast validation. Note that this compiler is optimized for TypeBox types only where the schematics are known in advance. If defining custom types with `Type.Unsafe<T>` please consider Ajv.
+TypeBox provides an extensible TypeSystem module that enables developers to register additional types above and beyond the standard or extended type set. This module also allows developers to define custom string formats as well as override certain type checking behaviours.
 
-The compiler module is provided as an optional import.
+The TypeSystem module is provided as an optional import.
 
 ```typescript
-import { TypeCompiler } from '@sinclair/typebox/compiler'
+import { TypeSystem } from '@sinclair/typebox/system'
 ```
 
-Use the `Compile(...)` function to compile a type.
-
-```typescript
-const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
-  x: Type.Number(),                                  //     x: TNumber;
-  y: Type.Number(),                                  //     y: TNumber;
-  z: Type.Number()                                   //     z: TNumber;
-}))                                                  // }>>
+<a name='typesystem-types'></a>
 
-const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true
-```
+### Types
 
-Validation errors can be read with the `Errors(...)` function.
+Use the `CreateType(...)` function to specify and return a custom type. This function will return a type factory function that can be used to construct the type. The following creates and registers a BigNumber type which will statically infer as `bigint`.
 
 ```typescript
-const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
-  x: Type.Number(),                                  //     x: TNumber;
-  y: Type.Number(),                                  //     y: TNumber;
-  z: Type.Number()                                   //     z: TNumber;
-}))                                                  // }>>
+//--------------------------------------------------------------------------------------------
+//
+// Use TypeSystem.CreateType(...) to define and return a type factory function
+//
+//--------------------------------------------------------------------------------------------
 
-const value = { }
+type BigNumberOptions = { minimum?: bigint; maximum?: bigint }
 
-const errors = [...C.Errors(value)]                  // const errors = [{
-                                                     //   schema: { type: 'number' },
-                                                     //   path: '/x',
-                                                     //   value: undefined,
-                                                     //   message: 'Expected number'
-                                                     // }, {
-                                                     //   schema: { type: 'number' },
-                                                     //   path: '/y',
-                                                     //   value: undefined,
-                                                     //   message: 'Expected number'
-                                                     // }, {
-                                                     //   schema: { type: 'number' },
-                                                     //   path: '/z',
-                                                     //   value: undefined,
-                                                     //   message: 'Expected number'
-                                                     // }]
-```
+const BigNumber = TypeSystem.CreateType<bigint, BigNumberOptions>(
+  'BigNumber', 
+  (options, value) => {
+    if (typeof value !== 'bigint') return false
+    if (options.maximum !== undefined && value > options.maximum) return false
+    if (options.minimum !== undefined && value < options.minimum) return false
+    return true
+  }
+)
 
-Compiled routines can be inspected with the `.Code()` function.
+//--------------------------------------------------------------------------------------------
+//
+// Use the custom type like any other type
+//
+//--------------------------------------------------------------------------------------------
 
-```typescript
-const C = TypeCompiler.Compile(Type.String())        // const C: TypeCheck<TString>
+const T = BigNumber({ minimum: 10n, maximum: 20n })  // const T = { 
+                                                     //    minimum: 10n, 
+                                                     //    maximum: 20n, 
+                                                     //    [Symbol(TypeBox.Kind)]: 'BigNumber' 
+                                                     //  }
 
-console.log(C.Code())                                // return function check(value) {
-                                                     //   return (
-                                                     //     (typeof value === 'string')
-                                                     //   )
-                                                     // }
+const C = TypeCompiler.Compile(T)
+const X = C.Check(15n)                               // const X = true
+const Y = C.Check(5n)                                // const Y = false
+const Z = C.Check(25n)                               // const Z = false
 ```
 
-<a name='typecheck-custom-types'></a>
+<a name='typesystem-formats'></a>
 
-### Custom Types
+### Formats
 
-Use the custom module to create user defined types. User defined types require a `[Kind]` symbol property which is used to match the schema against a registered type. Custom types are specific to TypeBox and can only be used with the TypeCompiler and Value modules.
-
-The custom module is an optional import.
+Use the `CreateFormat(...)` function to specify user defined string formats. The following creates a custom string format that checks for lowercase.
 
 ```typescript
-import { Custom } from '@sinclair/typebox/custom'
-```
-
-The following creates a `bigint` type.
-
-```typescript
-import { Type, Kind } from '@sinclair/typebox'
-
-Custom.Set('bigint', (schema, value) => typeof value === 'bigint')
-//            ▲
-//            │
-//            └────────────────────────────┐
-//                                         │
-const T = Type.Unsafe<bigint>({ [Kind]: 'bigint' })  // const T = { [Kind]: 'BigInt' }
-
-const A = TypeCompiler.Compile(T).Check(1n)          // const A = true
-
-const B = Value.Check(T, 1)                          // const B = false
-```
-
-<a name='typecheck-custom-formats'></a>
-
-### Custom Formats
-
-Use the format module to create user defined string formats. The format module is specific to TypeBox can only be used with the TypeCompiler and Value modules. If using Ajv, please refer to the official Ajv format documentation located [here](https://ajv.js.org/guide/formats.html).
-
-The format module is an optional import.
+//--------------------------------------------------------------------------------------------
+//
+// Use TypeSystem.CreateFormat(...) to define a custom string format
+//
+//--------------------------------------------------------------------------------------------
 
-```typescript
-import { Format } from '@sinclair/typebox/format'
-```
+TypeSystem.CreateFormat('lowercase', value => value === value.toLowerCase())
 
-The following creates a custom string format that checks for lowercase.
+//--------------------------------------------------------------------------------------------
+//
+// Use the format by creating string types with the 'format' option
+//
+//--------------------------------------------------------------------------------------------
 
-```typescript
-Format.Set('lowercase', value => value === value.toLowerCase())
-//            ▲
-//            │
-//            └────────────────────┐         
-//                                 │
 const T = Type.String({ format: 'lowercase' })
 
-const A = TypeCompiler.Compile(T).Check('action')    // const A = true
+const A = Value.Check(T, 'action')                   // const A = true
 
-const B = Value.Check(T, 'Action')                   // const B = false
+const B = Value.Check(T, 'ACTION')                   // const B = false
 ```
 
 <a name='benchmark'></a>

package/system/system.d.ts

@@ -1,10 +1,17 @@
+export declare class TypeSystemDuplicateTypeKind extends Error {
+    constructor(kind: string);
+}
+export declare class TypeSystemDuplicateFormat extends Error {
+    constructor(kind: string);
+}
+/** Creates user defined types and formats and provides overrides for value checking behaviours */
 export declare namespace TypeSystem {
-    /**
-     * Sets whether arrays should be treated as kinds of objects. The default is `false`
-     */
+    /** Sets whether arrays should be treated as kinds of objects. The default is `false` */
     let AllowArrayObjects: boolean;
-    /**
-     * Sets whether numeric checks should consider NaN a valid number type. The default is `false`
-     */
+    /** Sets whether numeric checks should consider NaN a valid number type. The default is `false` */
     let AllowNaN: boolean;
+    /** Creates a custom type */
+    function CreateType<Type, Options = object>(kind: string, callback: (options: Options, value: unknown) => boolean): (options?: Partial<Options>) => import("@sinclair/typebox").TUnsafe<Type>;
+    /** Creates a custom string format */
+    function CreateFormat(format: string, callback: (value: string) => boolean): (value: string) => boolean;
 }

package/system/system.js

@@ -27,15 +27,43 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeSystem = void 0;
+exports.TypeSystem = exports.TypeSystemDuplicateFormat = exports.TypeSystemDuplicateTypeKind = void 0;
+const typebox_1 = require("@sinclair/typebox");
+const index_1 = require("../custom/index");
+const index_2 = require("../format/index");
+class TypeSystemDuplicateTypeKind extends Error {
+    constructor(kind) {
+        super(`Duplicate kind '${kind}' detected`);
+    }
+}
+exports.TypeSystemDuplicateTypeKind = TypeSystemDuplicateTypeKind;
+class TypeSystemDuplicateFormat extends Error {
+    constructor(kind) {
+        super(`Duplicate format '${kind}' detected`);
+    }
+}
+exports.TypeSystemDuplicateFormat = TypeSystemDuplicateFormat;
+/** Creates user defined types and formats and provides overrides for value checking behaviours */
 var TypeSystem;
 (function (TypeSystem) {
-    /**
-     * Sets whether arrays should be treated as kinds of objects. The default is `false`
-     */
+    /** Sets whether arrays should be treated as kinds of objects. The default is `false` */
     TypeSystem.AllowArrayObjects = false;
-    /**
-     * Sets whether numeric checks should consider NaN a valid number type. The default is `false`
-     */
+    /** Sets whether numeric checks should consider NaN a valid number type. The default is `false` */
     TypeSystem.AllowNaN = false;
+    /** Creates a custom type */
+    function CreateType(kind, callback) {
+        if (index_1.Custom.Has(kind))
+            throw new TypeSystemDuplicateTypeKind(kind);
+        index_1.Custom.Set(kind, callback);
+        return (options = {}) => typebox_1.Type.Unsafe({ ...options, [typebox_1.Kind]: kind });
+    }
+    TypeSystem.CreateType = CreateType;
+    /** Creates a custom string format */
+    function CreateFormat(format, callback) {
+        if (index_2.Format.Has(format))
+            throw new TypeSystemDuplicateFormat(format);
+        index_2.Format.Set(format, callback);
+        return callback;
+    }
+    TypeSystem.CreateFormat = CreateFormat;
 })(TypeSystem = exports.TypeSystem || (exports.TypeSystem = {}));