@cleverbrush/schema 0.0.0-beta-20260410073748

package/dist/builders/ObjectSchemaBuilder.d.ts

@@ -0,0 +1,517 @@
+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, any, any, any>>> = {
+    [K in RequiredProps<T>]: InferType<T[K]>;
+} & {
+    [K in NotRequiredProps<T>]?: InferType<T[K]>;
+};
+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, any, any, any>>> = {
+    [K in keyof T]: ReturnType<T[K]['optional']>;
+};
+/**
+ * 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, 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, 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.
+ * Should be used to validate objects with specific properties.
+ * Properties should be defined as their own schema builders.
+ * You can use any `SchemaBuilder` e.g. `string()`, `number()`,
+ * `boolean()`, `array()`, `object()`, etc. to define properties.
+ * Which means that you can define nested objects and arrays of
+ * any complexity.
+ *
+ * **NOTE** this class is exported only to give opportunity to extend it
+ * by inheriting. It is not recommended to create an instance of this class
+ * directly. Use {@link object | object()} function instead.
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *    name: string(),
+ *    age: number()
+ * });
+ *
+ * const result = schema.validate({
+ *   name: 'John',
+ *   age: 30
+ * });
+ *
+ * // result.valid === true
+ * // result.object === { name: 'John', age: 30 }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *   name: string(),
+ *   age: number().optional()
+ * });
+ *
+ * const result = schema.validate({
+ *  name: 'John'
+ * });
+ * // result.valid === true
+ * // result.object === { name: 'John' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *  name: string(),
+ *  age: number();
+ * });
+ * const result = schema.validate({
+ *  name: 'John'
+ * });
+ *
+ * // result.valid === false
+ * // result.errors is deprecated — use result.getErrorsFor() instead
+ * // result.getErrorsFor((p) => p.age).errors // ["is expected to have property 'age'"]
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ * name: string(),
+ * address: object({
+ *     city: string(),
+ *     country: string()
+ *   })
+ * });
+ * const result = schema.validate({
+ * name: 'John',
+ * address: {
+ *    city: 'New York',
+ *    country: 'USA'
+ *  }
+ * });
+ * // result.valid === true
+ * // result.object === {
+ * //   name: 'John',
+ * //   address: {
+ * //     city: 'New York',
+ * //     country: 'USA'
+ * //   }
+ * // }
+ * ```
+ * @see {@link object}
+ */
+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;
+    /** 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;
+    protected constructor(props: ObjectSchemaBuilderCreateProps);
+    introspect(): {
+        /**
+         * Properties defined in schema
+         */
+        properties: TProperties;
+        /**
+         * If set to `true`, schema validation will not
+         * return errors if object contains fields which
+         * are not defined in the schema `properties`.
+         * Set to `false` by default
+         */
+        acceptUnknownProps: boolean;
+        type: string;
+        isRequired: boolean;
+        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(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
+     */
+    clearDefault(): ObjectSchemaBuilder<TProperties, TRequired, TNullable, TExplicitType, false, TExtensions> & 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> & 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 ? 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, 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, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    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, any, any, any>, TName extends string>(propName: TName, schema: TType): ObjectSchemaBuilder<TProperties & {
+        [k in TName]: TType;
+    }, TRequired, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     * @deprecated this is for internal use, do not use if you are
+     * not sure you need it.
+     *
+     * TODO: This is used to avoid `&` in resulting types. For example,
+     * when you have a schema like `object({prop1: string()})` and then use `addProp({prop2: string()})` method,
+     * the resulting type without `optimize` will be something like `{prop1: string} & {prop2: string}`. Which
+     * is not we would like to have. Instead we want to have `{prop1: string, prop2: string}`. This is what
+     * `optimize` method does. However it is not always possible to do this optimization without losing
+     * JSDoc comments, which is sucks. For example, I had to disable optimization for UnionSchemas, because
+     * 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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
+     * change a type of one property.
+     * @param propName name of the property (string)
+     * @param callback callback function returning a new schema fo the `propName`. As a first parameter
+     * you will receive an old schema for `propName`.
+     * @returns
+     */
+    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, 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, 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, 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, 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>;
+}
+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 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];
+};

package/dist/builders/ObjectSchemaBuilder.js

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-NXPH3ZUW.js";import"../chunk-CTP4RHDG.js";export{a as ObjectSchemaBuilder,b as object};
+//# sourceMappingURL=ObjectSchemaBuilder.js.map

package/dist/builders/ObjectSchemaBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/builders/PropertyValidationResult.d.ts

@@ -0,0 +1,68 @@
+import { ObjectSchemaBuilder } from './ObjectSchemaBuilder.js';
+import { type InferType, type NestedValidationResult, type PropertyDescriptorInner, type PropertyDescriptorTree } from './SchemaBuilder.js';
+/**
+ * Mutable container for nested validation results associated with a specific
+ * property descriptor. Implements {@link NestedValidationResult} and tracks
+ * the seen value, accumulated error messages, and child results for
+ * nested object properties.
+ *
+ * Used internally by `ObjectSchemaBuilder` during validation to build up
+ * a tree of per-property validation results.
+ */
+export declare class PropertyValidationResult<TSchema extends ObjectSchemaBuilder<any, any, any, any, any> = ObjectSchemaBuilder<any, any, any, any, any>, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any> = ObjectSchemaBuilder<any, any, any, any, any>, TParentPropertyDescriptor = any> implements NestedValidationResult<TSchema, TRootSchema, TParentPropertyDescriptor> {
+    #private;
+    /**
+     * The value that was seen at the property location described by the descriptor.
+     * Retrieves the value from the root object using the property descriptor's `getValue` method.
+     * Returns `undefined` if the property is not found.
+     */
+    get seenValue(): InferType<TSchema> | undefined;
+    /**
+     * The list of validation error messages accumulated for this property.
+     */
+    get errors(): ReadonlyArray<string>;
+    /**
+     * Whether validation passed for this property and all of its children.
+     * Returns `true` only when there are no errors and no child errors.
+     */
+    get isValid(): boolean;
+    /**
+     * Returns the list of child `NestedValidationResult` instances
+     * representing validation results for nested properties.
+     */
+    getChildErrors(): ReadonlyArray<NestedValidationResult<any, any, any>>;
+    /**
+     * The inner property descriptor providing `getValue`, `setValue`, and `getSchema`
+     * operations for the property this error relates to.
+     */
+    get descriptor(): PropertyDescriptorInner<TRootSchema, TSchema, TParentPropertyDescriptor>;
+    /**
+     * Creates a new `PropertyValidationResult`.
+     *
+     * @param descriptor - the property descriptor tree node this error is associated with;
+     *   must be a valid descriptor (checked via `ObjectSchemaBuilder.isValidPropertyDescriptor`)
+     * @param rootObjectValue - the root object being validated, used to resolve property values
+     * @param errors - optional initial list of error message strings
+     * @throws if `descriptor` is not a valid property descriptor
+     */
+    constructor(descriptor: PropertyDescriptorTree<TSchema, TRootSchema, any, TParentPropertyDescriptor>, rootObjectValue: InferType<TRootSchema> | undefined, errors?: string[]);
+    /**
+     * Appends a validation error message to this property's error list.
+     * @param error - the error message string to add
+     */
+    addError(error: string): void;
+    /**
+     * Appends a child `NestedValidationResult` for a nested property.
+     * @param childError - the child validation result to add
+     */
+    addChildError(childError: NestedValidationResult<any, any, any>): void;
+    /**
+     * Returns a JSON-serializable representation of this validation result.
+     * This ensures `JSON.stringify` includes `isValid` and `errors`,
+     * which are otherwise non-enumerable prototype getters.
+     */
+    toJSON(): {
+        isValid: boolean;
+        errors: ReadonlyArray<string>;
+    };
+}