@sinclair/typebox 0.24.30 → 0.24.31

package/format/format.d.ts

@@ -2,7 +2,7 @@ export declare type FormatValidationFunction = (value: string) => boolean;
 /** Shared string formats used by the TypeCompiler and Value modules */
 export declare namespace Format {
     /** Clears all formats */
-    function Clear(format: string): void;
+    function Clear(): void;
     /** Returns true if the string format exists */
     function Has(format: string): boolean;
     /** Sets a string format validation function */

package/format/format.js

@@ -33,7 +33,7 @@ var Format;
 (function (Format) {
     const formats = new Map();
     /** Clears all formats */
-    function Clear(format) {
+    function Clear() {
         return formats.clear();
     }
     Format.Clear = Clear;

package/package.json

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

package/readme.md

@@ -39,6 +39,8 @@ import { Static, Type } from '@sinclair/typebox'
 const T = Type.String()     // const T = { type: 'string' }
 
 type T = Static<typeof T>   // type T = string
+
+
 ```
 
 <a name="Overview"></a>
@@ -146,6 +148,8 @@ function receive(value: T) {                         // ... as a Type
     // ok...
   }
 }
+
+
 ```
 
 ## Types
@@ -340,6 +344,8 @@ The following table outlines the TypeBox mappings between TypeScript and JSON sc
 │                                │                             │ }                              │
 │                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
+
+
 ```
 
 ## Modifiers
@@ -382,6 +388,8 @@ TypeBox provides modifiers that can be applied to an objects properties. This al
 │                                │                             │ }                              │
 │                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
+
+
 ```
 
 ## Options
@@ -397,6 +405,8 @@ const T = Type.Number({ multipleOf: 2 })
 
 // array must have at least 5 integer values
 const T = Type.Array(Type.Integer(), { minItems: 5 })
+
+
 ```
 
 ## Extended Types
@@ -459,6 +469,8 @@ In addition to JSON schema types, TypeBox provides several extended types that a
 │                                │                             │ }                              │
 │                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
+
+
 ```
 
 ## Reference Types
@@ -474,6 +486,8 @@ const T = Type.String({ $id: 'T' })                  // const T = {
 const R = Type.Ref(T)                                // const R = {
                                                      //    $ref: 'T'
                                                      // }
+
+
 ```
 
 ## Recursive Types
@@ -511,6 +525,8 @@ function test(node: Node) {
                  .nodes[0].nodes[0]
                  .id
 }
+
+
 ```
 
 ## Generic Types
@@ -541,6 +557,8 @@ const U = Nullable(Type.Number())                    // const U = {
                                                      // }
 
 type U = Static<typeof U>                            // type U = number | null
+
+
 ```
 
 ## Unsafe Types
@@ -553,6 +571,8 @@ const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
                                                      // }
 
 type T = Static<typeof T>                            // type T = string
+
+
 ```
 
 This function can be used to create custom schemas for validators that require specific schema representations. An example of this might be OpenAPI's `nullable` and `enum` schemas which are not provided by TypeBox. The following demonstrates using `Type.Unsafe(...)` to create these types.
@@ -593,6 +613,8 @@ const T = StringEnum(['A', 'B', 'C'])                // const T = {
                                                      // }
 
 type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
+
+
 ```
 
 ## Conditional Types
@@ -644,6 +666,8 @@ The following table shows the TypeBox mappings between TypeScript and JSON schem
 │ )                              │                             │                                │
 │                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
+
+
 ```
 
 ## Values
@@ -705,6 +729,8 @@ if(TypeGuard.TString(T)) {
     
   // T is TString
 }
+
+
 ```
 
 ## Strict
@@ -732,6 +758,8 @@ const U = Type.Strict(T)                             // const U = {
                                                      //     } 
                                                      //   } 
                                                      // }
+
+
 ```
 
 ## Validation
@@ -795,6 +823,8 @@ const T = Type.Object({
 //--------------------------------------------------------------------------------------------
 
 const R = ajv.validate(T, { x: 1, y: 2, z: 3 })      // const R = true
+
+
 ```
 
 Please refer to the official Ajv [documentation](https://ajv.js.org/guide/getting-started.html) for additional information on using Ajv.
@@ -819,6 +849,8 @@ const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObje
 }))                                                  // }>>
 
 const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true 
+
+
 ```
 
 Validation errors can be read with the `Errors(...)` function.
@@ -860,22 +892,26 @@ console.log(C.Code())                                // return function check(va
                                                      //     (typeof value === 'string')
                                                      //   )
                                                      // }
+
+
 ```
 
 ## Formats
 
-Use the `Format` module to define custom string formats.
+Use the `Format` module to create custom string formats. Formats provide greater flexibility over [string patterns](https://json-schema.org/understanding-json-schema/reference/regular_expressions.html), but may come at a cost of schema portability. Formats are internally shared between the TypeCompiler and Value modules. TypeBox does not provide any built in formats by default.
+
+The format module is an optional import.
 
 ```typescript
 import { Format } from '@sinclair/typebox/format'
 ```
 
-Formats are shared between `Value` and the `TypeCompiler` modules.
+The following creates a custom format to validate Mongo `ObjectId` strings
 
 ```typescript
 //--------------------------------------------------------------------------------------------
 //
-// Use Format.Set(...) to define a format
+// Format.Set(...) to create the format
 //
 //--------------------------------------------------------------------------------------------
 
@@ -883,15 +919,19 @@ Format.Set('ObjectId', value => /^[0-9a-fA-F]{24}$/.test(value))
 
 //--------------------------------------------------------------------------------------------
 //
-// The format is now available to TypeCompiler and Value modules
+// The format can now be used by TypeCompiler and Value modules
 //
 //--------------------------------------------------------------------------------------------
 
 const T = Type.String({ format: 'ObjectId' })
 
-const R1 = TypeCompiler.Compile(T).Check('507f1f77bcf86cd799439011')
+const V = '507f1f77bcf86cd799439011'
+
+const R1 = TypeCompiler.Compile(T).Check(V)          // R1 = true
+
+const R2 = Value.Check(T, V)                         // R2 = true
+
 
-const R2 = Value.Check(T, '507f1f77bcf86cd799439011')                
 ```
 
 ## Benchmark

package/value/cast.d.ts

@@ -3,6 +3,9 @@ export declare class ValueCastUnknownTypeError extends Error {
     readonly schema: Types.TSchema;
     constructor(schema: Types.TSchema);
 }
+export interface ValueCastOptions {
+    convert: boolean;
+}
 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

@@ -80,6 +80,45 @@ class ValueCastUnknownTypeError extends Error {
 exports.ValueCastUnknownTypeError = ValueCastUnknownTypeError;
 var ValueCast;
 (function (ValueCast) {
+    // -----------------------------------------------------------
+    // Conversion
+    // -----------------------------------------------------------
+    function IsString(value) {
+        return typeof value === 'string';
+    }
+    function IsBoolean(value) {
+        return typeof value === 'boolean';
+    }
+    function IsNumber(value) {
+        return typeof value === 'number';
+    }
+    function IsBigInt(value) {
+        return typeof value === 'bigint';
+    }
+    function IsStringNumeric(value) {
+        return IsString(value) && !isNaN(value) && !isNaN(parseFloat(value));
+    }
+    function IsValueToString(value) {
+        return IsBigInt(value) || IsBoolean(value) || IsNumber(value);
+    }
+    function IsValueTrue(value) {
+        return (IsNumber(value) && value === 1) || (IsString(value) && ['true', 'TRUE', 'True'].includes(value));
+    }
+    function TryConvertString(value) {
+        return IsValueToString(value) ? value.toString() : value;
+    }
+    function TryConvertNumber(value) {
+        return IsStringNumeric(value) ? parseFloat(value) : value;
+    }
+    function TryConvertInteger(value) {
+        return IsStringNumeric(value) ? parseInt(value) : value;
+    }
+    function TryConvertBoolean(value) {
+        return IsValueTrue(value) ? true : value;
+    }
+    // -----------------------------------------------------------
+    // Casts
+    // -----------------------------------------------------------
     function Any(schema, references, value) {
         return check_1.ValueCheck.Check(schema, references, value) ? value : create_1.ValueCreate.Create(schema, references);
     }
@@ -91,7 +130,8 @@ var ValueCast;
         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);
+        const conversion = TryConvertBoolean(value);
+        return check_1.ValueCheck.Check(schema, references, conversion) ? conversion : create_1.ValueCreate.Create(schema, references);
     }
     function Constructor(schema, references, value) {
         if (check_1.ValueCheck.Check(schema, references, value))
@@ -112,7 +152,8 @@ var ValueCast;
         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);
+        const conversion = TryConvertInteger(value);
+        return check_1.ValueCheck.Check(schema, references, conversion) ? conversion : 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);
@@ -121,7 +162,8 @@ var ValueCast;
         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);
+        const conversion = TryConvertNumber(value);
+        return check_1.ValueCheck.Check(schema, references, conversion) ? conversion : create_1.ValueCreate.Create(schema, references);
     }
     function Object(schema, references, value) {
         if (check_1.ValueCheck.Check(schema, references, value))
@@ -169,7 +211,8 @@ var ValueCast;
         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);
+        const conversion = TryConvertString(value);
+        return check_1.ValueCheck.Check(schema, references, conversion) ? conversion : create_1.ValueCreate.Create(schema, references);
     }
     function Tuple(schema, references, value) {
         if (check_1.ValueCheck.Check(schema, references, value))

package/value/value.d.ts

@@ -10,9 +10,9 @@ export declare namespace Value {
     function Check<T extends Types.TSchema, R extends Types.TSchema[]>(schema: T, references: [...R], value: unknown): value is Types.Static<T>;
     /** Returns true if the value matches the given type. */
     function Check<T extends Types.TSchema>(schema: T, value: unknown): value is Types.Static<T>;
-    /** Casts a value into a structure matching the given type. The result will be a new value that retains as much information of the original value as possible. */
+    /** Casts a value into a given type. The return value will retain as much information of the original value as possible. Cast will convert string, number and boolean values if a reasonable conversion is possible. */
     function Cast<T extends Types.TSchema, R extends Types.TSchema[]>(schema: T, references: [...R], value: unknown): Types.Static<T>;
-    /** Casts a value into a structure matching the given type. The result will be a new value that retains as much information of the original value as possible. */
+    /** Casts a value into a given type. The return value will retain as much information of the original value as possible. Cast will convert string, number and boolean values if a reasonable conversion is possible. */
     function Cast<T extends Types.TSchema>(schema: T, value: unknown): Types.Static<T>;
     /** Returns an iterator for each error in this value. */
     function Errors<T extends Types.TSchema, R extends Types.TSchema[]>(schema: T, references: [...R], value: unknown): IterableIterator<ValueError>;