@sinclair/typebox 0.34.11 → 0.34.13

package/build/cjs/type/ref/ref.d.ts

@@ -11,18 +11,31 @@ export type TRefUnsafe<Type extends TSchema> = TUnsafe<Static<Type>>;
 /** `[Json]` Creates a Ref type.*/
 export declare function Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>;
 /**
- * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
- * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
- * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
- * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+ * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+ * a `string` value for the reference (and not a schema).
+ *
+ * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
  *
  * ```typescript
+ * // pre-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
  * const R = Type.Ref(T)
  * ```
- * to
+ * should be changed to the following
+ *
+ * ```typescript
+ * // post-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
+ * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+ * ```
+ * You can also create a generic function to replicate the pre-0.34.0 signature if required
  *
  * ```typescript
- * const R = Type.Unsafe<Static<T>>(T.$id)
+ * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
  * ```
  */
 export declare function Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>;

package/build/cjs/type/type/json.d.ts

@@ -151,18 +151,31 @@ export declare class JsonTypeBuilder {
     /** `[Json]` Creates a Ref type.*/
     Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>;
     /**
-     * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
-     * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
-     * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
-     * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+     * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+     * a `string` value for the reference (and not a schema).
+     *
+     * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
      *
      * ```typescript
+     * // pre-0.34.0
+     *
+     * const T = Type.String({ $id: 'T' })
+     *
      * const R = Type.Ref(T)
      * ```
-     * to
+     * should be changed to the following
+     *
+     * ```typescript
+     * // post-0.34.0
+     *
+     * const T = Type.String({ $id: 'T' })
+     *
+     * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+     * ```
+     * You can also create a generic function to replicate the pre-0.34.0 signature if required
      *
      * ```typescript
-     * const R = Type.Unsafe<Static<T>>(T.$id)
+     * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
      * ```
      */
     Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>;

package/build/cjs/value/convert/convert.js

@@ -70,7 +70,7 @@ function TryConvertBigInt(value) {
     return IsStringNumeric(value) ? BigInt(truncateInteger(value)) : (0, index_5.IsNumber)(value) ? BigInt(Math.trunc(value)) : IsValueFalse(value) ? BigInt(0) : IsValueTrue(value) ? BigInt(1) : value;
 }
 function TryConvertString(value) {
-    return IsValueToString(value) ? value.toString() : (0, index_5.IsSymbol)(value) && value.description !== undefined ? value.description.toString() : value;
+    return (0, index_5.IsSymbol)(value) && value.description !== undefined ? value.description.toString() : IsValueToString(value) ? value.toString() : value;
 }
 function TryConvertNumber(value) {
     return IsStringNumeric(value) ? parseFloat(value) : IsValueTrue(value) ? 1 : IsValueFalse(value) ? 0 : value;

package/build/cjs/value/mutate/mutate.js

@@ -8,6 +8,12 @@ const index_2 = require("../pointer/index");
 const index_3 = require("../clone/index");
 const index_4 = require("../../type/error/index");
 // ------------------------------------------------------------------
+// IsStandardObject
+// ------------------------------------------------------------------
+function IsStandardObject(value) {
+    return (0, index_1.IsObject)(value) && !(0, index_1.IsArray)(value);
+}
+// ------------------------------------------------------------------
 // Errors
 // ------------------------------------------------------------------
 class ValueMutateError extends index_4.TypeBoxError {
@@ -17,7 +23,7 @@ class ValueMutateError extends index_4.TypeBoxError {
 }
 exports.ValueMutateError = ValueMutateError;
 function ObjectType(root, path, current, next) {
-    if (!(0, index_1.IsObject)(current)) {
+    if (!IsStandardObject(current)) {
         index_2.ValuePointer.Set(root, path, (0, index_3.Clone)(next));
     }
     else {
@@ -69,7 +75,7 @@ function Visit(root, path, current, next) {
         return ArrayType(root, path, current, next);
     if ((0, index_1.IsTypedArray)(next))
         return TypedArrayType(root, path, current, next);
-    if ((0, index_1.IsObject)(next))
+    if (IsStandardObject(next))
         return ObjectType(root, path, current, next);
     if ((0, index_1.IsValueType)(next))
         return ValueType(root, path, current, next);
@@ -82,8 +88,8 @@ function IsNonMutableValue(value) {
 }
 function IsMismatchedValue(current, next) {
     // prettier-ignore
-    return (((0, index_1.IsObject)(current) && (0, index_1.IsArray)(next)) ||
-        ((0, index_1.IsArray)(current) && (0, index_1.IsObject)(next)));
+    return ((IsStandardObject(current) && (0, index_1.IsArray)(next)) ||
+        ((0, index_1.IsArray)(current) && IsStandardObject(next)));
 }
 // ------------------------------------------------------------------
 // Mutate

package/build/esm/type/ref/ref.d.mts

@@ -11,18 +11,31 @@ export type TRefUnsafe<Type extends TSchema> = TUnsafe<Static<Type>>;
 /** `[Json]` Creates a Ref type.*/
 export declare function Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>;
 /**
- * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
- * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
- * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
- * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+ * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+ * a `string` value for the reference (and not a schema).
+ *
+ * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
  *
  * ```typescript
+ * // pre-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
  * const R = Type.Ref(T)
  * ```
- * to
+ * should be changed to the following
+ *
+ * ```typescript
+ * // post-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
+ * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+ * ```
+ * You can also create a generic function to replicate the pre-0.34.0 signature if required
  *
  * ```typescript
- * const R = Type.Unsafe<Static<T>>(T.$id)
+ * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
  * ```
  */
 export declare function Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>;

package/build/esm/type/type/json.d.mts

@@ -151,18 +151,31 @@ export declare class JsonTypeBuilder {
     /** `[Json]` Creates a Ref type.*/
     Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>;
     /**
-     * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
-     * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
-     * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
-     * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+     * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+     * a `string` value for the reference (and not a schema).
+     *
+     * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
      *
      * ```typescript
+     * // pre-0.34.0
+     *
+     * const T = Type.String({ $id: 'T' })
+     *
      * const R = Type.Ref(T)
      * ```
-     * to
+     * should be changed to the following
+     *
+     * ```typescript
+     * // post-0.34.0
+     *
+     * const T = Type.String({ $id: 'T' })
+     *
+     * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+     * ```
+     * You can also create a generic function to replicate the pre-0.34.0 signature if required
      *
      * ```typescript
-     * const R = Type.Unsafe<Static<T>>(T.$id)
+     * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
      * ```
      */
     Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>;

package/build/esm/value/convert/convert.mjs

@@ -66,7 +66,7 @@ function TryConvertBigInt(value) {
     return IsStringNumeric(value) ? BigInt(truncateInteger(value)) : IsNumber(value) ? BigInt(Math.trunc(value)) : IsValueFalse(value) ? BigInt(0) : IsValueTrue(value) ? BigInt(1) : value;
 }
 function TryConvertString(value) {
-    return IsValueToString(value) ? value.toString() : IsSymbol(value) && value.description !== undefined ? value.description.toString() : value;
+    return IsSymbol(value) && value.description !== undefined ? value.description.toString() : IsValueToString(value) ? value.toString() : value;
 }
 function TryConvertNumber(value) {
     return IsStringNumeric(value) ? parseFloat(value) : IsValueTrue(value) ? 1 : IsValueFalse(value) ? 0 : value;

package/build/esm/value/mutate/mutate.mjs

@@ -3,6 +3,12 @@ import { ValuePointer } from '../pointer/index.mjs';
 import { Clone } from '../clone/index.mjs';
 import { TypeBoxError } from '../../type/error/index.mjs';
 // ------------------------------------------------------------------
+// IsStandardObject
+// ------------------------------------------------------------------
+function IsStandardObject(value) {
+    return IsObject(value) && !IsArray(value);
+}
+// ------------------------------------------------------------------
 // Errors
 // ------------------------------------------------------------------
 export class ValueMutateError extends TypeBoxError {
@@ -11,7 +17,7 @@ export class ValueMutateError extends TypeBoxError {
     }
 }
 function ObjectType(root, path, current, next) {
-    if (!IsObject(current)) {
+    if (!IsStandardObject(current)) {
         ValuePointer.Set(root, path, Clone(next));
     }
     else {
@@ -63,7 +69,7 @@ function Visit(root, path, current, next) {
         return ArrayType(root, path, current, next);
     if (IsTypedArray(next))
         return TypedArrayType(root, path, current, next);
-    if (IsObject(next))
+    if (IsStandardObject(next))
         return ObjectType(root, path, current, next);
     if (IsValueType(next))
         return ValueType(root, path, current, next);
@@ -76,8 +82,8 @@ function IsNonMutableValue(value) {
 }
 function IsMismatchedValue(current, next) {
     // prettier-ignore
-    return ((IsObject(current) && IsArray(next)) ||
-        (IsArray(current) && IsObject(next)));
+    return ((IsStandardObject(current) && IsArray(next)) ||
+        (IsArray(current) && IsStandardObject(next)));
 }
 // ------------------------------------------------------------------
 // Mutate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.34.11",
+  "version": "0.34.13",
   "description": "Json Schema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "typescript",

package/readme.md

@@ -68,6 +68,7 @@ License MIT
   - [Options](#types-options)
   - [Properties](#types-properties)
   - [Generics](#types-generics)
+  - [Recursive](#types-recursive)
   - [Modules](#types-modules)
   - [Template Literal](#types-template-literal)
   - [Indexed](#types-indexed)
@@ -759,21 +760,51 @@ const T = Nullable(Type.String())                    // const T = {
 type T = Static<typeof T>                            // type T = string | null
 ```
 
-<a name='types-modules'></a>
+<a name='types-recursive'></a>
 
-### Module Types
+### Recursive Types
 
-TypeBox Modules are containers for related types. They provide a referential namespace, enabling types to reference one another via string identifiers. Modules support both singular and mutually recursive referencing within the context of a module, as well as referential computed types (such as Partial + Ref). All Module types must be imported before use. TypeBox represents an imported type with the `$defs` Json Schema keyword. 
+Use the Recursive function to create a singular recursive type.
 
-#### Usage
+```typescript
+const Node = Type.Recursive(Self => Type.Object({    // const Node = {
+  id: Type.String(),                                 //   $id: 'Node',
+  nodes: Type.Array(Self)                            //   type: 'object',
+}), { $id: 'Node' })                                 //   properties: {
+                                                     //     id: {
+                                                     //       type: 'string'
+                                                     //     },
+                                                     //     nodes: {
+                                                     //       type: 'array',
+                                                     //       items: {
+                                                     //         $ref: 'Node'
+                                                     //       }
+                                                     //     }
+                                                     //   },
+                                                     //   required: [
+                                                     //     'id',
+                                                     //     'nodes'
+                                                     //   ]
+                                                     // }
 
-The following creates a Module with User and PartialUser types. Note that the PartialUser type is specified as a Partial + Ref to the User type. It is not possible to perform a Partial operation directly on a reference, so TypeBox will return a TComputed type that defers the Partial operation until all types are resolved. The TComputed type is evaluated when calling Import on the Module.
+type Node = Static<typeof Node>                      // type Node = {
+                                                     //   id: string
+                                                     //   nodes: Node[]
+                                                     // }
 
-```typescript
-// Module with PartialUser and User types
+function test(node: Node) {
+  const id = node.nodes[0].nodes[0].id               // id is string
+}
+```
 
-const Module = Type.Module({
+<a name='types-modules'></a>
+
+### Module Types
 
+Module types are containers for a set of referential types. Modules act as namespaces, enabling types to reference one another via string identifiers. Modules support both singular and mutually recursive references, as well as deferred dereferencing for computed types such as Partial. Types imported from a module are expressed using the Json Schema `$defs` keyword. 
+
+```typescript
+const Module = Type.Module({
   PartialUser: Type.Partial(Type.Ref('User')),  // TComputed<'Partial', [TRef<'User'>]>
 
   User: Type.Object({                           // TObject<{
@@ -781,11 +812,7 @@ const Module = Type.Module({
     name: Type.String(),                        //   name: TString,
     email: Type.String()                        //   email: TString
   }),                                           // }>
-  
 })
-
-// Types must be imported before use.
-
 const User = Module.Import('User')               // const User: TImport<{...}, 'User'>
 
 type User = Static<typeof User>                  // type User = { 
@@ -803,7 +830,6 @@ type PartialUser = Static<typeof PartialUser>    // type PartialUser = {
                                                  // }
 ```
 
-
 <a name='types-template-literal'></a>
 
 ### Template Literal Types