@cleverbrush/schema 1.1.11 → 3.0.0

package/dist/builders/ObjectSchemaBuilder.d.ts

@@ -1,29 +1,145 @@
-import { InferType, SchemaBuilder, ValidationContext, ValidationResult } from './SchemaBuilder.js';
+import { PropertyValidationResult } from './PropertyValidationResult.js';
+import { type BRAND, type InferType, type NestedValidationResult, type PreValidationResult, type PropertyDescriptor, type PropertyDescriptorTree, SchemaBuilder, SYMBOL_HAS_PROPERTIES, type ValidationContext, type ValidationError, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+/**
+ * A callback function to select properties from the schema.
+ * Normally it's provided by the user to select property descriptors
+ * from the schema for the further usage. e.g. to select source and destination
+ * properties for object mappings
+ */
+export type SchemaPropertySelector<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TPropertySchema extends SchemaBuilder<any, any, any, any, any>, TAssignableTo = any, TParentPropertyDescriptor = undefined> = (l: PropertyDescriptorTree<TSchema, TSchema, TAssignableTo>) => PropertyDescriptor<TSchema, TPropertySchema, TParentPropertyDescriptor>;
 type ObjectSchemaBuilderProps<T extends Record<string, SchemaBuilder> = {}, TRequired extends boolean = true> = ReturnType<ObjectSchemaBuilder<T, TRequired>['introspect']>;
 type ObjectSchemaBuilderCreateProps<T extends Record<string, SchemaBuilder> = {}, TRequired extends boolean = true> = Partial<ObjectSchemaBuilderProps<T, TRequired>>;
 type Id<T> = T extends infer U ? {
     [K in keyof U]: U[K];
 } : never;
-export type RespectPropsOptionality<T extends Record<string, SchemaBuilder<any, any>>> = {
+/**
+ * Extracts the positional argument types from a schema whose inferred type is a
+ * function.  When the branded `InferType<T>` resolves to a function type the
+ * parameter tuple is extracted; otherwise `any[]` is used as a safe fallback.
+ *
+ * @example
+ * ```ts
+ * type Args = ConstructorParams<typeof func().addParameter(string()).addParameter(number())>;
+ * // → [string, number]
+ * ```
+ */
+type ConstructorParams<T extends SchemaBuilder<any, any, any, any, any>> = InferType<T> extends (...args: infer A) => any ? A : any[];
+/**
+ * Converts a tuple of `FunctionSchemaBuilder`s into an intersection of
+ * `new (...args) => TInstance` call signatures, producing overloaded
+ * construct signatures in the inferred type.
+ *
+ * The recursion peels schemas off the front of `TSchemas` one at a time,
+ * each contributing one construct overload to the intersection.
+ *
+ * @example
+ * ```ts
+ * type Sigs = ConstructorSignatures<
+ *   [typeof func().addParameter(string()), typeof func().addParameter(number())],
+ *   { name: string }
+ * >;
+ * // → { new (p0: string): { name: string } }
+ * //   & { new (p0: number): { name: string } }
+ * ```
+ */
+type ConstructorSignatures<TSchemas extends SchemaBuilder<any, any, any, any, any>[], TInstance> = TSchemas extends [
+    infer THead extends SchemaBuilder<any, any, any, any, any>,
+    ...infer TTail extends SchemaBuilder<any, any, any, any, any>[]
+] ? {
+    new (...args: ConstructorParams<THead>): TInstance;
+} & ConstructorSignatures<TTail, TInstance> : unknown;
+/**
+ * Wraps `TInstance` with constructor overload signatures derived from
+ * `TSchemas`.  When the tuple is empty the type is returned unchanged
+ * (no-op); otherwise the result is an intersection of all construct
+ * signatures with `TInstance`.
+ *
+ * This is the type projected onto `InferType<ObjectSchemaBuilder>` when one
+ * or more constructors have been registered via `.addConstructor()`.
+ *
+ * @example
+ * ```ts
+ * // No constructors — passthrough
+ * type A = WithConstructors<[], { name: string }>;
+ * // → { name: string }
+ *
+ * // One constructor
+ * type B = WithConstructors<[typeof func().addParameter(string())], { name: string }>;
+ * // → { new (p0: string): { name: string } } & { name: string }
+ *
+ * // Two constructors → overloaded construct signatures
+ * type C = WithConstructors<
+ *   [typeof func().addParameter(string()), typeof func().addParameter(number())],
+ *   { name: string }
+ * >;
+ * // → { new (p0: string): { name: string } }
+ * //   & { new (p0: number): { name: string } }
+ * //   & { name: string }
+ * ```
+ */
+type WithConstructors<TSchemas extends SchemaBuilder<any, any, any, any, any>[], TInstance> = TSchemas extends [] ? TInstance : ConstructorSignatures<TSchemas, TInstance> & TInstance;
+export type RespectPropsOptionality<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = {
     [K in RequiredProps<T>]: InferType<T[K]>;
 } & {
     [K in NotRequiredProps<T>]?: InferType<T[K]>;
 };
-type MakeChildrenRequired<T extends Record<string, SchemaBuilder<any, any>>> = {
+type RespectPropsOptionalityForInput<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = {
+    [K in RequiredInputProps<T>]: InferType<T[K]>;
+} & {
+    [K in NotRequiredInputProps<T>]?: InferType<T[K]>;
+};
+type MakeChildrenRequired<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = {
     [K in keyof T]: ReturnType<T[K]['required']>;
 };
-type MakeChildrenOptional<T extends Record<string, SchemaBuilder<any, any>>> = {
+type MakeChildrenOptional<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = {
     [K in keyof T]: ReturnType<T[K]['optional']>;
 };
-type MakeChildOptional<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T> = {
+/**
+ * Recursively maps each property to its optional form, descending into
+ * nested `ObjectSchemaBuilder` schemas.  All other schema types (arrays,
+ * unions, primitives) are only made optional at the top level.
+ */
+type DeepMakeChildrenOptional<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = {
+    [K in keyof T]: T[K] extends ObjectSchemaBuilder<infer P extends Record<string, SchemaBuilder<any, any, any, any, any>>, any, any, any, any, any, any> ? ReturnType<ReturnType<T[K]['deepPartial']>['optional']> : ReturnType<T[K]['optional']>;
+};
+type MakeChildOptional<T extends Record<any, SchemaBuilder<any, any, any, any, any>>, TProp extends keyof T> = {
     [K in keyof T]: K extends TProp ? ReturnType<T[K]['optional']> : T[K];
 };
-type MakeChildRequired<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T> = {
+type MakeChildRequired<T extends Record<any, SchemaBuilder<any, any, any, any, any>>, TProp extends keyof T> = {
     [K in keyof T]: K extends TProp ? ReturnType<T[K]['required']> : T[K];
 };
-type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T, TSchema extends SchemaBuilder<any, any>> = {
+type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any, any, any, any>>, TProp extends keyof T, TSchema extends SchemaBuilder<any, any, any, any, any>> = {
     [K in keyof T]: K extends TProp ? TSchema : T[K];
 };
+export type ObjectSchemaValidationResult<T, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any> = TRootSchema> = Omit<ValidationResult<T>, 'errors'> & {
+    /**
+     * A flat list of validation errors.
+     *
+     * @deprecated Use {@link ObjectSchemaValidationResult.getErrorsFor | getErrorsFor()} instead for
+     * per-property error inspection with type-safe property selectors. The `errors` array on
+     * `ObjectSchemaBuilder` validation results will be removed in a future major version.
+     */
+    errors?: ValidationError[];
+    /**
+     * Returns a nested validation error for the property selected by the `selector` function.
+     * 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.
+     *
+     * @param selector a callback function to select property from the schema.
+     */
+    getErrorsFor<TPropertySchema, TParentPropertyDescriptor>(selector?: (properties: PropertyDescriptorTree<TSchema, TRootSchema>) => PropertyDescriptor<TRootSchema, TPropertySchema, TParentPropertyDescriptor>): TPropertySchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any> ? PropertyValidationResult<TPropertySchema, TRootSchema, TParentPropertyDescriptor> : NestedValidationResult<TPropertySchema, TRootSchema, TParentPropertyDescriptor>;
+    /**
+     * Returns a list of all property validation results that have direct
+     * validation errors. Each entry exposes `.descriptor` (with
+     * `.toJsonPointer()` for the property's path) and `.errors`.
+     *
+     * This is useful for collecting all errors with their full JSON Pointer
+     * paths, e.g. for building RFC 9457 Problem Details responses.
+     */
+    getInvalidProperties(): ReadonlyArray<NestedValidationResult<any, TRootSchema, any>>;
+};
 /**
  * Object schema builder class. Similar to the `object` type
  * in JS. Allows to define a schema for `object` value.
@@ -45,7 +161,7 @@ type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp exte
  *    age: number()
  * });
  *
- * const result = await schema.validate({
+ * const result = schema.validate({
  *   name: 'John',
  *   age: 30
  * });
@@ -61,7 +177,7 @@ type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp exte
  *   age: number().optional()
  * });
  *
- * const result = await schema.validate({
+ * const result = schema.validate({
  *  name: 'John'
  * });
  * // result.valid === true
@@ -74,12 +190,13 @@ type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp exte
  *  name: string(),
  *  age: number();
  * });
- * const result = await schema.validate({
+ * const result = schema.validate({
  *  name: 'John'
  * });
  *
  * // result.valid === false
- * // result.errors[0].message === "is expected to have property 'age'"
+ * // result.errors is deprecated — use result.getErrorsFor() instead
+ * // result.getErrorsFor((p) => p.age).errors // ["is expected to have property 'age'"]
  * ```
  *
  * @example
@@ -91,7 +208,7 @@ type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp exte
  *     country: string()
  *   })
  * });
- * const result = await schema.validate({
+ * const result = schema.validate({
  * name: 'John',
  * address: {
  *    city: 'New York',
@@ -109,11 +226,16 @@ type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp exte
  * ```
  * @see {@link object}
  */
-export declare class ObjectSchemaBuilder<TProperties extends Record<string, SchemaBuilder<any, any>> = {}, TRequired extends boolean = true, TExplicitType = undefined> extends SchemaBuilder<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType, TRequired> {
+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;
-    static create<P extends Record<string, SchemaBuilder>, R extends boolean>(props: ObjectSchemaBuilderCreateProps<P, R>): ObjectSchemaBuilder<{}, true, undefined>;
+    /** Marks this builder as having sub-properties for descriptor tree recursion. */
+    readonly [SYMBOL_HAS_PROPERTIES] = true;
+    /**
+     * @hidden
+     */
+    static create<P extends Record<string, SchemaBuilder>, R extends boolean>(props: ObjectSchemaBuilderCreateProps<P, R>): ObjectSchemaBuilder<{}, true, false, undefined, false, {}, []>;
     protected createFromProps<T extends Record<string, SchemaBuilder>, R extends boolean = true>(props: ObjectSchemaBuilderCreateProps<T, R>): this;
-    private constructor();
+    protected constructor(props: ObjectSchemaBuilderCreateProps);
     introspect(): {
         /**
          * Properties defined in schema
@@ -126,51 +248,264 @@ export declare class ObjectSchemaBuilder<TProperties extends Record<string, Sche
          * Set to `false` by default
          */
         acceptUnknownProps: boolean;
+        /**
+         * The list of constructor schemas registered via `.addConstructor()`.
+         * Each element is a `FunctionSchemaBuilder` whose inferred function
+         * type provides one overloaded construct signature in `InferType`.
+         * Empty array when no constructors have been added.
+         */
+        constructorSchemas: TConstructorSchemas;
         type: string;
         isRequired: boolean;
-        preprocessors: readonly import("./SchemaBuilder.js").Preprocessor<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>[];
-        validators: readonly import("./SchemaBuilder.js").Validator<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>[];
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: (undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | (() => undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | undefined;
+        description: string | undefined;
+        schemaName: string | undefined;
+        hasCatch: boolean;
+        catchValue: (undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | (() => undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) | undefined;
+        example: unknown;
     };
     /**
      * @hidden
      */
-    required(): ObjectSchemaBuilder<TProperties, true, TExplicitType>;
+    required(errorMessage?: ValidationErrorMessageProvider): ObjectSchemaBuilder<TProperties, true, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): ObjectSchemaBuilder<TProperties, false, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: (undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | (() => undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType)): ObjectSchemaBuilder<TProperties, true, TNullable, TExplicitType, true, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * @hidden
      */
-    optional(): ObjectSchemaBuilder<TProperties, false, TExplicitType>;
+    clearDefault(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, false, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): ObjectSchemaBuilder<TProperties, TRequired, TNullable, (undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<T>` — all top-level properties
+     * become `readonly` at the type level. Validation behaviour is unchanged.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, Readonly<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    protected preValidateSync(object: any, context?: ValidationContext<this>): PreValidationResult<InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>>, {
+        validatedObject: any;
+    }>;
+    protected preValidateAsync(object: any, context?: ValidationContext<this>): Promise<PreValidationResult<InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>>, {
+        validatedObject: any;
+    }>>;
+    /**
+     * Adds a `validator` to validators list.
+     *
+     * Object-level validators can return errors with a `property` selector
+     * to route the error to a specific property, making it visible via
+     * `getErrorsFor()`.
+     *
+     * ```ts
+     * schema.addValidator((value) => ({
+     *     valid: false,
+     *     errors: [{
+     *         message: 'Passwords do not match',
+     *         property: (t) => t.confirmPassword
+     *     }]
+     * }));
+     * ```
+     *
+     * The `property` selector uses the same `PropertyDescriptorTree`
+     * as `getErrorsFor()` and react-form's `forProperty`.
+     */
+    addValidator(validator: (object: undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, RespectPropsOptionality<TProperties>> : TExplicitType) => {
+        valid: boolean;
+        errors?: Array<{
+            message: string;
+            property?: (properties: PropertyDescriptorTree<ObjectSchemaBuilder<TProperties>>) => PropertyDescriptor<any, any, any>;
+        }>;
+    } | Promise<{
+        valid: boolean;
+        errors?: Array<{
+            message: string;
+            property?: (properties: PropertyDescriptorTree<ObjectSchemaBuilder<TProperties>>) => PropertyDescriptor<any, any, any>;
+        }>;
+    }>, options?: {
+        mutates?: boolean;
+    }): this;
+    /**
+     * Performs synchronous validation of object schema over the `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     *
+     * The returned result includes a `getErrorsFor()` method for type-safe,
+     * per-property error inspection.
+     *
+     * @param object The object to validate against this schema.
+     * @param context Optional `ValidationContext` settings.
+     */
+    validate(object: undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionalityForInput<TProperties>> : TExplicitType, TRequired>> : TExplicitType, context?: ValidationContext<this>): ObjectSchemaValidationResult<undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>> : TExplicitType, this>;
     /**
-     * Performs validion of object schema over the `object`.
+     * @param object The object to validate against this schema.
      * @param context Optional `ValidationContext` settings.
      */
-    validate(object: undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType, context?: ValidationContext): Promise<ValidationResult<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>>;
+    validateAsync(object: undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionalityForInput<TProperties>> : TExplicitType, TRequired>> : TExplicitType, context?: ValidationContext<this>): Promise<ObjectSchemaValidationResult<undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>> : TExplicitType, this>>;
+    /**
+     * Performs synchronous validation of object schema over the `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     *
+     * The returned result includes a `getErrorsFor()` method for type-safe,
+     * per-property error inspection.
+     *
+     * @param object The object to validate against this schema.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionalityForInput<TProperties>> : TExplicitType, TRequired>> : TExplicitType, context?: ValidationContext<this>): ObjectSchemaValidationResult<undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>> : TExplicitType, this>;
+    /**
+     * Performs async validation of object schema over the `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     *
+     * @param object The object to validate against this schema.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validateAsync(object: undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionalityForInput<TProperties>> : TExplicitType, TRequired>> : TExplicitType, context?: ValidationContext<this>): Promise<ObjectSchemaValidationResult<undefined extends TExplicitType ? InferType<SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType, TRequired>> : TExplicitType, this>>;
     /**
      * Fields not defined in `properties` will not be validated
      * and will be passed through the validation.
      */
-    acceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>;
+    acceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Fields not defined in `properties` will be considered
      * as schema violation. This is the default behavior.
      */
-    notAcceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>;
+    notAcceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
-     * @hidden
+     * @inheritdoc
      */
-    hasType<T>(notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, T>;
+    hasType<T>(_notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, TNullable, T, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
-     * @hidden
+     * @inheritdoc
+     */
+    clearHasType(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, undefined, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * Appends a constructor overload to the object schema.
+     *
+     * Each call extends the set of construct signatures on the inferred type by
+     * one overload.  The accumulated argument lists are taken from the
+     * `FunctionSchemaBuilder` passed in — specifically from the positional
+     * parameter schemas registered via `.addParameter()`.
+     *
+     * At **runtime** the schema continues to validate plain objects; the
+     * constructor information is purely a TypeScript-level annotation and is
+     * stored in `introspect().constructorSchemas` for tooling use.
+     *
+     * Multiple calls are supported and produce **overloaded** construct
+     * signatures in the inferred type, modelling a class that exposes several
+     * constructor overloads.
+     *
+     * @param schema - A `FunctionSchemaBuilder` describing one constructor
+     *   overload.  Use `.addParameter()` on the function schema to declare the
+     *   parameter types.  The return type, if set via `.hasReturnType()`, is
+     *   ignored — the return type of a constructor is always the instance type
+     *   derived from the object schema's properties.
+     *
+     * @returns A new `ObjectSchemaBuilder` whose `TConstructorSchemas` tuple has
+     *   been extended by `schema`, updating `InferType` to include the new
+     *   construct signature.
+     *
+     * @example
+     * ```ts
+     * import { object, string, number, func, InferType } from '@cleverbrush/schema';
+     *
+     * // Single constructor
+     * const PersonSchema = object({ name: string(), age: number() })
+     *     .addConstructor(
+     *         func().addParameter(string()).addParameter(number())
+     *     );
+     *
+     * type Person = InferType<typeof PersonSchema>;
+     * // → { new (p0: string, p1: number): { name: string; age: number } }
+     * //   & { name: string; age: number }
+     * ```
+     *
+     * @example
+     * ```ts
+     * import { object, string, number, func, InferType } from '@cleverbrush/schema';
+     *
+     * // Multiple constructors via chained calls → overloaded signatures
+     * const PointSchema = object({ x: number(), y: number() })
+     *     .addConstructor(func())                                     // no-arg ctor
+     *     .addConstructor(func().addParameter(number()).addParameter(number())); // (x, y) ctor
+     *
+     * type Point = InferType<typeof PointSchema>;
+     * // → { new (): { x: number; y: number } }
+     * //   & { new (p0: number, p1: number): { x: number; y: number } }
+     * //   & { x: number; y: number }
+     *
+     * // Validation still operates on plain objects — the constructor type is
+     * // a compile-time annotation only.
+     * const result = PointSchema.validate({ x: 1, y: 2 });
+     * // result.valid === true
+     *
+     * // Introspect the registered constructor schemas at runtime:
+     * const info = PointSchema.introspect();
+     * // info.constructorSchemas.length === 2
+     * ```
+     */
+    addConstructor<TFunc extends SchemaBuilder<any, any, any, any, any>>(schema: TFunc): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, [
+        ...TConstructorSchemas,
+        TFunc
+    ]> & TExtensions;
+    /**
+     * Removes all constructor overloads previously registered via
+     * `.addConstructor()`, resetting the `TConstructorSchemas` tuple to `[]`.
+     *
+     * After calling this method `InferType` reverts to the plain object type
+     * derived from the schema's properties — no construct signatures are
+     * included.
+     *
+     * `introspect().constructorSchemas` will return an empty array.
+     *
+     * @returns A new `ObjectSchemaBuilder` with `TConstructorSchemas = []`.
+     *
+     * @example
+     * ```ts
+     * import { object, string, func, InferType } from '@cleverbrush/schema';
+     *
+     * const WithCtor = object({ name: string() })
+     *     .addConstructor(func().addParameter(string()));
+     *
+     * type WithCtorType = InferType<typeof WithCtor>;
+     * // → { new (p0: string): { name: string } } & { name: string }
+     *
+     * const Plain = WithCtor.clearConstructors();
+     *
+     * type PlainType = InferType<typeof Plain>;
+     * // → { name: string }
+     *
+     * Plain.introspect().constructorSchemas; // []
+     * ```
      */
-    clearHasType(): ObjectSchemaBuilder<TProperties, TRequired>;
+    clearConstructors(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, [
+    ]> & TExtensions;
     /**
      * Adds a new property to the object schema. The new property
      * will be validated according to the provided schema.
      * @param propName name of the new property
      * @param schema schema builder of the new property
      */
-    addProp<TType extends SchemaBuilder<any, any>, TName extends string>(propName: TName, schema: TType): ObjectSchemaBuilder<TProperties & {
+    addProp<TType extends SchemaBuilder<any, any, any, any, any>, TName extends string>(propName: TName, schema: TType): ObjectSchemaBuilder<TProperties & {
         [k in TName]: TType;
-    }, TRequired, TExplicitType>;
+    }, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * @hidden
      * @deprecated this is for internal use, do not use if you are
@@ -185,82 +520,141 @@ export declare class ObjectSchemaBuilder<TProperties extends Record<string, Sche
      * comments were lost. Hopefully it will be fixed in the future by Typescript team or somebody will
      * find a workaround/fix and create a pull request.
      */
-    optimize(): SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType>;
+    optimize(): SchemaBuilder<undefined extends TExplicitType ? WithConstructors<TConstructorSchemas, Id<RespectPropsOptionality<TProperties>>> : TExplicitType, TRequired, TNullable, THasDefault, TExtensions>;
     /**
      * Adds new properties to the object schema. The same as `.addProp()` but
      * allows to add multiple properties with one call. The new properties
      * will be validated according to the provided schemas.
      * @param props a key/schema object map.
      */
-    addProps<TProps extends Record<string, SchemaBuilder<any, any>>>(props: TProps): ObjectSchemaBuilder<TProperties & TProps, true, undefined>;
+    addProps<TProps extends Record<string, SchemaBuilder<any, any, any, any, any>>>(props: TProps): ObjectSchemaBuilder<TProperties & TProps, TRequired, TNullable, undefined, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Adds all properties from the `schema` object schema to the current schema.
      * @param schema an instance of `ObjectSchemaBuilder`
      */
-    addProps<K extends ObjectSchemaBuilder<any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProp, infer TReq, infer TExpType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProp> & TProp, TRequired, TExplicitType> : never;
+    addProps<K extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProp, infer _, any, infer __> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProp> & TProp, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions : never;
     /**
      * Omits properties listed in `properties` from the schema.
      * Consider `Omit<Type, 'prop1'|'prop2'...>` as a good illustration
      * from the TS world.
      * @param properties - array of property names (strings) to remove from the schema.
      */
-    omit<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K>, TRequired, TExplicitType>;
+    omit<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Removes `propName` from the list of properties.
      * @param propName property name to remove. Schema should contain
      * this property. An error will be thrown otherwise.
      */
-    omit<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty>, TRequired, TExplicitType>;
+    omit<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Removes all properties of `schema` from the current schema.
      * `Omit<TSchema, keyof TAnotherSchema>` as a good illustration
      * from the TS world.
      * @param schema schema builder to take properties from.
      */
-    omit<T>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer TRequired, infer TExplicitType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps>, TRequired, TExplicitType> : never;
+    omit<T>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer TRequired, any, infer TExplicitType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions : never;
     /**
      * Adds all properties from `schema` to the current schema.
      * `TSchema & TAnotherSchema` is a good example of the similar concept
      * in the TS type system.
      * @param schema an object schema to take properties from
      */
-    intersect<T extends ObjectSchemaBuilder<any, any, any>>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer TReq, infer TExplType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps> & TProps, TRequired, TExplType> : never;
+    intersect<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer _, any, infer TExplType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps> & TProps, TRequired, TNullable, TExplType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions : never;
     /**
      * Marks all properties in the current schema as optional.
      * It is the same as call `.optional('propname')` where `propname` is the name
      * of every property in the schema.
      */
-    partial(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TExplicitType>;
+    partial(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Marks all properties from `properties` as optional in the schema.
      * @param properties list of property names (string) to make optional
      */
-    partial<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K> & Pick<MakeChildrenOptional<TProperties>, K>, TRequired, TExplicitType>;
+    partial<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K> & Pick<MakeChildrenOptional<TProperties>, K>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Marks property `propName` as optional in the schema.
      * @param propName the name of the property (string).
      */
-    partial<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty> & Pick<MakeChildrenOptional<TProperties>, TProperty>, TRequired, TExplicitType>;
+    partial<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty> & Pick<MakeChildrenOptional<TProperties>, TProperty>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    /**
+     * Recursively marks all properties — and all properties of nested
+     * `object()` schemas — as optional.  Useful for PATCH API bodies
+     * and partial form state where every field at every level is optional.
+     *
+     * Only nested `ObjectSchemaBuilder` schemas are recursed into.
+     * Other schema types (arrays, unions, primitives, lazy) are made
+     * optional at the top level but their internals are not modified.
+     *
+     * @example
+     * ```ts
+     * const Address = object({
+     *   street: string(),
+     *   city:   string()
+     * });
+     *
+     * const User = object({
+     *   name:    string(),
+     *   address: Address
+     * });
+     *
+     * const PatchUser = User.deepPartial();
+     * // PatchUser infers as:
+     * // { name?: string; address?: { street?: string; city?: string } }
+     *
+     * PatchUser.validate({ address: { city: 'Paris' } }); // valid
+     * PatchUser.validate({});                              // valid
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Three-level nesting
+     * const schema = object({
+     *   a: object({
+     *     b: object({ c: string() })
+     *   })
+     * }).deepPartial();
+     *
+     * schema.validate({});               // valid
+     * schema.validate({ a: {} });        // valid
+     * schema.validate({ a: { b: {} } }); // valid
+     * ```
+     *
+     * @example
+     * ```ts
+     * // PATCH API body
+     * const CreateBody = object({
+     *   profile: object({ displayName: string(), bio: string() }),
+     *   settings: object({ theme: string(), language: string() })
+     * });
+     *
+     * const PatchBody = CreateBody.deepPartial();
+     * // All fields are optional at every level —
+     * // send only what you want to update.
+     * ```
+     *
+     * @see {@link partial} for shallow-only property optionality.
+     */
+    deepPartial(): ObjectSchemaBuilder<DeepMakeChildrenOptional<TProperties>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Returns a new schema containing only properties listed in
      * `properties` array.
      * @param properties array of property names (strings)
      */
-    pick<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>;
+    pick<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, TNullable, undefined, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Returns new schema based on the current schema. This new schema
      * will consists only from properties which names are taken from the
      * `schema` object schema.
      * @param schema schema to take property names list from
      */
-    pick<K extends ObjectSchemaBuilder<any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProps, infer T1, infer T2> ? ObjectSchemaBuilder<Omit<TProperties, keyof Omit<TProperties, keyof TProps>>, TRequired, undefined> : never;
+    pick<K extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProps, infer _, any, infer __> ? ObjectSchemaBuilder<Omit<TProperties, keyof Omit<TProperties, keyof TProps>>, TRequired, TNullable, undefined, THasDefault, TExtensions, TConstructorSchemas> & TExtensions : never;
     /**
      * Returns a new schema consisting of only one property
      * (taken from the `property` property name). If the property
      * does not exists in the current schema, an error will be thrown.
      * @param property the name of the property (string).
      */
-    pick<K extends keyof TProperties>(property: K): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>;
+    pick<K extends keyof TProperties>(property: K): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, TNullable, undefined, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Modify schema for `propName` and return a new schema.
      * Could be useful if you want to leave all schema intact, but
@@ -270,43 +664,74 @@ export declare class ObjectSchemaBuilder<TProperties extends Record<string, Sche
      * you will receive an old schema for `propName`.
      * @returns
      */
-    modifyPropSchema<K extends keyof TProperties, R extends SchemaBuilder<any, any>>(propName: K, callback: (builder: TProperties[K]) => R): ObjectSchemaBuilder<ModifyPropSchema<TProperties, K, R>, TRequired, TExplicitType>;
+    modifyPropSchema<K extends keyof TProperties, R extends SchemaBuilder<any, any, any, any, any>>(propName: K, callback: (builder: TProperties[K]) => R): ObjectSchemaBuilder<ModifyPropSchema<TProperties, K, R>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * An alias for `.partial(prop: string)`
      * @param prop name of the property
      */
-    makePropOptional<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildOptional<TProperties, K>, TRequired, TExplicitType>;
+    makePropOptional<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildOptional<TProperties, K>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * Marks `prop` as required property.
      * If `prop` does not exists in the current schema,
      * an error will be thrown.
      * @param prop name of the property
      */
-    makePropRequired<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildRequired<TProperties, K>, TRequired, TExplicitType>;
+    makePropRequired<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildRequired<TProperties, K>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * `Partial<T>` would be a good example of the
      * same operation in the TS world.
      */
-    makeAllPropsOptional(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TExplicitType>;
+    makeAllPropsOptional(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
     /**
      * `Required<T>` would be a good example of the
      * same operation in the TS world.
      */
-    makeAllPropsRequired(): ObjectSchemaBuilder<MakeChildrenRequired<TProperties>, TRequired, TExplicitType>;
+    makeAllPropsRequired(): ObjectSchemaBuilder<MakeChildrenRequired<TProperties>, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TConstructorSchemas> & TExtensions;
+    static getPropertiesFor<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>> = {}, TRequired extends boolean = true, TExplicitType = undefined, TSchema extends ObjectSchemaBuilder<any, any, any, any> = ObjectSchemaBuilder<TProperties, TRequired, false, TExplicitType>>(schema: TSchema): PropertyDescriptorTree<TSchema, TSchema>;
+    static isValidPropertyDescriptor(descriptor: PropertyDescriptor<any, any, any>): boolean;
+    nullable(): ObjectSchemaBuilder<TProperties, TRequired, true, TExplicitType, THasDefault, TExtensions, TConstructorSchemas>;
+    notNullable(): ObjectSchemaBuilder<TProperties, TRequired, false, TExplicitType, THasDefault, TExtensions, TConstructorSchemas>;
 }
-/**
- * Defines a schema for empty object `{}`
- */
-export declare function object(): ObjectSchemaBuilder<{}, true>;
-/**
- * Defines an object schema, properties definitions are takens from `props`.
- * @param props key/schema object map for schema's properties.
- */
-export declare function object<TProps extends Record<string, SchemaBuilder<any, any>>>(props: TProps): ObjectSchemaBuilder<TProps, true>;
-type RequiredProps<T extends Record<string, SchemaBuilder<any, any>>> = keyof {
-    [k in keyof T as T[k] extends SchemaBuilder<infer TRes, infer TReq> ? TReq extends true ? k : never : never]: T[k];
+export interface Object {
+    /**
+     * Defines a schema for empty object `{}`
+     */
+    (): ObjectSchemaBuilder<{}, true>;
+    /**
+     * Defines an object schema, properties definitions are takens from `props`.
+     * @param props key/schema object map for schema's properties.
+     */
+    <TProps extends Record<string, SchemaBuilder<any, any, any, any, any>>>(props: TProps): ObjectSchemaBuilder<TProps, true>;
+    /**
+     * Defines an object schema, properties definitions are takens from `props`.
+     * @param props key/schema object map for schema's properties.
+     */
+    <TProps extends Record<string, SchemaBuilder<any, any, any, any, any>>>(props?: TProps): ObjectSchemaBuilder<TProps, true>;
+    /**
+     * Returns a tree of property descriptors for the given `schema`.
+     * The structure of the tree is the same as the structure of the `schema`.
+     * Which gives you an opportunity to access property descriptors for each
+     * property in the schema in a useful and type-safe way.
+     * @param schema
+     */
+    getPropertiesFor<TProperties extends Record<string, SchemaBuilder<any, any, any, any, any>> = {}, TRequired extends boolean = true, TExplicitType = undefined, TSchema extends ObjectSchemaBuilder<any, any, any, any> = ObjectSchemaBuilder<TProperties, TRequired, false, TExplicitType>>(schema: TSchema): PropertyDescriptorTree<TSchema, TSchema>;
+    /**
+     * Verifies if the given `descriptor` is a valid property descriptor.
+     * @param descriptor a property descriptor to check
+     */
+    isValidPropertyDescriptor(descriptor: PropertyDescriptor<any, any, any>): boolean;
+}
+declare const object: Object;
+export { object };
+type RequiredProps<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<any, infer TReq, any, any> ? TReq extends true ? k : never : never]: T[k];
+};
+type NotRequiredProps<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<any, infer TReq, any, any> ? TReq extends true ? never : k : never]: T[k];
+};
+type RequiredInputProps<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<any, infer TReq, any, infer THasDef> ? TReq extends true ? THasDef extends true ? never : k : never : never]: T[k];
 };
-type NotRequiredProps<T extends Record<string, SchemaBuilder<any, any>>> = keyof {
-    [k in keyof T as T[k] extends SchemaBuilder<infer TRes, infer TReq> ? TReq extends true ? never : k : never]: T[k];
+type NotRequiredInputProps<T extends Record<string, SchemaBuilder<any, any, any, any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<any, infer TReq, any, infer THasDef> ? TReq extends true ? THasDef extends true ? k : never : k : never]: T[k];
 };
-export {};