@cleverbrush/schema 1.1.11 → 3.0.0

package/dist/builders/SchemaBuilder.d.ts

@@ -1,14 +1,112 @@
-import { Transaction } from '../utils/transaction.js';
-export type InferType<T> = T extends SchemaBuilder<infer TResult, infer TRequired> ? T extends {
-    optimize: (...args: any[]) => SchemaBuilder<infer TOptimizedType, infer TOptimizedRequired>;
-} ? TOptimizedRequired extends true ? TOptimizedType : MakeOptional<TOptimizedType> : TRequired extends true ? TResult : MakeOptional<TResult> : T;
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type Transaction } from '../utils/transaction.js';
+import type { ArraySchemaBuilder } from './ArraySchemaBuilder.js';
+import type { ExternSchemaBuilder } from './ExternSchemaBuilder.js';
+import type { ObjectSchemaBuilder } from './ObjectSchemaBuilder.js';
+/** @internal Symbol used as the key for the type brand on schema builders. */
+declare const __type: unique symbol;
+/** @internal */
+export type SchemaTypeBrand = typeof __type;
+/** @internal Symbol used as the key for the default-value brand on schema builders. */
+declare const __hasDefault: unique symbol;
+/** @internal */
+export type HasDefaultBrand = typeof __hasDefault;
+/** Symbol used as the key for branded/opaque types. */
+declare const __brand: unique symbol;
+/** Symbol used as the key for branded/opaque types. */
+export type BRAND = typeof __brand;
+/**
+ * Intersects a base type with a phantom brand tag.
+ * The brand exists only at the type level — zero runtime cost.
+ *
+ * @example
+ * ```ts
+ * type Email = Brand<string, 'Email'>;
+ * type UserId = Brand<number, 'UserId'>;
+ * ```
+ */
+export type Brand<T, TBrand extends string | symbol> = T & {
+    readonly [K in BRAND]: TBrand;
+};
+/**
+ * Infers the TypeScript type that a `SchemaBuilder` instance validates.
+ * Takes into account type optimizations (via `optimize()`) and whether the schema is optional.
+ *
+ * @example
+ * ```ts
+ * const userSchema = object({ name: string(), age: number().optional() });
+ * type User = InferType<typeof userSchema>;
+ * // { name: string; age?: number }
+ * ```
+ */
+export type InferType<T> = T extends {
+    optimize: (...args: any[]) => {
+        readonly [K in SchemaTypeBrand]: infer TOptimized;
+    };
+} ? TOptimized : T extends {
+    readonly [K in SchemaTypeBrand]: infer TType;
+} ? TType : T;
+/**
+ * Represents a single validation error with a human-readable error message.
+ *
+ * When returned from an object-level validator (via {@link SchemaBuilder.addValidator | addValidator}),
+ * the optional `property` selector can route the error to a specific property
+ * so that {@link ObjectSchemaValidationResult.getErrorsFor | getErrorsFor()} reports it
+ * on that property rather than only on the root object.
+ *
+ * ```ts
+ * .addValidator((v) => ({
+ *     valid: false,
+ *     errors: [{
+ *         message: 'Passwords do not match',
+ *         property: (t) => t.confirmPassword
+ *     }]
+ * }))
+ * ```
+ */
 export type ValidationError = {
-    path: string;
     message: string;
+    /**
+     * Optional property selector that targets this error to a specific
+     * property of the validated object. Uses the same selector signature
+     * as `getErrorsFor()` and react-form's `forProperty`.
+     */
+    property?: (tree: any) => any;
 };
+/**
+ * Used to represent a validation result for nested
+ * objects/properties. Contains a list of errors and
+ * the value that caused them.
+ */
+export type NestedValidationResult<TSchema, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TParentPropertyDescriptor> = {
+    /**
+     * Value that property had and which caused error or errors
+     */
+    seenValue?: InferType<TSchema>;
+    /**
+     * A list of errors, empty if object satisfies a schema
+     */
+    errors: ReadonlyArray<string>;
+    /**
+     * Whether validation passed for this property and all of its children.
+     */
+    isValid: boolean;
+    get descriptor(): PropertyDescriptorInner<TRootSchema, TSchema, TParentPropertyDescriptor>;
+};
+/**
+ * Utility type that makes a value `T` optional (i.e. `T | undefined`).
+ * Used internally by {@link InferType} to represent optional schema fields.
+ */
 export type MakeOptional<T> = {
     prop?: T;
 }['prop'];
+/**
+ * Type of the function that provides a validation error message for
+ * the given `seenValue` and `schema`. Can be a string or a function
+ * returning a string or a promise of a string.
+ * Should be used to provide a custom validation error message.
+ */
+export type ValidationErrorMessageProvider<TSchema extends SchemaBuilder<any, any, any, any, any> = SchemaBuilder<any, any, any, any, any>> = string | ((seenValue: InferType<TSchema>, schema: TSchema) => string | Promise<string>);
 export type ValidationResult<T> = {
     /**
      * If `true` - object satisfies schema
@@ -21,33 +119,318 @@ export type ValidationResult<T> = {
     object?: T;
     errors?: ValidationError[];
 };
+/**
+ * Error thrown by {@link SchemaBuilder.parse | parse()} and
+ * {@link SchemaBuilder.parseAsync | parseAsync()} when validation fails.
+ * Carries the full array of {@link ValidationError | validation errors}.
+ */
+export declare class SchemaValidationError extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+/**
+ * Internal result returned by the `preValidate` step of `SchemaBuilder`.
+ * Contains the validation context, any early errors, and the transaction
+ * wrapping the (possibly preprocessed) value.
+ */
 export type PreValidationResult<T, TTransactionType> = Omit<ValidationResult<T>, 'object'> & {
     context: ValidationContext;
     transaction?: Transaction<TTransactionType>;
+    rootPropertyDescriptor?: PropertyDescriptor<any, any, undefined>;
 };
 type ValidatorResult<T> = Omit<ValidationResult<T>, 'object' | 'errors'> & {
-    errors?: Omit<ValidationError, 'path'>[];
+    errors?: ValidationError[];
 };
+/**
+ * A function that transforms the value before validation.
+ * Preprocessors run in order before validators and can modify or replace the value.
+ *
+ * @param object - the current value to preprocess
+ * @returns the transformed value, or a Promise resolving to it
+ */
 export type Preprocessor<T> = (object: T) => Promise<T> | T;
+/**
+ * A custom validation function that checks a value and returns a result
+ * indicating whether the value is valid, along with optional error messages.
+ *
+ * @param object - the value to validate
+ * @returns a result with `valid` boolean and optional `errors` array, or a Promise resolving to it
+ */
 export type Validator<T> = (object: T) => Promise<ValidatorResult<T>> | ValidatorResult<T>;
+/**
+ * Internal wrapper that pairs a preprocessor function with metadata
+ * indicating whether it may mutate the value.
+ */
+export type PreprocessorEntry<T> = {
+    fn: Preprocessor<T>;
+    mutates: boolean;
+};
+/**
+ * Internal wrapper that pairs a validator function with metadata
+ * indicating whether it may mutate the value.
+ */
+export type ValidatorEntry<T> = {
+    fn: Validator<T>;
+    mutates: boolean;
+};
+/**
+ * Configuration properties used to construct a `SchemaBuilder` instance.
+ * Contains the schema type identifier, requirement flag, and lists of
+ * preprocessors and validators.
+ */
 export type SchemaBuilderProps<T> = {
     type: string;
     isRequired?: boolean;
-    preprocessors: Preprocessor<T>[];
-    validators: Validator<T>[];
+    isNullable?: boolean;
+    isReadonly?: boolean;
+    preprocessors: PreprocessorEntry<T>[];
+    validators: ValidatorEntry<T>[];
+    requiredValidationErrorMessageProvider?: ValidationErrorMessageProvider;
+    extensions?: Record<string, unknown>;
+    defaultValue?: T | (() => T);
+    catchValue?: T | (() => T);
+    hasCatch?: boolean;
+    description?: string;
+    schemaName?: string;
+    example?: unknown;
 };
-export type ValidationContext = {
-    /**
-     * Path of the field. **Optional**, used to display correct error path in the {@link ValidationError}
-     */
-    path?: string;
+export type ValidationContext<TSchema extends SchemaBuilder<any, any, any, any> = SchemaBuilder<any, any, any, any>> = {
     /**
      * Optional. By default validation will stop after the first validation error, in case if
      * you want to receive all validation erors, please set this flag to `true`.
      * You might need it to display validation errors.
      */
     doNotStopOnFirstError?: boolean;
+    /**
+     * Optional. If you define a `rootPropertyDescriptor` while validating an object,
+     * it will report all validation errors with the path starting from the root property.
+     * Normally it's used internally by the library for validation of nested objects and
+     * should not be used directly (but who knows, maybe you will find a use case for it).
+     */
+    rootPropertyDescriptor?: TSchema extends ObjectSchemaBuilder<any, any, any, any> ? PropertyDescriptor<TSchema, TSchema, undefined> : never;
+    /**
+     * Optional. This is a property descriptor for the current object being validated.
+     * This descriptor is descendant of the `rootPropertyDescriptor` and is used to provide
+     * a path to the current object being validated in the root object.
+     * Normally it's used internally by the library for validation of nested objects and
+     * should not be used directly (but who knows, maybe you will find a use case for it).
+     */
+    currentPropertyDescriptor?: TSchema extends ObjectSchemaBuilder<any, any, any> ? PropertyDescriptor<TSchema, TSchema, unknown> : never;
+    /**
+     * Optional. Used along with `rootPropertyDescriptor` and `currentPropertyDescriptor` to provide
+     * a root validation object, this object will be used to retrieve the value of properties
+     * using the `rootPropertyDescriptor` because the `rootPropertyDescriptor` is a property descriptor
+     * for the root object, and it needs the root object along with the whole structure to get the
+     * value of the property.
+     *
+     * Normally it's used internally by the library for validation of nested objects and
+     * should not be used directly (but who knows, maybe you will find a use case for it).
+     */
+    rootValidationObject?: InferType<TSchema>;
+};
+/**
+ * A symbol to mark property descriptors in the schema.
+ * Normally, you should not use it directly unless you want
+ * to develop some advanced features or extend the library.
+ * In normal conditions it's used internally by the library.
+ */
+export declare const SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR: unique symbol;
+/**
+ * A symbol that marks a schema as having sub-properties that can
+ * participate in property descriptor trees. When a schema exposes
+ * `[SYMBOL_HAS_PROPERTIES] = true` **and** its `introspect()` returns
+ * a `properties` record, it will be recursed into by
+ * `ObjectSchemaBuilder.getPropertiesFor()` — the same way nested
+ * `ObjectSchemaBuilder` instances are.
+ *
+ * Currently implemented by `ObjectSchemaBuilder` (always) and
+ * `ExternSchemaBuilder` (when created with an explicit property map).
+ */
+export declare const SYMBOL_HAS_PROPERTIES: unique symbol;
+/**
+ * Describes a property in a schema. And gives you
+ * a possibility to access property value and set it.
+ * suppose you have a schema like this:
+ * ```ts
+ * const schema = object({
+ *  name: string(),
+ *  address: object({
+ *   city: string(),
+ *   country: string()
+ *  }),
+ *  id: number()
+ * });
+ * ```
+ * then you can get a property descriptor for the `address.city` property
+ * like this:
+ * ```ts
+ * const addressCityDescriptor = object.getPropertiesFor(schema).address.city;
+ * ```
+ *
+ * And then you can use it to get and set the value of this property having the object:
+ * ```ts
+ * const obj = {
+ * name: 'Leo',
+ * address: {
+ *  city: 'Kozelsk',
+ *  country: 'Russia'
+ *  },
+ *  id: 123
+ * };
+ *
+ * const success = addressCityDescriptor.setValue(obj, 'Venyov');
+ * // this returns you a boolean value indicating if the value was set successfully
+ * ```
+ */
+export type PropertySetterOptions = {
+    /**
+     * If set to `true`, the method will create missing structure
+     * in the object to set the value. For example, if you have a schema
+     * and property descriptor like this:
+     * ```ts
+     * const schema = object({
+     * address: object({
+     * city: string(),
+     * country: string()
+     * }),
+     * });
+     * const addressCityDescriptor = object.getPropertiesFor(schema).address.city;
+     * ```
+     * And then you try to set a new value to the `address.city` property on the object
+     * which does not have `address` property:
+     * ```ts
+     * const obj = {
+     * name: 'Leo'
+     * };
+     * const success = addressCityDescriptor.setValue(obj, 'Venyov', { createMissingStructure: true });
+     * // success === true
+     * // obj === {
+     * // name: 'Leo',
+     * // address: {
+     * // city: 'Venyov'
+     * //  }
+     * // }
+     */
+    createMissingStructure?: boolean;
+};
+/**
+ * Extracts the inner property descriptor type from a `PropertyDescriptor`.
+ * Returns `undefined` if `T` is not a valid `PropertyDescriptor`.
+ */
+export type PropertyDescriptorInnerFromPropertyDescriptor<T> = T extends PropertyDescriptor<infer TSchema, infer TPropertySchema, infer TParentPropertyDescriptor> ? PropertyDescriptorInner<TSchema, TPropertySchema, TParentPropertyDescriptor> : undefined;
+export type PropertyDescriptorInner<TSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TPropertySchema, TParentPropertyDescriptor> = {
+    /**
+     * Sets a new value to the property. If the process was successful,
+     * the method returns `true`, otherwise `false`.
+     * It can return `false` if the property could not be set to the object
+     * which can happen if the `setValue` method is called with an object
+     * which does not comply with the schema.
+     * for example, if you have a schema and property descriptopr like this:
+     * ```ts
+     * const schema = object({
+     *  name: string(),
+     *  address: object({
+     *   city: string(),
+     *   country: string()
+     *  }),
+     *  id: number()
+     * });
+     *
+     * const addressCityDescriptor = object.getPropertiesFor(schema).address.city;
+     * ```
+     * And then you try to set a new value to the `address.city` property on the object
+     * which does not have `address` property:
+     * ```ts
+     * const obj = {
+     * name: 'Leo'
+     * };
+     *
+     * const success = addressCityDescriptor.setValue(obj, 'Venyov');
+     * // success === false
+     * ```
+     *
+     * @param obj Object to set the value to
+     * @param value a new value to set to the property
+     * @param options additional optional parameters to control the process
+     * @returns
+     */
+    setValue: (obj: InferType<TSchema>, value: InferType<TPropertySchema>, options?: PropertySetterOptions) => boolean;
+    /**
+     * Gets the value of the property from the object.
+     * @param obj object to get the value from
+     * @returns an object containing a `value` and `success` properties. `value` is the value of the property
+     * if it was found in the object, `success` is a boolean value indicating if the property was found in the object.
+     */
+    getValue: (obj: InferType<TSchema>) => {
+        value?: InferType<TPropertySchema>;
+        success: boolean;
+    };
+    /**
+     * Gets the schema for the property described by the property descriptor.
+     * @returns a schema for the property
+     */
+    getSchema: () => TPropertySchema;
+    parent: PropertyDescriptorInnerFromPropertyDescriptor<TParentPropertyDescriptor>;
+    /**
+     * The name of this property within its parent object, or `undefined`
+     * for the root descriptor.
+     */
+    propertyName: string | undefined;
+    /**
+     * Returns a JSON Pointer (RFC 6901) string representing this
+     * property's path from the root descriptor.
+     *
+     * Property names are escaped per RFC 6901 (`~` → `~0`, `/` → `~1`).
+     * The root descriptor returns an empty string (`''`).
+     */
+    toJsonPointer: () => string;
 };
+/**
+ * A wrapper object keyed by {@link SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR} that
+ * holds a {@link PropertyDescriptorInner} for a particular property within
+ * an object schema. Used to get/set property values on validated objects.
+ */
+export type PropertyDescriptor<TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TPropertySchema, TParentPropertyDescriptor> = {
+    [SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR]: PropertyDescriptorInner<TRootSchema, TPropertySchema, TParentPropertyDescriptor>;
+};
+/**
+ * A tree of property descriptors for the schema.
+ * Has a possibility to filter properties by the type (`TAssignableTo` type parameter).
+ */
+export type PropertyDescriptorTree<TSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any> = TSchema, TAssignableTo = any, TParentPropertyDescriptor = undefined> = PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor> & (TSchema extends ObjectSchemaBuilder<infer TProperties, any, any> ? {
+    [K in keyof TProperties]: TProperties[K] extends ObjectSchemaBuilder<any, any, any> ? PropertyDescriptorTree<TProperties[K], TRootSchema, any, PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : TProperties[K] extends ExternSchemaBuilder<any, any, any, any, any, any, infer TExternResult> ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> & ExternOutputPropertyDescriptors<TExternResult, TRootSchema, PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>>> : TProperties[K] extends ArraySchemaBuilder<infer TArrayElement, any, any> ? TArrayElement extends ObjectSchemaBuilder<any, any, any, any, any> ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : InferType<TProperties[K]> extends TAssignableTo ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : never : InferType<TProperties[K]> extends TAssignableTo ? PropertyDescriptor<TRootSchema, TProperties[K], PropertyDescriptor<TRootSchema, TSchema, TParentPropertyDescriptor>> : never;
+} : never);
+/**
+ * Recursively maps the keys of an extern schema's output type into
+ * property descriptors.  When a value is a plain-object type its keys
+ * are expanded recursively; primitives, arrays, Dates, and functions
+ * are treated as leaves.
+ *
+ * @internal
+ */
+type ExternOutputPropertyDescriptors<TOutput, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any>, TParentPropertyDescriptor> = TOutput extends Date | Function | readonly any[] | string | number | boolean | symbol | bigint | null | undefined ? {} : TOutput extends Record<string, any> ? {
+    [K in keyof TOutput]: PropertyDescriptor<TRootSchema, SchemaBuilder<TOutput[K], true, false, false, {}>, TParentPropertyDescriptor> & ExternOutputPropertyDescriptors<TOutput[K], TRootSchema, PropertyDescriptor<TRootSchema, SchemaBuilder<TOutput[K], true, false, false, {}>, TParentPropertyDescriptor>>;
+} : {};
+/**
+ * Creates an array augmented with non-enumerable NestedValidationResult
+ * properties (`seenValue`, `errors`, `isValid`, `descriptor`).
+ * Used by UnionSchemaBuilder and ArraySchemaBuilder to return hybrid
+ * arrays from `getErrorsFor()`.
+ */
+export declare function createHybridErrorArray<T extends any[]>(items: T, seenValue: () => any, errors: () => ReadonlyArray<string>, descriptor: () => any): T;
+/**
+ * Resolves the full output type of a schema, accounting for `TRequired` and
+ * `TNullable` modifiers. Mirrors the branded `[__type]` computation so that
+ * the `~standard` Standard Schema property carries the correct inferred type.
+ *
+ * - When `TRequired = true` and `TNullable = false` the result is `TResult`.
+ * - When `TRequired = true` and `TNullable = true` the result is `TResult | null`.
+ * - When `TRequired = false` the result is wrapped by {@link MakeOptional},
+ *   adding `| undefined` (and `| null` when also nullable).
+ *
+ * @internal
+ */
+type ResolvedSchemaType<TResult, TRequired extends boolean, TNullable extends boolean> = TRequired extends true ? TNullable extends true ? TResult | null : TResult : MakeOptional<TNullable extends true ? TResult | null : TResult>;
 /**
  * Base class for all schema builders. Provides basic functionality for schema building.
  *
@@ -55,45 +438,195 @@ export type ValidationContext = {
  * @typeparam TResult Type of the object that will be returned by `validate()` method.
  * @typeparam TRequired If `true`, object will be required. If `false`, object will be optional.
  */
-export declare abstract class SchemaBuilder<TResult = any, TRequired extends boolean = true> {
+export declare abstract class SchemaBuilder<TResult = any, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> {
     #private;
     /**
-     * Set type of schema explicitly. `notUsed` param is needed only for cas when JS is used. E.g. when you
+     * Type-level brand encoding the inferred type of this schema.
+     * Not emitted at runtime — used only by {@link InferType}.
+     * @internal
+     */
+    readonly [__type]: TRequired extends true ? TNullable extends true ? TResult | null : TResult : MakeOptional<TNullable extends true ? TResult | null : TResult>;
+    /**
+     * Type-level brand encoding whether this schema has a default value.
+     * Not emitted at runtime — used by input type inference.
+     * @internal
+     */
+    readonly [__hasDefault]: THasDefault;
+    /**
+     * Standard Schema v1 interface.
+     *
+     * Exposes this schema as a [Standard Schema v1](https://standardschema.dev/)
+     * validator, enabling out-of-the-box interoperability with any library that
+     * consumes the spec — including tRPC, TanStack Form, React Hook Form, T3 Env,
+     * Hono, Elysia, next-safe-action, and 50+ other tools.
+     *
+     * Every `SchemaBuilder` subclass (all 13 builders) inherits this property
+     * automatically — no additional setup required.
+     *
+     * **Shape of the returned object:**
+     * - `version` — always `1` (Standard Schema spec version)
+     * - `vendor` — `'@cleverbrush/schema'`
+     * - `validate(value)` — synchronous; wraps this builder's own `.validate()`
+     *   and converts its result to the Standard Schema `Result<Output>` format:
+     *   - Success: `{ value: <validated output> }`
+     *   - Failure: `{ issues: [{ message: string }, …] }`
+     *
+     * The returned object is **cached** after the first access so repeated reads
+     * return the same reference (required by the spec).
+     *
+     * @example
+     * ```ts
+     * import { object, string, number } from '@cleverbrush/schema';
+     *
+     * const UserSchema = object({
+     *   name:  string().minLength(2),
+     *   email: string().email(),
+     *   age:   number().min(18).optional(),
+     * });
+     *
+     * // Grab the Standard Schema interface
+     * const std = UserSchema['~standard'];
+     * // std.version === 1
+     * // std.vendor  === '@cleverbrush/schema'
+     *
+     * const ok = std.validate({ name: 'Alice', email: 'alice@example.com' });
+     * // { value: { name: 'Alice', email: 'alice@example.com', age: undefined } }
+     *
+     * const fail = std.validate({ name: 'A', email: 'not-an-email' });
+     * // { issues: [{ message: 'minLength' }, { message: 'email' }] }
+     *
+     * // Pass directly to TanStack Form, T3 Env, tRPC, etc.:
+     * // validators: { onChange: UserSchema, onBlur: UserSchema }
+     * ```
+     *
+     * @see https://standardschema.dev/
+     */
+    get ['~standard'](): StandardSchemaV1.Props<ResolvedSchemaType<TResult, TRequired, TNullable>>;
+    /**
+     * Set type of schema explicitly. `notUsed` param is needed only for case when JS is used. E.g. when you
      * can't call method like `schema.hasType<Date>()`, so instead you can call `schema.hasType(new Date())`
      * with the same result.
      */
     abstract hasType<T>(notUsed?: T): any;
     /**
      * Clears type set by call to `.hasType<T>()`, default schema type inference will be used
-     * for schema retuned by this call.
+     * for schema returned by this call.
      */
     abstract clearHasType(): any;
     /**
-     * Protected method used to create an new instance of the Builder
-     * defined by the `props` object. Should be used to instanticate new
+     * Protected method used to create a new instance of the Builder
+     * defined by the `props` object. Should be used to instantiate new
      * builders to keep builder's immutability.
      * @param props arbitrary props object
      */
     protected abstract createFromProps(props: any): this;
+    /**
+     * The string identifier of the schema type (e.g. `'string'`, `'number'`, `'object'`).
+     */
     protected get type(): string;
+    /**
+     * Sets the schema type identifier. Must be a non-empty string.
+     */
     protected set type(value: string);
     /**
      * A list of preprocessors associated with
      * the Builder
      */
-    protected get preprocessors(): Preprocessor<TResult>[];
+    protected get preprocessors(): PreprocessorEntry<TResult>[];
     /**
      * A list of validators associated with
      * the Builder
      */
-    protected get validators(): Validator<TResult>[];
+    protected get validators(): ValidatorEntry<TResult>[];
+    /**
+     * Whether the schema requires a non-null/non-undefined value.
+     */
     protected get isRequired(): TRequired;
+    /**
+     * Whether `null` is an accepted value for this schema.
+     */
+    protected get isNullable(): boolean;
+    /**
+     * Sets the requirement flag. Must be a boolean.
+     */
     protected set isRequired(value: boolean);
-    protected preValidate(
     /**
-     * Object to validate
+     * The error message provider used for the "is required" error.
+     * Exposed for fast-path validation in subclasses.
+     */
+    protected get requiredErrorMessage(): ValidationErrorMessageProvider;
+    /**
+     * Whether this schema has a default value configured via `.default()`.
+     * Exposed for fast-path validation in subclasses.
+     */
+    protected get hasDefault(): boolean;
+    /**
+     * Whether this schema has a catch/fallback value configured via `.catch()`.
+     */
+    protected get hasCatch(): boolean;
+    /**
+     * Resolves the catch/fallback value. If the stored value is a factory function,
+     * it is called to produce the value (useful for mutable fallbacks like `() => []`).
+     */
+    protected resolveCatchValue(): TResult;
+    /**
+     * Whether this schema is marked as readonly.
+     * Type-level only — no runtime enforcement.
+     */
+    protected get isReadonly(): boolean;
+    /**
+     * Resolves the default value. If the stored default is a function,
+     * it is called to produce the value (useful for mutable defaults).
+     */
+    protected resolveDefaultValue(): TResult;
+    /**
+     * Whether `preValidateSync` can be skipped entirely.
+     * True when there are no preprocessors and no validators,
+     * so the only work would be the required check and wrapping
+     * in a noop transaction — which subclasses can do inline.
+     */
+    protected get canSkipPreValidation(): boolean;
+    /**
+     * Whether `null` should count as a required-constraint violation.
+     *
+     * By default `null` is treated the same as `undefined` for the purposes
+     * of the required check — i.e. a required schema rejects both.
+     * Subclasses that may legally receive `null` as a value (e.g.
+     * `UnionSchemaBuilder` when a `NullSchemaBuilder` option is present)
+     * can override this to `false` so that `null` bypasses the required
+     * check and is passed directly to their option-validation logic.
+     *
+     * @protected
+     */
+    protected get isNullRequiredViolation(): boolean;
+    /**
+     * Synchronous version of {@link preValidateAsync}.
+     * Throws at runtime if any preprocessor or validator returns a Promise.
+     *
+     * @param object - the value to pre-validate
+     * @param context - optional validation context settings
+     * @returns a `PreValidationResult` containing the preprocessed transaction, context, and any errors
+     * @throws Error if a preprocessor or validator returns a Promise (use {@link preValidateAsync} instead)
+     */
+    protected preValidateSync(object: any, context?: ValidationContext): PreValidationResult<any, {
+        validatedObject: any;
+    }>;
+    /**
+     * Async version of pre-validation. Runs preprocessors, validators, and the
+     * required/optional check on `object`. Supports async preprocessors,
+     * validators, and error message providers.
+     *
+     * @param object - the value to pre-validate
+     * @param context - optional validation context settings
+     * @returns a `PreValidationResult` containing the preprocessed transaction, context, and any errors
      */
-    object: any, context?: ValidationContext): Promise<PreValidationResult<any, {
+    protected preValidateAsync(object: any, context?: ValidationContext): Promise<PreValidationResult<any, {
+        validatedObject: any;
+    }>>;
+    /**
+     * @deprecated Use {@link preValidateAsync} instead. This alias will be removed in a future version.
+     */
+    protected preValidate(object: any, context?: ValidationContext): Promise<PreValidationResult<any, {
         validatedObject: any;
     }>>;
     /**
@@ -109,27 +642,262 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
          * will be considered as valid).
          */
         isRequired: boolean;
+        /**
+         * If set to `true`, schema values of `null` are considered valid.
+         */
+        isNullable: boolean;
+        /**
+         * If set to `true`, the inferred type is marked as readonly.
+         * Type-level only — no runtime enforcement.
+         */
+        isReadonly: boolean;
         /**
          * Array of preprocessor functions
          */
-        preprocessors: readonly Preprocessor<TResult>[];
+        preprocessors: readonly PreprocessorEntry<TResult>[];
         /**
          * Array of validator functions
          */
-        validators: readonly Validator<TResult>[];
+        validators: readonly ValidatorEntry<TResult>[];
+        /**
+         * Custom error message provider for the 'is required' validation error.
+         */
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        /**
+         * Extension metadata. Stores custom state set by schema extensions.
+         */
+        extensions: {
+            [x: string]: unknown;
+        };
+        /**
+         * Whether a default value (or factory) has been set on this schema.
+         */
+        hasDefault: boolean;
+        /**
+         * The default value or factory function.
+         */
+        defaultValue: TResult | (() => TResult) | undefined;
+        /**
+         * The human-readable description attached to this schema via `.describe()`,
+         * or `undefined` if none was set.
+         */
+        description: string | undefined;
+        /**
+         * The logical name attached to this schema via `.schemaName()`,
+         * or `undefined` if none was set.
+         */
+        schemaName: string | undefined;
+        /**
+         * Whether a catch/fallback value has been set on this schema via `.catch()`.
+         */
+        hasCatch: boolean;
+        /**
+         * The catch/fallback value or factory function set via `.catch()`.
+         */
+        catchValue: TResult | (() => TResult) | undefined;
+        /**
+         * An example value attached to this schema via `.example()`,
+         * or `undefined` if none was set.
+         */
+        example: unknown;
     };
     /**
      * Makes schema optional (consider `null` and `undefined` as valid objects for this schema)
      */
     optional(): any;
+    /**
+     * Makes schema nullable — `null` is accepted as a valid value.
+     *
+     * Unlike `.optional()` which accepts `undefined`, `.nullable()` accepts
+     * `null`. The inferred type changes from `T` to `T | null`. Combine with
+     * `.optional()` to accept both `null` and `undefined`.
+     */
+    nullable(): any;
+    /**
+     * Removes the nullable mark — `null` is no longer accepted as a valid
+     * value. This is the counterpart of `.nullable()`.
+     */
+    notNullable(): any;
+    /**
+     * Sets a default value for this schema. When the input is `undefined`,
+     * the default value is used instead. The default is still validated
+     * against the schema's constraints.
+     *
+     * Accepts either a static value or a factory function (useful for
+     * mutable defaults like `() => new Date()` or `() => []`).
+     *
+     * @example
+     * ```ts
+     * const schema = string().default('hello');
+     * schema.validate(undefined); // { valid: true, object: 'hello' }
+     * schema.validate('world');   // { valid: true, object: 'world' }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Factory function for mutable defaults
+     * const schema = array(string()).default(() => []);
+     * ```
+     */
+    default(value: TResult | (() => TResult)): any;
+    /**
+     * Sets a fallback value for this schema. When validation **fails** for any reason,
+     * the fallback value is returned as a successful result instead of validation errors.
+     *
+     * This is useful for graceful degradation — for example, providing a safe default
+     * when parsing untrusted input that might not conform to the schema.
+     *
+     * Accepts either a static value or a factory function. Factory functions are called
+     * each time the fallback is needed (useful for mutable values like `() => []`).
+     *
+     * Unlike {@link default}, which only fires when the input is `undefined`, `.catch()`
+     * fires on **any** validation failure — type mismatch, constraint violation, etc.
+     *
+     * When `.catch()` is set, {@link parse} and {@link parseAsync} will **never throw**.
+     *
+     * @param value - the fallback value, or a factory function producing the fallback
+     *
+     * @example
+     * ```ts
+     * const schema = string().catch('unknown');
+     * schema.validate(42);        // { valid: true, object: 'unknown' }
+     * schema.validate('hello');   // { valid: true, object: 'hello' }
+     * schema.parse(42);           // 'unknown'  (no throw)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Factory function for mutable fallbacks
+     * const schema = array(string()).catch(() => []);
+     * schema.validate(null);  // { valid: true, object: [] }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Contrast with .default() — default fires only on undefined
+     * const d = string().default('anon');
+     * d.validate(undefined); // { valid: true, object: 'anon' }  ← fires
+     * d.validate(42);        // { valid: false, errors: [...] }  ← does NOT fire
+     *
+     * const c = string().catch('anon');
+     * c.validate(undefined); // { valid: true, object: 'anon' }  ← fires
+     * c.validate(42);        // { valid: true, object: 'anon' }  ← also fires
+     * ```
+     */
+    catch(value: TResult | (() => TResult)): this;
+    /**
+     * Removes the default value set by a previous call to `.default()`.
+     */
+    clearDefault(): any;
+    /**
+     * Attaches a human-readable description to this schema as runtime metadata.
+     *
+     * The description has no effect on validation — it is purely informational.
+     * It is accessible via `.introspect().description` and is emitted as the
+     * `description` field by `toJsonSchema()` from `@cleverbrush/schema-json`.
+     *
+     * Useful for documentation generation, form labels, and AI tool descriptions.
+     *
+     * @example
+     * ```ts
+     * const schema = object({
+     *   name: string().describe('The user\'s full name'),
+     *   age:  number().optional().describe('Age in years'),
+     * }).describe('A user object');
+     *
+     * schema.introspect().description; // 'A user object'
+     * ```
+     */
+    describe(text: string): this;
+    /**
+     * Attaches an example value to this schema instance.
+     *
+     * The example is purely metadata — it has no effect on validation.
+     * It is accessible via `.introspect().example` and is emitted as the
+     * `example` keyword in JSON Schema output and OpenAPI spec generation.
+     *
+     * @example
+     * ```ts
+     * import { string } from '@cleverbrush/schema';
+     *
+     * const Email = string().example('user@example.com');
+     *
+     * Email.introspect().example; // 'user@example.com'
+     * ```
+     */
+    example(value: TResult): this;
+    /**
+     * Attaches a logical name to this schema instance.
+     *
+     * The name is purely metadata — it has no effect on validation. It is
+     * accessible via `.introspect().schemaName` and can be consumed by any
+     * tool that introspects schemas at runtime, such as OpenAPI spec
+     * generators, documentation tools, form libraries, or code generators.
+     *
+     * **Uniqueness** is the responsibility of the consuming tool. Passing the
+     * same constant (same object reference) to multiple consumers is always
+     * safe; how conflicts between different instances with the same name are
+     * handled depends on the tool.
+     *
+     * @example
+     * ```ts
+     * import { object, string, number } from '@cleverbrush/schema';
+     *
+     * export const UserSchema = object({
+     *   id:   number(),
+     *   name: string(),
+     * }).schemaName('User');
+     *
+     * UserSchema.introspect().schemaName; // 'User'
+     * ```
+     */
+    schemaName(name: string): this;
+    /**
+     * Brands the schema with a phantom type tag, preventing structural mixing
+     * of semantically different values at the type level. Zero runtime cost.
+     *
+     * The optional `_name` parameter is only needed when using plain JavaScript
+     * (where generic type parameters are unavailable). In TypeScript, prefer
+     * the generic form: `schema.brand<'Email'>()`.
+     *
+     * @example
+     * ```ts
+     * const Email = string().brand<'Email'>();
+     * const Username = string().brand<'Username'>();
+     * type Email = InferType<typeof Email>;     // string & { readonly [BRAND]: 'Email' }
+     * type Username = InferType<typeof Username>; // string & { readonly [BRAND]: 'Username' }
+     * ```
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): any;
+    /**
+     * Marks the inferred type as readonly. For objects, produces `Readonly<T>`.
+     * For arrays, produces `ReadonlyArray<T>`. Primitives are unchanged.
+     * Type-level only — no runtime enforcement.
+     *
+     * @example
+     * ```ts
+     * const schema = object({ name: string(), age: number() }).readonly();
+     * type T = InferType<typeof schema>; // Readonly<{ name: string; age: number }>
+     * ```
+     *
+     * @example
+     * ```ts
+     * const schema = array(string()).readonly();
+     * type T = InferType<typeof schema>; // ReadonlyArray<string>
+     * ```
+     */
+    readonly(): any;
     /**
      * Makes schema required (consider `null` and `undefined` as invalid objects for this schema)
+     * @param errorMessage - optional custom error message or provider for the 'is required' validation error
      */
-    required(): any;
+    required(errorMessage?: ValidationErrorMessageProvider): any;
     /**
      * Adds a `preprocessor` to a preprocessors list
      */
-    addPreprocessor(preprocessor: Preprocessor<TResult>): this;
+    addPreprocessor(preprocessor: Preprocessor<TResult>, options?: {
+        mutates?: boolean;
+    }): this;
     /**
      * Remove all preprocessors for this schema.
      */
@@ -137,15 +905,53 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
     /**
      * Adds a `validator` to validators list.
      */
-    addValidator(validator: Validator<TResult>): this;
+    addValidator(validator: Validator<TResult>, options?: {
+        mutates?: boolean;
+    }): this;
     /**
      * Remove all validators for this schema.
      */
     clearValidators(): this;
     /**
-     * Perform schema validation on `object`.
+     * Perform synchronous schema validation on `object`.
+     * Throws at runtime if any preprocessor, validator, or error message
+     * provider returns a Promise — use {@link validateAsync} instead.
+     * @internal Override this in subclasses. External callers use {@link validate}.
+     */
+    protected abstract _validate(object: any, context?: ValidationContext): ValidationResult<any>;
+    /**
+     * Perform asynchronous schema validation on `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     * @internal Override this in subclasses. External callers use {@link validateAsync}.
+     */
+    protected abstract _validateAsync(object: any, context?: ValidationContext): Promise<ValidationResult<any>>;
+    /**
+     * Perform synchronous schema validation on `object`.
+     * Throws at runtime if any preprocessor, validator, or error message
+     * provider returns a Promise — use {@link validateAsync} instead.
+     *
+     * If a fallback has been set via {@link catch}, a failed validation result
+     * is replaced by a successful result built from the fallback value, preserving
+     * the specialized result shape (e.g. `getErrorsFor` / `getNestedErrors` methods).
+     */
+    validate(
+    /**
+     * Object to validate
      */
-    abstract validate(
+    object: any, 
+    /**
+     * Optional `ValidationContext` settings
+     */
+    context?: ValidationContext): ValidationResult<any>;
+    /**
+     * Perform asynchronous schema validation on `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     *
+     * If a fallback has been set via {@link catch}, a failed validation result
+     * is replaced by a successful result built from the fallback value, preserving
+     * the specialized result shape (e.g. `getErrorsFor` / `getNestedErrors` methods).
+     */
+    validateAsync(
     /**
      * Object to validate
      */
@@ -154,6 +960,77 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * Optional `ValidationContext` settings
      */
     context?: ValidationContext): Promise<ValidationResult<any>>;
+    /**
+     * Synchronously resolves a `ValidationErrorMessageProvider` to a string.
+     * Throws if the provider function returns a Promise.
+     *
+     * @param provider - the error message provider (string or sync function)
+     * @param seenValue - the value that caused the validation error
+     * @returns the resolved error message string
+     * @throws Error if the provider returns a Promise (use {@link getValidationErrorMessage} with {@link validateAsync})
+     */
+    protected getValidationErrorMessageSync(provider: ValidationErrorMessageProvider<any>, seenValue: TResult): string;
+    /**
+     * Resolves a `ValidationErrorMessageProvider` to a string error message.
+     * Handles both string providers and function providers (sync or async).
+     *
+     * @param provider - the error message provider (string or function)
+     * @param seenValue - the value that caused the validation error
+     * @returns the resolved error message string
+     */
+    protected getValidationErrorMessage(provider: ValidationErrorMessageProvider<any>, seenValue: TResult): Promise<string>;
+    /**
+     * Ensures a `ValidationErrorMessageProvider` is valid.
+     * If `provider` is `undefined`, falls back to `defaultValue`.
+     * Function providers are bound to `this` for access to schema state.
+     *
+     * @param provider - the provider to validate, or `undefined`
+     * @param defaultValue - fallback provider when `provider` is not supplied
+     * @returns a valid `ValidationErrorMessageProvider`
+     */
+    protected assureValidationErrorMessageProvider(provider: ValidationErrorMessageProvider<any> | undefined, defaultValue: ValidationErrorMessageProvider<any>): ValidationErrorMessageProvider<any>;
+    /**
+     * Sets extension metadata by key. Returns a new schema instance with the
+     * extension data stored. The data survives fluent chaining.
+     * @internal Used by extension authors inside `defineExtension()` callbacks.
+     */
+    withExtension(key: string, value: unknown): this;
+    /**
+     * Retrieves extension metadata by key.
+     * @internal Used by extension authors inside `defineExtension()` callbacks.
+     */
+    getExtension(key: string): unknown;
+    /**
+     * Synchronously validates the value and returns it if valid.
+     * Throws a {@link SchemaValidationError} if validation fails.
+     *
+     * @param object - the value to parse
+     * @param context - optional validation context
+     * @returns the validated value
+     * @throws SchemaValidationError if validation fails
+     * @throws Error if the schema contains async preprocessors, validators, or error message providers
+     */
+    parse(object: any, context?: ValidationContext): TResult;
+    /**
+     * Asynchronously validates the value and returns it if valid.
+     * Throws a {@link SchemaValidationError} if validation fails.
+     *
+     * @param object - the value to parse
+     * @param context - optional validation context
+     * @returns the validated value
+     * @throws SchemaValidationError if validation fails
+     */
+    parseAsync(object: any, context?: ValidationContext): Promise<TResult>;
+    /**
+     * Alias for {@link validate}. Synchronously validates and returns a result object.
+     * Provided for familiarity with the zod API.
+     */
+    safeParse(object: any, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Alias for {@link validateAsync}. Asynchronously validates and returns a result object.
+     * Provided for familiarity with the zod API.
+     */
+    safeParseAsync(object: any, context?: ValidationContext): Promise<ValidationResult<TResult>>;
     protected constructor(props: SchemaBuilderProps<TResult>);
 }
 export {};