@cleverbrush/schema 1.1.10 → 2.0.0

package/dist/builders/ObjectSchemaBuilder.d.ts

@@ -1,29 +1,70 @@
-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>, 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>>> = {
+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> ? 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>, TSchema extends ObjectSchemaBuilder<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> ? PropertyValidationResult<TPropertySchema, TRootSchema, TParentPropertyDescriptor> : NestedValidationResult<TPropertySchema, TRootSchema, TParentPropertyDescriptor>;
+};
 /**
  * Object schema builder class. Similar to the `object` type
  * in JS. Allows to define a schema for `object` value.
@@ -45,7 +86,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 +102,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 +115,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 +133,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 +151,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 = {}> extends SchemaBuilder<undefined extends TExplicitType ? 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
@@ -128,49 +175,117 @@ export declare class ObjectSchemaBuilder<TProperties extends Record<string, Sche
         acceptUnknownProps: boolean;
         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 ? RespectPropsOptionality<TProperties> : TExplicitType>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: (undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | (() => undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | undefined;
+        description: string | undefined;
+        hasCatch: boolean;
+        catchValue: (undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | (() => undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | undefined;
     };
     /**
      * @hidden
      */
-    required(): ObjectSchemaBuilder<TProperties, true, TExplicitType>;
+    required(errorMessage?: ValidationErrorMessageProvider): ObjectSchemaBuilder<TProperties, true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): ObjectSchemaBuilder<TProperties, false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: (undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType) | (() => undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType)): ObjectSchemaBuilder<TProperties, true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
     /**
      * @hidden
      */
-    optional(): ObjectSchemaBuilder<TProperties, false, TExplicitType>;
+    clearDefault(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
     /**
-     * Performs validion of object schema over the `object`.
+     * @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> & 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> & 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;
+    }>>;
+    /**
+     * 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 ? RespectPropsOptionality<TProperties> : TExplicitType, context?: ValidationContext): Promise<ValidationResult<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>>;
+    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>;
+    /**
+     * @param object The object to validate against this schema.
+     * @param context Optional `ValidationContext` settings.
+     */
+    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> & 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> & TExtensions;
     /**
-     * @hidden
+     * @inheritdoc
      */
-    hasType<T>(notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, T>;
+    hasType<T>(_notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, TNullable, T, THasDefault, TExtensions> & TExtensions;
     /**
-     * @hidden
+     * @inheritdoc
      */
-    clearHasType(): ObjectSchemaBuilder<TProperties, TRequired>;
+    clearHasType(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, undefined, 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> & TExtensions;
     /**
      * @hidden
      * @deprecated this is for internal use, do not use if you are
@@ -185,82 +300,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 ? 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> & 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>>(schema: K): K extends ObjectSchemaBuilder<infer TProp, infer _, any, infer __> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProp> & TProp, TRequired, TNullable, TExplicitType, THasDefault, TExtensions> & 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> & 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> & 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> & 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>>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer _, any, infer TExplType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps> & TProps, TRequired, TNullable, TExplType, THasDefault, TExtensions> & 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> & 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> & 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> & 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> & 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> & 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>>(schema: K): K extends ObjectSchemaBuilder<infer TProps, infer _, any, infer __> ? ObjectSchemaBuilder<Omit<TProperties, keyof Omit<TProperties, keyof TProps>>, TRequired, TNullable, undefined, THasDefault, TExtensions> & 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> & TExtensions;
     /**
      * Modify schema for `propName` and return a new schema.
      * Could be useful if you want to leave all schema intact, but
@@ -270,43 +444,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> & 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> & 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> & 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> & 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> & 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>;
+    notNullable(): ObjectSchemaBuilder<TProperties, TRequired, false, TExplicitType, THasDefault, TExtensions>;
 }
-/**
- * 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 {};