@cleverbrush/schema 2.0.0 → 3.0.1

package/dist/builders/FunctionSchemaBuilder.d.ts

@@ -1,14 +1,18 @@
-import { type BRAND, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+import { type BRAND, type InferType, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
 type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<FunctionSchemaBuilder<R>['introspect']>>;
+type InferParameters<TParams extends SchemaBuilder<any, any, any, any, any>[]> = {
+    [K in keyof TParams]: InferType<TParams[K]>;
+};
 /**
  * Schema builder for functions. Allows to define a schema for a function.
- * It can be: required or optional.
+ * It can be required or optional, and may carry typed parameter and return-type
+ * schemas so that the inferred TypeScript function signature is fully typed.
  *
  * **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
  * directly. Use {@link func | func()} function instead.
  *
- * @example
+ * @example Basic validation
  * ```ts
  * const schema = func();
  * const result = schema.validate(() => {});
@@ -16,7 +20,7 @@ type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<Return
  * // result.object === () => {}
  * ```
  *
- * @example
+ * @example Optional function schema
  * ```ts
  * const schema = func().optional();
  * const result = schema.validate(undefined);
@@ -24,23 +28,88 @@ type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<Return
  * // result.object === undefined
  * ```
  *
+ * @example Typed parameters and return type
+ * ```ts
+ * import { func, string, number, InferType } from '@cleverbrush/schema';
+ *
+ * const greet = func()
+ *     .addParameter(string())           // first param: string
+ *     .addParameter(number().optional()) // second param: number | undefined
+ *     .hasReturnType(string());          // return type: string
+ *
+ * type Greet = InferType<typeof greet>;
+ * // → (param0: string, param1: number | undefined) => string
+ *
+ * // Introspect at runtime
+ * const info = greet.introspect();
+ * // info.parameters  → [StringSchemaBuilder, NumberSchemaBuilder]
+ * // info.returnType  → StringSchemaBuilder
+ * ```
+ *
  * @see {@link func}
  */
-export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? (...args: any[]) => any : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TParameters extends SchemaBuilder<any, any, any, any, any>[] = [], TReturnTypeSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, TResult = TExplicitType extends undefined ? (...args: TParameters extends [] ? any[] : InferParameters<TParameters>) => TReturnTypeSchema extends SchemaBuilder<any, any, any, any, any> ? InferType<TReturnTypeSchema> : any : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
     /**
      * @hidden
      */
-    static create(props: FunctionSchemaBuilderCreateProps<any>): FunctionSchemaBuilder<true, false, undefined, false, {}, (...args: any[]) => any>;
+    static create(props: FunctionSchemaBuilderCreateProps<any>): FunctionSchemaBuilder<true, false, undefined, false, {}, [], undefined, (...args: any[]) => any>;
     protected constructor(props: FunctionSchemaBuilderCreateProps<TRequired>);
     /**
      * @hidden
      */
-    hasType<T>(_notUsed?: T): FunctionSchemaBuilder<true, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    hasType<T>(_notUsed?: T): FunctionSchemaBuilder<true, TNullable, T, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
-    clearHasType(): FunctionSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    clearHasType(): FunctionSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * Returns an object describing the current schema configuration.
+     *
+     * In addition to the base fields exposed by {@link SchemaBuilder.introspect},
+     * the following fields are included:
+     *
+     * - `parameters` — an array of {@link SchemaBuilder} instances accumulated via
+     *   {@link addParameter}. Each element describes one positional parameter of the
+     *   function in the order they were added.
+     * - `returnType` — the {@link SchemaBuilder} set via {@link hasReturnType}, or
+     *   `undefined` when no return-type schema has been configured.
+     *
+     * @example
+     * ```ts
+     * const schema = func()
+     *     .addParameter(string())
+     *     .addParameter(number())
+     *     .hasReturnType(boolean());
+     *
+     * const info = schema.introspect();
+     * // info.parameters.length === 2
+     * // info.returnType instanceof BooleanSchemaBuilder
+     * ```
+     */
+    introspect(): {
+        /** List of parameter schemas added via {@link addParameter}. */
+        parameters: SchemaBuilder<any, any, any, any, any>[];
+        /** Return type schema set via {@link hasReturnType}, or `undefined` if not set. */
+        returnType: SchemaBuilder<any, any, any, any, any> | undefined;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        schemaName: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
+    };
     /** {@inheritDoc SchemaBuilder.validate} */
     validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
     /** {@inheritDoc SchemaBuilder.validateAsync} */
@@ -61,44 +130,119 @@ export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TNu
     /**
      * @hidden
      */
-    required(errorMessage?: ValidationErrorMessageProvider): FunctionSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    required(errorMessage?: ValidationErrorMessageProvider): FunctionSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
-    optional(): FunctionSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    optional(): FunctionSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
-    default(value: TResult | (() => TResult)): FunctionSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    default(value: TResult | (() => TResult)): FunctionSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
-    clearDefault(): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    clearDefault(): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
     brand<TBrand extends string | symbol>(_name?: TBrand): FunctionSchemaBuilder<TRequired, TNullable, TResult & {
         readonly [K in BRAND]: TBrand;
-    }, THasDefault, TExtensions> & TExtensions;
+    }, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * Marks the inferred type as `Readonly<Function>`. Sets the
      * `isReadonly` introspection flag for tooling consistency.
      *
      * @see {@link SchemaBuilder.readonly}
      */
-    readonly(): FunctionSchemaBuilder<TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions> & TExtensions;
+    readonly(): FunctionSchemaBuilder<TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
     /**
      * @hidden
      */
-    nullable(): FunctionSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    nullable(): FunctionSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * Appends a positional parameter schema to the function schema.
+     *
+     * Each call extends the inferred function signature by one parameter.
+     * The full list of parameter schemas is available at runtime via
+     * `introspect().parameters`.
+     *
+     * Parameter order matches the call order — the first `addParameter()` call
+     * defines the type of the first argument, the second call defines the second
+     * argument, and so on.
+     *
+     * @param schema - The schema describing the parameter. Pass an optional schema
+     *   (e.g. `string().optional()`) to make the corresponding argument optional.
+     *
+     * @example
+     * ```ts
+     * const fn = func()
+     *     .addParameter(string())          // (a: string, ...) => any
+     *     .addParameter(number().optional()) // (..., b?: number) => any
+     *     .addParameter(boolean());        // (..., c: boolean) => any
+     *
+     * type Fn = InferType<typeof fn>;
+     * // → (a: string, b: number | undefined, c: boolean) => any
+     * ```
+     */
+    addParameter<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, THasDefault, TExtensions, [
+        ...TParameters,
+        TSchema
+    ], TReturnTypeSchema> & TExtensions;
+    /**
+     * Sets the return type schema for the function schema.
+     *
+     * Replaces any previously set return type. The inferred function signature
+     * gains a concrete return type instead of `any`. The schema is accessible at
+     * runtime via `introspect().returnType`.
+     *
+     * @param schema - The schema describing the return type of the function.
+     *
+     * @example
+     * ```ts
+     * const fn = func()
+     *     .addParameter(string())
+     *     .hasReturnType(number());
+     *
+     * type Fn = InferType<typeof fn>;
+     * // → (param0: string) => number
+     *
+     * fn.introspect().returnType; // NumberSchemaBuilder
+     * ```
+     */
+    hasReturnType<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TSchema> & TExtensions;
     /**
      * @hidden
      */
-    notNullable(): FunctionSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    notNullable(): FunctionSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
 }
 /**
- * Creates a `function` schema.
- * @returns {@link FunctionSchemaBuilder}
+ * Creates a `function` schema that validates the value is a JavaScript function.
+ *
+ * The returned builder is immutable and fully chainable. Use
+ * {@link FunctionSchemaBuilder.addParameter} to annotate the expected parameter
+ * types and {@link FunctionSchemaBuilder.hasReturnType} to annotate the return
+ * type — the inferred TypeScript function signature is updated automatically.
+ *
+ * @returns A new {@link FunctionSchemaBuilder} with `isRequired` set to `true`.
+ *
+ * @example
+ * ```ts
+ * import { func, string, number, InferType } from '@cleverbrush/schema';
+ *
+ * const schema = func()
+ *     .addParameter(string())
+ *     .addParameter(number().optional())
+ *     .hasReturnType(string());
+ *
+ * type Fn = InferType<typeof schema>;
+ * // → (param0: string, param1?: number) => string
+ *
+ * schema.validate(() => 'hello');  // { valid: true }
+ * schema.validate('not a fn');     // { valid: false }
+ * ```
+ *
+ * @see {@link FunctionSchemaBuilder}
  */
 export declare const func: () => FunctionSchemaBuilder<true>;
 export {};

package/dist/builders/FunctionSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-EUQ5AE3H.js";import"../chunk-CTP4RHDG.js";export{a as FunctionSchemaBuilder,b as func};
+import{a,b}from"../chunk-ZC6YBKCP.js";import"../chunk-3JMDGYDT.js";export{a as FunctionSchemaBuilder,b as func};
 //# sourceMappingURL=FunctionSchemaBuilder.js.map

package/dist/builders/GenericSchemaBuilder.d.ts

@@ -0,0 +1,294 @@
+import { type BRAND, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type GenericSchemaBuilderCreateProps<TRequired extends boolean = true> = Partial<ReturnType<GenericSchemaBuilder<any, TRequired>['introspect']>>;
+/**
+ * Schema builder that wraps a generic template function, enabling reusable
+ * parameterized schemas. Call {@link GenericSchemaBuilder.apply | `.apply()`}
+ * with concrete schema arguments to obtain a fully typed concrete schema
+ * 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
+ * directly. Use {@link generic | generic()} function instead.
+ *
+ * @example Single type parameter
+ * ```ts
+ * import { generic, object, array, number, string, InferType } from '@cleverbrush/schema';
+ *
+ * const PaginatedList = generic(
+ *   <T extends SchemaBuilder<any, any, any, any, any>>(itemSchema: T) =>
+ *     object({
+ *       items: array(itemSchema),
+ *       total: number(),
+ *       page:  number(),
+ *     })
+ * );
+ *
+ * const userSchema = object({ name: string(), age: number() });
+ * const PaginatedUsers = PaginatedList.apply(userSchema);
+ *
+ * type PaginatedUsersType = InferType<typeof PaginatedUsers>;
+ * // → { items: { name: string; age: number }[]; total: number; page: number }
+ * ```
+ *
+ * @example Multiple type parameters
+ * ```ts
+ * const Result = generic(
+ *   <T extends SchemaBuilder<any, any, any, any, any>,
+ *    E extends SchemaBuilder<any, any, any, any, any>>(
+ *     valueSchema: T,
+ *     errorSchema: E
+ *   ) =>
+ *     object({
+ *       ok:    boolean(),
+ *       value: valueSchema.optional(),
+ *       error: errorSchema.optional(),
+ *     })
+ * );
+ *
+ * const StringResult = Result.apply(string(), number());
+ * // InferType → { ok: boolean; value?: string; error?: number }
+ * ```
+ *
+ * @example With default arguments (enables direct `.validate()` on the template)
+ * ```ts
+ * const AnyList = generic(
+ *   [any()],   // default args — one per template parameter
+ *   <T extends SchemaBuilder<any, any, any, any, any>>(itemSchema: T) =>
+ *     object({ items: array(itemSchema), total: number() })
+ * );
+ *
+ * // Validate directly using defaults:
+ * AnyList.validate({ items: [1, 'two', true], total: 3 }); // valid
+ *
+ * // Or apply concrete schemas first:
+ * AnyList.apply(string()).validate({ items: ['a', 'b'], total: 2 }); // valid
+ * ```
+ *
+ * @see {@link generic}
+ *
+ * @typeParam TFn - The generic template function type. Its return type
+ *   determines `TResult` (the validated value type) when no explicit type
+ *   override has been applied via `.hasType<T>()`.
+ * @typeParam TRequired - `true` when the schema is required (default),
+ *   `false` after calling `.optional()`. Governs whether `undefined` is a
+ *   valid value.
+ * @typeParam TNullable - `true` after calling `.nullable()`. Governs whether
+ *   `null` is a valid value.
+ * @typeParam TExplicitType - Type override set via `.hasType<T>()`. When
+ *   `undefined` (the default), `TResult` is derived from `TFn`'s return type.
+ * @typeParam THasDefault - `true` after calling `.default(value)`. Governs
+ *   whether `InferType` emits `T` instead of `T | undefined` for optional
+ *   schemas with a default.
+ * @typeParam TExtensions - Object type carrying extension methods added via
+ *   `withExtensions()`. Defaults to `{}`.
+ * @typeParam TResult - The inferred result type: `TExplicitType` when set,
+ *   otherwise the value type inferred from `ReturnType<TFn>`.
+ */
+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;
+    /**
+     * Applies the template function with concrete schema arguments, returning
+     * a fully typed concrete schema builder. TypeScript infers the result type
+     * from the template function's own generic signature.
+     *
+     * The returned builder is independent of this `GenericSchemaBuilder` and
+     * can be used like any other schema: `.validate()`, `.optional()`, etc.
+     *
+     * @example
+     * ```ts
+     * const Wrapper = generic(
+     *   <T extends SchemaBuilder<any, any, any, any, any>>(schema: T) =>
+     *     object({ data: schema })
+     * );
+     *
+     * const s = Wrapper.apply(string());
+     * // InferType<typeof s> → { data: string }
+     * s.validate({ data: 'hello' }); // { valid: true }
+     * ```
+     */
+    readonly apply: TFn;
+    /**
+     * @hidden
+     */
+    static create(props: GenericSchemaBuilderCreateProps<any>): GenericSchemaBuilder<(...args: any[]) => SchemaBuilder<any, any, any, any, any>, true, false, undefined, false, {}, any>;
+    protected constructor(props: GenericSchemaBuilderCreateProps<TRequired>);
+    /**
+     * Returns an object describing the current schema configuration.
+     *
+     * In addition to the base fields exposed by {@link SchemaBuilder.introspect},
+     * the following fields are included:
+     *
+     * - `templateFn` — the template function passed to {@link generic}.
+     * - `defaults` — the default argument list passed to the two-argument
+     *   form of {@link generic}, or `undefined` when no defaults were provided.
+     *
+     * @example
+     * ```ts
+     * const schema = generic([string()], <T>(s: T) => object({ data: s }));
+     *
+     * const info = schema.introspect();
+     * // info.type         → 'generic'
+     * // info.templateFn   → [Function]
+     * // info.defaults     → [StringSchemaBuilder]
+     * ```
+     */
+    introspect(): {
+        /** Template function passed to {@link generic}. */
+        templateFn: ((...args: any[]) => SchemaBuilder<any, any, any, any, any>) | undefined;
+        /** Default positional arguments for the template function, or `undefined`. */
+        defaults: readonly any[] | undefined;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        schemaName: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
+    };
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation of the schema over `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Performs async validation of the schema over `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected createFromProps<TReq extends boolean>(props: GenericSchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @hidden
+     */
+    hasType<T>(_notUsed?: T): GenericSchemaBuilder<TFn, true, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearHasType(): GenericSchemaBuilder<TFn, TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): GenericSchemaBuilder<TFn, true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): GenericSchemaBuilder<TFn, false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): GenericSchemaBuilder<TFn, TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): GenericSchemaBuilder<TFn, TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): GenericSchemaBuilder<TFn, true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): GenericSchemaBuilder<TFn, TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): GenericSchemaBuilder<TFn, TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    readonly(): GenericSchemaBuilder<TFn, TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Creates a generic schema template — a reusable, parameterized schema factory
+ * whose TypeScript type is inferred from the template function's generic
+ * signature.
+ *
+ * Call {@link GenericSchemaBuilder.apply | `.apply()`} on the returned builder
+ * to instantiate the template with concrete schema arguments and receive a
+ * fully typed concrete schema.
+ *
+ * There are two overloads:
+ *
+ * 1. **`generic(templateFn)`** — Provide only the template function. The
+ *    template must be called via `.apply()` before validation.
+ * 2. **`generic(defaults, templateFn)`** — Provide positional default arguments
+ *    followed by the template function. The template can be validated directly
+ *    using those defaults (without calling `.apply()` first).
+ *
+ * @param templateFn - A (generic) function that accepts schema arguments and
+ *   returns a concrete schema. TypeScript infers the result type from this
+ *   function's generic signature when `.apply()` is called.
+ *
+ * @returns A new {@link GenericSchemaBuilder} with `isRequired` set to `true`.
+ *
+ * @example Single type parameter
+ * ```ts
+ * import { generic, object, array, number, string, any, InferType } from '@cleverbrush/schema';
+ *
+ * const PaginatedList = generic(
+ *   <T extends SchemaBuilder<any, any, any, any, any>>(itemSchema: T) =>
+ *     object({ items: array(itemSchema), total: number(), page: number() })
+ * );
+ *
+ * const UserList = PaginatedList.apply(object({ name: string() }));
+ * type UserListType = InferType<typeof UserList>;
+ * // → { items: { name: string }[]; total: number; page: number }
+ *
+ * UserList.validate({ items: [{ name: 'Alice' }], total: 1, page: 1 }); // valid
+ * ```
+ *
+ * @example Multiple type parameters
+ * ```ts
+ * const Result = generic(
+ *   <T extends SchemaBuilder<any, any, any, any, any>,
+ *    E extends SchemaBuilder<any, any, any, any, any>>(
+ *     valueSchema: T,
+ *     errorSchema: E
+ *   ) =>
+ *     union(
+ *       object({ ok: boolean().equalsTo(true),  value: valueSchema }),
+ *       object({ ok: boolean().equalsTo(false), error: errorSchema })
+ *     )
+ * );
+ *
+ * const StringResult = Result.apply(string(), number());
+ * ```
+ *
+ * @example With defaults (enables direct validation on the template)
+ * ```ts
+ * const AnyList = generic(
+ *   [any()],   // default args — positional, one per template parameter
+ *   <T extends SchemaBuilder<any, any, any, any, any>>(itemSchema: T) =>
+ *     object({ items: array(itemSchema), total: number() })
+ * );
+ *
+ * // Validate directly — uses the default any() schema:
+ * AnyList.validate({ items: [1, 'two'], total: 2 }); // valid
+ *
+ * // Or apply concrete schemas first:
+ * AnyList.apply(string()).validate({ items: ['x'], total: 1 }); // valid
+ * ```
+ *
+ * @see {@link GenericSchemaBuilder}
+ */
+export declare function generic<TFn extends (...args: any[]) => SchemaBuilder<any, any, any, any, any>>(templateFn: TFn): GenericSchemaBuilder<TFn, true, false, undefined, false, {}>;
+export declare function generic<TFn extends (...args: any[]) => SchemaBuilder<any, any, any, any, any>>(defaults: readonly any[], templateFn: TFn): GenericSchemaBuilder<TFn, true, false, undefined, false, {}>;
+export {};

package/dist/builders/LazySchemaBuilder.d.ts

@@ -68,8 +68,10 @@ export declare class LazySchemaBuilder<TResult = any, TRequired extends boolean
         hasDefault: boolean;
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
     };
     /** {@inheritDoc SchemaBuilder.validate} */
     validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;

package/dist/builders/NumberSchemaBuilder.d.ts

@@ -117,8 +117,10 @@ export declare class NumberSchemaBuilder<TResult = number, TRequired extends boo
         hasDefault: boolean;
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
     };
     /**
      * @inheritdoc
@@ -228,6 +230,20 @@ export declare class NumberSchemaBuilder<TResult = number, TRequired extends boo
      * Consider `Infinity` as valid.
      */
     canBeInfinite(): NumberSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Adds a preprocessor that coerces a string value to a number
+     * using `Number(value)`. Useful when the input is captured from
+     * a string source (e.g. a parse-string schema, URL parameter,
+     * or form input).
+     *
+     * @example ```ts
+     * const schema = number().coerce();
+     * const result = schema.validate('42');
+     * // result.valid === true
+     * // result.object === 42
+     * ```
+     */
+    coerce(): NumberSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Restrict number to be at least `minValue`.
      */

package/dist/builders/NumberSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-KESLT5EE.js";import"../chunk-CTP4RHDG.js";export{a as NumberSchemaBuilder,b as number};
+import{a,b}from"../chunk-BUEVZ3KA.js";import"../chunk-3JMDGYDT.js";export{a as NumberSchemaBuilder,b as number};
 //# sourceMappingURL=NumberSchemaBuilder.js.map