@cleverbrush/schema 4.4.3 → 5.0.0

package/dist/builders/GenericSchemaBuilder.d.ts

@@ -7,8 +7,8 @@ type GenericSchemaBuilderCreateProps<TRequired extends boolean = true> = Partial
  * builder whose TypeScript type is inferred from the template function's
  * generic signature.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link generic | generic()} function instead.
  *
  * @example Single type parameter
@@ -50,7 +50,7 @@ type GenericSchemaBuilderCreateProps<TRequired extends boolean = true> = Partial
  * // InferType → { ok: boolean; value?: string; error?: number }
  * ```
  *
- * @example With default arguments (enables direct `.validate()` on the template)
+ * @example With default arguments
  * ```ts
  * const AnyList = generic(
  *   [any()],   // default args — one per template parameter
@@ -87,6 +87,16 @@ type GenericSchemaBuilderCreateProps<TRequired extends boolean = true> = Partial
  */
 export declare class GenericSchemaBuilder<TFn extends (...args: any[]) => SchemaBuilder<any, any, any, any, any>, TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? ReturnType<TFn> extends SchemaBuilder<infer R, any, any, any, any> ? R : any : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'generic',
+        TFn,
+        TRequired,
+        TNullable,
+        TExplicitType,
+        THasDefault,
+        TResult
+    ];
     /**
      * Applies the template function with concrete schema arguments, returning
      * a fully typed concrete schema builder. TypeScript infers the result type
@@ -152,6 +162,7 @@ export declare class GenericSchemaBuilder<TFn extends (...args: any[]) => Schema
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/IntersectionSchemaBuilder.d.ts

@@ -26,6 +26,7 @@ export declare class IntersectionSchemaBuilder<TLeft extends SchemaBuilder<any,
         defaultValue: (TExplicitType extends undefined ? SchemaIntersection<TLeft, TRight> : TExplicitType) | (() => TExplicitType extends undefined ? SchemaIntersection<TLeft, TRight> : TExplicitType) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: (TExplicitType extends undefined ? SchemaIntersection<TLeft, TRight> : TExplicitType) | (() => TExplicitType extends undefined ? SchemaIntersection<TLeft, TRight> : TExplicitType) | undefined;
         example: unknown;

package/dist/builders/LazySchemaBuilder.d.ts

@@ -69,6 +69,7 @@ export declare class LazySchemaBuilder<TResult = any, TRequired extends boolean
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/NullSchemaBuilder.d.ts

@@ -11,8 +11,8 @@ type NullSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType
  * in a typed schema, for example in discriminated-union branches or when
  * modelling a JSON payload that may carry a JSON `null` value.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link nul | nul()} function instead.
  *
  * @example
@@ -74,12 +74,10 @@ export declare class NullSchemaBuilder<TRequired extends boolean = true, TNullab
     validateAsync(object: null, context?: ValidationContext): Promise<ValidationResult<null>>;
     /**
      * Performs synchronous validation of the schema over `object`.
-     * @param context Optional `ValidationContext` settings.
      */
     protected _validate(object: null, _context?: ValidationContext): ValidationResult<null>;
     /**
      * Performs async validation of the schema over `object`.
-     * @param context Optional `ValidationContext` settings.
      */
     protected _validateAsync(object: null, _context?: ValidationContext): Promise<ValidationResult<null>>;
     protected createFromProps<TReq extends boolean>(props: NullSchemaBuilderCreateProps<TReq>): this;

package/dist/builders/NumberSchemaBuilder.d.ts

@@ -5,30 +5,34 @@ type NumberSchemaBuilderCreateProps<T = number, R extends boolean = true> = Part
  * Can be required or optional, can be restricted to be equal to a certain value,
  * can be restricted to be in a certain range, can be restricted to be integer.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link number | number()} function instead.
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = number().equals(42);
  * const result = schema.validate(42);
  * // result.valid === true
  * // result.object === 42
  * ```
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = number();
  * const result = schema.validate('42');
  * // result.valid === false
  * // result.errors[0].message === 'is expected to be a number'
  * ```
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = number().min(0).max(100);
  * const result = schema.validate(42);
  * // result.valid === true
  * // result.object === 42
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = number().min(0).max(100);
  * const result = schema.validate(142.5);
  * // result.valid === false
@@ -39,6 +43,14 @@ type NumberSchemaBuilderCreateProps<T = number, R extends boolean = true> = Part
  */
 export declare class NumberSchemaBuilder<TResult = number, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'number',
+        TResult,
+        TRequired,
+        TNullable,
+        THasDefault
+    ];
     /**
      * @hidden
      */
@@ -118,6 +130,7 @@ export declare class NumberSchemaBuilder<TResult = number, TRequired extends boo
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;
@@ -236,7 +249,8 @@ export declare class NumberSchemaBuilder<TResult = number, TRequired extends boo
      * a string source (e.g. a parse-string schema, URL parameter,
      * or form input).
      *
-     * @example ```ts
+     * @example
+     * ```ts
      * const schema = number().coerce();
      * const result = schema.validate('42');
      * // result.valid === true

package/dist/builders/NumberSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-ELPPAHNO.js";import"../chunk-REYZ7G7J.js";export{a as NumberSchemaBuilder,b as number};
+import{a,b}from"../chunk-BTR3ZGES.js";import"../chunk-2BKBVVZ3.js";export{a as NumberSchemaBuilder,b as number};
 //# sourceMappingURL=NumberSchemaBuilder.js.map

package/dist/builders/ObjectSchemaBuilder.d.ts

@@ -125,7 +125,7 @@ export type ObjectSchemaValidationResult<T, TRootSchema extends ObjectSchemaBuil
      * This is the **recommended** way to inspect validation errors — it provides type-safe,
      * per-property error details including `isValid`, `errors`, and `seenValue`.
      *
-     * Prefer this over the deprecated `errors` array.
+     * Inspect root or property-specific validation errors with a selector.
      *
      * @param selector a callback function to select property from the schema.
      */
@@ -150,8 +150,8 @@ export type ObjectSchemaValidationResult<T, TRootSchema extends ObjectSchemaBuil
  * Which means that you can define nested objects and arrays of
  * any complexity.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link object | object()} function instead.
  *
  * @example
@@ -195,7 +195,7 @@ export type ObjectSchemaValidationResult<T, TRootSchema extends ObjectSchemaBuil
  * });
  *
  * // result.valid === false
- * // result.errors is deprecated — use result.getErrorsFor() instead
+ * // Inspect property errors using result.getErrorsFor().
  * // result.getErrorsFor((p) => p.age).errors // ["is expected to have property 'age'"]
  * ```
  *
@@ -228,6 +228,16 @@ export type ObjectSchemaValidationResult<T, TRootSchema extends ObjectSchemaBuil
  */
 export declare class ObjectSchemaBuilder<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>> = {}, TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TConstructorSchemas extends SchemaBuilder<any, any, any, any, any>[] = []> extends SchemaBuilder<undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'object',
+        TProperties,
+        TRequired,
+        TNullable,
+        TExplicitType,
+        THasDefault,
+        TConstructorSchemas
+    ];
     /** Marks this builder as having sub-properties for descriptor tree recursion. */
     readonly [SYMBOL_HAS_PROPERTIES] = true;
     /**
@@ -269,6 +279,7 @@ export declare class ObjectSchemaBuilder<TProperties extends Record<string, Sche
         defaultValue: (undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | (() => undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: (undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | (() => undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | undefined;
         example: unknown;

package/dist/builders/ObjectSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-6LSN7NXQ.js";import"../chunk-REYZ7G7J.js";export{a as ObjectSchemaBuilder,b as object};
+import{a,b}from"../chunk-JEBLDVKG.js";import"../chunk-2BKBVVZ3.js";export{a as ObjectSchemaBuilder,b as object};
 //# sourceMappingURL=ObjectSchemaBuilder.js.map

package/dist/builders/ParseStringSchemaBuilder.d.ts

@@ -87,6 +87,7 @@ export declare class ParseStringSchemaBuilder<TResult = any, TRequired extends b
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/ParseStringSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-XHSBY2QK.js";import"../chunk-6LSN7NXQ.js";import"../chunk-REYZ7G7J.js";export{a as ParseStringSchemaBuilder,b as parseString};
+import{a,b}from"../chunk-X6CT6I2V.js";import"../chunk-JEBLDVKG.js";import"../chunk-2BKBVVZ3.js";export{a as ParseStringSchemaBuilder,b as parseString};
 //# sourceMappingURL=ParseStringSchemaBuilder.js.map

package/dist/builders/PromiseSchemaBuilder.d.ts

@@ -6,8 +6,8 @@ type PromiseSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnT
  * function) and optionally carries a typed resolved-value schema so that
  * the inferred TypeScript type is `Promise<T>` instead of `Promise<any>`.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link promise | promise()} function instead.
  *
  * @example Basic validation
@@ -43,6 +43,16 @@ type PromiseSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnT
  */
 export declare class PromiseSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResolvedTypeSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, TResult = TExplicitType extends undefined ? TResolvedTypeSchema extends SchemaBuilder<any, any, any, any, any> ? Promise<InferType<TResolvedTypeSchema>> : Promise<any> : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'promise',
+        TRequired,
+        TNullable,
+        TExplicitType,
+        THasDefault,
+        TResolvedTypeSchema,
+        TResult
+    ];
     /**
      * @hidden
      */
@@ -90,6 +100,7 @@ export declare class PromiseSchemaBuilder<TRequired extends boolean = true, TNul
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/PromiseSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-JUFZ7PLO.js";import"../chunk-REYZ7G7J.js";export{a as PromiseSchemaBuilder,b as promise};
+import{a,b}from"../chunk-25KL2NBJ.js";import"../chunk-2BKBVVZ3.js";export{a as PromiseSchemaBuilder,b as promise};
 //# sourceMappingURL=PromiseSchemaBuilder.js.map

package/dist/builders/RecordSchemaBuilder.d.ts

@@ -186,6 +186,17 @@ type RecordSchemaBuilderCreateProps<TKeySchema extends StringSchemaBuilder<any,
  */
 export declare class RecordSchemaBuilder<TKeySchema extends StringSchemaBuilder<any, any, any, any>, TValueSchema extends SchemaBuilder<any, any, any, any, any>, TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? Record<InferType<TKeySchema>, InferType<TValueSchema>> : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'record',
+        TKeySchema,
+        TValueSchema,
+        TRequired,
+        TNullable,
+        TExplicitType,
+        THasDefault,
+        TResult
+    ];
     /**
      * @hidden
      */
@@ -251,6 +262,7 @@ export declare class RecordSchemaBuilder<TKeySchema extends StringSchemaBuilder<
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/RecordSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-XL723XFL.js";import"../chunk-REYZ7G7J.js";export{a as RecordSchemaBuilder,b as record};
+import{a,b}from"../chunk-W5D22D4P.js";import"../chunk-2BKBVVZ3.js";export{a as RecordSchemaBuilder,b as record};
 //# sourceMappingURL=RecordSchemaBuilder.js.map

package/dist/builders/SchemaBuilder.d.ts

@@ -51,7 +51,7 @@ export type InferType<T> = T extends {
  *
  * When returned from an object-level validator (via {@link SchemaBuilder.addValidator | addValidator}),
  * the optional `property` selector can route the error to a specific property
- * so that {@link ObjectSchemaValidationResult.getErrorsFor | getErrorsFor()} reports it
+ * so that `ObjectSchemaValidationResult.getErrorsFor()` reports it
  * on that property rather than only on the root object.
  *
  * ```ts
@@ -192,6 +192,8 @@ export type SchemaBuilderProps<T> = {
     hasCatch?: boolean;
     description?: string;
     schemaName?: string;
+    /** @internal Canonical named definition for a use-site-only derivative. */
+    referenceTarget?: SchemaBuilder<any, any, any, any, any>;
     example?: unknown;
 };
 export type ValidationContext<TSchema extends SchemaBuilder<any, any, any, any> = SchemaBuilder<any, any, any, any>> = {
@@ -404,8 +406,18 @@ export type PropertyDescriptor<TRootSchema extends ObjectSchemaBuilder<any, any,
  * Has a possibility to filter properties by the type (`TAssignableTo` type parameter).
  */
 export type PropertyDescriptorTree<TSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any> = TSchema, TAssignableTo = any, TParentPropertyDescriptor = undefined> = PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor> & (TSchema extends ObjectSchemaBuilder<infer TProperties, any, any> ? {
-    [K in keyof TProperties]: TProperties[K] extends ObjectSchemaBuilder<any, any, any> ? PropertyDescriptorTree<TProperties[K], TRootSchema, any, PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : TProperties[K] extends ExternSchemaBuilder<any, any, any, any, any, any, infer TExternResult> ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> & ExternOutputPropertyDescriptors<TExternResult, TRootSchema, PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string>> : TProperties[K] extends ArraySchemaBuilder<infer TArrayElement, any, any> ? TArrayElement extends ObjectSchemaBuilder<any, any, any, any, any> ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : InferType<TProperties[K]> extends TAssignableTo ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : never : InferType<TProperties[K]> extends TAssignableTo ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : never;
+    [K in keyof TProperties]: TProperties[K] extends ObjectSchemaBuilder<any, any, any> ? PropertyDescriptorTree<TProperties[K], TRootSchema, any, PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : TProperties[K] extends ExternSchemaBuilder<any, any, any, any, any, any, infer TExternResult> ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> & ExternOutputPropertyDescriptors<TExternResult, TRootSchema, PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string>> : TProperties[K] extends ArraySchemaBuilder<infer TArrayElement, any, any> ? TArrayElement extends ObjectSchemaBuilder<any, any, any, any, any> ? IndexedPropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : InferType<TProperties[K]> extends TAssignableTo ? IndexedPropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : never : InferType<TProperties[K]> extends TAssignableTo ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>, K & string> : never;
 } : never);
+/**
+ * A descriptor that preserves its array binding and exposes lazy indexed child
+ * descriptors. Indices are non-negative integers; they are positions, not item
+ * identities. Object and nested-array elements retain their schema types.
+ *
+ * @example `object.getPropertiesFor(schema).addresses[0].city`
+ */
+export type IndexedPropertyDescriptor<TRoot extends ObjectSchemaBuilder<any, any, any, any, any>, TSchema, TParent, TKey extends string = string> = PropertyDescriptor<TRoot, TSchema, TParent, TKey> & (TSchema extends ObjectSchemaBuilder<any, any, any> ? PropertyDescriptorTree<TSchema, TRoot, any, TParent> : TSchema extends ArraySchemaBuilder<infer TElement, any, any> ? {
+    readonly [index: number]: IndexedPropertyDescriptor<TRoot, TElement, PropertyDescriptor<TRoot, TSchema, TParent, TKey>>;
+} : {});
 /**
  * Recursively maps the keys of an extern schema's output type into
  * property descriptors.  When a value is a plain-object type its keys
@@ -441,8 +453,8 @@ type ResolvedSchemaType<TResult, TRequired extends boolean, TNullable extends bo
  * Base class for all schema builders. Provides basic functionality for schema building.
  *
  * **Note:** this class is not intended to be used directly, use one of the subclasses instead.
- * @typeparam TResult Type of the object that will be returned by `validate()` method.
- * @typeparam TRequired If `true`, object will be required. If `false`, object will be optional.
+ * @typeParam TResult Type of the object that will be returned by `validate()` method.
+ * @typeParam TRequired If `true`, object will be required. If `false`, object will be optional.
  */
 export declare abstract class SchemaBuilder<TResult = any, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> {
     #private;
@@ -466,13 +478,13 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * consumes the spec — including tRPC, TanStack Form, React Hook Form, T3 Env,
      * Hono, Elysia, next-safe-action, and 50+ other tools.
      *
-     * Every `SchemaBuilder` subclass (all 13 builders) inherits this property
+     * Every `SchemaBuilder` subclass inherits this property
      * automatically — no additional setup required.
      *
      * **Shape of the returned object:**
      * - `version` — always `1` (Standard Schema spec version)
      * - `vendor` — `'@cleverbrush/schema'`
-     * - `validate(value)` — synchronous; wraps this builder's own `.validate()`
+     * - `validate(value)` — asynchronous; wraps this builder's `.validateAsync()`
      *   and converts its result to the Standard Schema `Result<Output>` format:
      *   - Success: `{ value: <validated output> }`
      *   - Failure: `{ issues: [{ message: string }, …] }`
@@ -526,6 +538,17 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * @param props arbitrary props object
      */
     protected abstract createFromProps(props: any): this;
+    /**
+     * Constructs an immutable derivative through the existing subclass hook.
+     * Shape, rule and extension changes detach from inherited component names
+     * by default. Only presence, nullability, annotations and type-only changes
+     * may preserve the canonical definition. Preserve chains collapse to their
+     * original target; an unnamed derivative never reconnects automatically.
+     * @param props - Complete introspection properties for the new builder.
+     * @param preserveReference - Whether only use-site metadata changed.
+     * @internal
+     */
+    protected derive(props: any, preserveReference?: boolean): this;
     /**
      * The string identifier of the schema type (e.g. `'string'`, `'number'`, `'object'`).
      */
@@ -693,6 +716,14 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
          * or `undefined` if none was set.
          */
         schemaName: string | undefined;
+        /**
+         * Canonical named definition retained by use-site modifiers.
+         * Exporters must compose local annotations/nullability around this
+         * target before resolving the derivative's inherited name.
+         * Structural and validation-rule derivatives have no target.
+         * @internal
+         */
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         /**
          * Whether a catch/fallback value has been set on this schema via `.catch()`.
          */
@@ -761,7 +792,10 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      *
      * When `.catch()` is set, {@link parse} and {@link parseAsync} will **never throw**.
      *
-     * @param value - the fallback value, or a factory function producing the fallback
+     * @param value - A value (or factory) compatible with the resolved output:
+     * optional schemas allow undefined; nullable schemas allow null.
+     * @remarks Legacy optional schemas also accept null at runtime, so
+     * catch(undefined) does not normalize null. Use an explicit preprocessor.
      *
      * @example
      * ```ts
@@ -790,7 +824,7 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * c.validate(42);        // { valid: true, object: 'anon' }  ← also fires
      * ```
      */
-    catch(value: TResult | (() => TResult)): this;
+    catch(value: ResolvedSchemaType<TResult, TRequired, TNullable> | (() => ResolvedSchemaType<TResult, TRequired, TNullable>)): this;
     /**
      * Removes the default value set by a previous call to `.default()`.
      */
@@ -845,6 +879,15 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * safe; how conflicts between different instances with the same name are
      * handled depends on the tool.
      *
+     * Ordinary presence, nullability, annotation and type-only modifiers retain
+     * this canonical definition for document exporters. Shape, validation-rule,
+     * default, fallback and extension changes discard the inherited name. Apply
+     * `schemaName` after those edits to give the derivative its own component.
+     * Calling this method always establishes a fresh definition, even on an alias.
+     *
+     * @param name - Component name for this independent schema definition.
+     * @returns A new named builder without an inherited canonical target.
+     *
      * @example
      * ```ts
      * import { object, string, number } from '@cleverbrush/schema';
@@ -899,9 +942,15 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      */
     required(errorMessage?: ValidationErrorMessageProvider): any;
     /**
-     * Adds a `preprocessor` to a preprocessors list
+     * Adds an immutable preprocessing step. It may return the resolved value,
+     * including undefined for optional schemas and null for nullable schemas.
+     * @param preprocessor - Existing value-to-value conversion, optionally async.
+     * @param options - Whether the callback can mutate its argument.
+     * @returns A new builder preserving the original schema.
+     * @remarks Legacy callback parameter typing is preserved for compatibility.
+     * Unknown external data still needs runtime validation.
      */
-    addPreprocessor(preprocessor: Preprocessor<TResult>, options?: {
+    addPreprocessor(preprocessor: (object: TResult) => ResolvedSchemaType<TResult, TRequired, TNullable> | Promise<ResolvedSchemaType<TResult, TRequired, TNullable>>, options?: {
         mutates?: boolean;
     }): this;
     /**

package/dist/builders/StringSchemaBuilder.d.ts

@@ -6,46 +6,52 @@ type StringSchemaBuilderCreateProps<T = string, R extends boolean = true> = Part
  * length, restricted to start with a certain value, restricted to end with
  * a certain value, restricted to match a certain regular expression.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link string | string()} function instead.
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string().equals('hello');
  * const result = schema.validate('hello');
  * // result.valid === true
  * // result.object === 'hello'
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string().equals('hello');
  * const result = schema.validate('world');
  * // result.valid === false
  * // result.errors[0].message === "is expected to be equal to 'hello'"
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string().minLength(5);
  * const result = schema.validate('hello');
  * // result.valid === true
  * // result.object === 'hello'
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string().minLength(5);
  * const result = schema.validate('hi');
  * // result.valid === false
  * // result.errors[0].message === 'is expected to have a length of at least 5'
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string().minLength(2).maxLength(5);
  * const result = schema.validate('yes');
  * // result.valid === true
  * // result.object === 'yes'
  * ```
  *
- * @example ```ts
+ * @example
+ * ```ts
  * const schema = string('no');
  * const result = schema.validate('yes');
  * // result.valid === false
@@ -56,6 +62,14 @@ type StringSchemaBuilderCreateProps<T = string, R extends boolean = true> = Part
  */
 export declare class StringSchemaBuilder<TResult = string, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'string',
+        TResult,
+        TRequired,
+        TNullable,
+        THasDefault
+    ];
     /**
      * @hidden
      */
@@ -136,6 +150,7 @@ export declare class StringSchemaBuilder<TResult = string, TRequired extends boo
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/StringSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-ORV2G6ZL.js";import"../chunk-REYZ7G7J.js";export{a as StringSchemaBuilder,b as string};
+import{a,b}from"../chunk-JH7VLA6C.js";import"../chunk-2BKBVVZ3.js";export{a as StringSchemaBuilder,b as string};
 //# sourceMappingURL=StringSchemaBuilder.js.map

package/dist/builders/TupleSchemaBuilder.d.ts

@@ -35,8 +35,8 @@ type TupleSchemaBuilderCreateProps<TElements extends readonly SchemaBuilder<any,
  * Use it when you need to validate function arguments, CSV rows, coordinate
  * pairs, structured event payloads, or any other fixed-structure array.
  *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
+ * **NOTE** this class is exported for type annotations and advanced use.
+ * Customize via extensions rather than subclassing. Avoid instantiating it
  * directly. Use {@link tuple | tuple()} function instead.
  *
  * @example
@@ -86,6 +86,17 @@ export declare class TupleSchemaBuilder<TElements extends readonly SchemaBuilder
     [K in keyof TElements]: InferType<TElements[K]>;
 } : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
+    /** Native type parameters for extension rebinding; never emitted at runtime. @internal */
+    readonly __cleverbrush_builder_type__: readonly [
+        'tuple',
+        TElements,
+        TRequired,
+        TNullable,
+        TExplicitType,
+        THasDefault,
+        TRestSchema,
+        TResult
+    ];
     /**
      * @hidden
      */
@@ -100,11 +111,11 @@ export declare class TupleSchemaBuilder<TElements extends readonly SchemaBuilder
      */
     clearHasType(): TupleSchemaBuilder<TElements, TRequired, TNullable, undefined, THasDefault, TExtensions, TRestSchema> & TExtensions;
     /**
-     * Performs synchronous validation of the schema over `object`. {@inheritDoc SchemaBuilder.validate}
+     * {@inheritDoc SchemaBuilder.validate}
      */
     validate(object: TResult, context?: ValidationContext): TupleSchemaValidationResult<TResult, TElements>;
     /**
-     * Performs asynchronous validation of the schema over `object`. {@inheritDoc SchemaBuilder.validateAsync}
+     * {@inheritDoc SchemaBuilder.validateAsync}
      */
     validateAsync(object: TResult, context?: ValidationContext): Promise<TupleSchemaValidationResult<TResult, TElements>>;
     /**
@@ -170,6 +181,7 @@ export declare class TupleSchemaBuilder<TElements extends readonly SchemaBuilder
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
         schemaName: string | undefined;
+        referenceTarget: SchemaBuilder<any, any, any, any, any> | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
         example: unknown;

package/dist/builders/TupleSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-G424M7GI.js";import"../chunk-REYZ7G7J.js";export{a as TupleSchemaBuilder,b as tuple};
+import{a,b}from"../chunk-VBPZRO7L.js";import"../chunk-2BKBVVZ3.js";export{a as TupleSchemaBuilder,b as tuple};
 //# sourceMappingURL=TupleSchemaBuilder.js.map