@cleverbrush/schema 2.0.0 → 3.0.0

package/dist/builders/ParseStringSchemaBuilder.d.ts

@@ -0,0 +1,204 @@
+import { ObjectSchemaBuilder } from './ObjectSchemaBuilder.js';
+import { type BRAND, type InferType, type PropertyDescriptor, type PropertyDescriptorInner, type PropertyDescriptorTree, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+/** Descriptor for a single interpolation segment captured at creation time. */
+type SegmentDef = {
+    /** The property schema for this segment. */
+    schema: SchemaBuilder<any, any, any, any, any>;
+    /** Dot-separated property path (e.g. `'order.id'`) — used in error messages. */
+    path: string;
+    /** The property descriptor inner — used to set parsed values on the result object. */
+    descriptor: PropertyDescriptorInner<any, any, any>;
+};
+/** Internal data captured by the `$template` tagged-template invocation. */
+type ParseStringTemplateDefinition = {
+    /** Literal string fragments from the tagged template. */
+    literals: readonly string[];
+    /** One segment per interpolation expression, in order. */
+    segments: readonly SegmentDef[];
+};
+/**
+ * The typed tagged-template function passed to the `parseString`
+ * callback. Template expressions must be property-selector lambdas that
+ * navigate the {@link PropertyDescriptorTree} of the object schema.
+ *
+ * Only properties whose inferred type extends `string | number | boolean | Date`
+ * are selectable — nested `ObjectSchemaBuilder` children are navigable but
+ * not themselves endpoints.
+ */
+export type ParseStringTemplateTag<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = (strings: TemplateStringsArray, ...selectors: Array<(tree: PropertyDescriptorTree<TSchema, TSchema, string | number | boolean | Date>) => PropertyDescriptor<TSchema, any, any>>) => ParseStringTemplateDefinition;
+type ParseStringSchemaBuilderCreateProps<T = any, R extends boolean = true> = Partial<ReturnType<ParseStringSchemaBuilder<T, R>['introspect']>>;
+/**
+ * Validates a string against a template pattern and parses it
+ * into a strongly-typed object.
+ *
+ * Created via the {@link parseString} factory:
+ *
+ * ```ts
+ * const RouteSchema = parseString(
+ *   object({ userId: string().uuid(), id: number() }),
+ *   $t => $t`/orders/${t => t.id}/${t => t.userId}`
+ * );
+ *
+ * const result = RouteSchema.validate('/orders/42/550e8400-...');
+ * // result.object === { id: 42, userId: '550e8400-...' }
+ * ```
+ *
+ * @see {@link parseString}
+ */
+export declare class ParseStringSchemaBuilder<TResult = any, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: ParseStringSchemaBuilderCreateProps): ParseStringSchemaBuilder<any, true, false, false, {}>;
+    protected constructor(props: ParseStringSchemaBuilderCreateProps);
+    /**
+     * Return a snapshot of this builder's configuration.
+     *
+     * Includes all base-class fields plus:
+     * - `objectSchema` — the object schema defining the result shape.
+     * - `templateDefinition` — the parsed template (literals and selector segments).
+     */
+    introspect(): {
+        /** The object schema defining the result shape. */
+        objectSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+        /** The template definition (literals + segments). */
+        templateDefinition: ParseStringTemplateDefinition;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        schemaName: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
+    };
+    /**
+     * Builds a string from the template by substituting parameter values.
+     *
+     * This is the reverse of {@link validate}: where `validate` parses a
+     * string into a typed object, `serialize` takes a params object and
+     * produces the string.
+     *
+     * @param params - An object matching the template's parsed result type.
+     *   Nested properties are resolved via dot-paths (e.g. `order.id`).
+     *   Values are coerced to strings via `String()`.
+     * @returns The reconstructed string with all segments replaced.
+     * @throws {Error} If a required parameter is missing (`undefined`).
+     *
+     * @example
+     * ```ts
+     * const Route = parseString(
+     *   object({ id: number().coerce() }),
+     *   $t => $t`/todos/${t => t.id}`
+     * );
+     *
+     * Route.serialize({ id: 42 }); // '/todos/42'
+     * ```
+     */
+    serialize(params: TResult): string;
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: string, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: string, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected _validate(object: any, context?: ValidationContext): ValidationResult<TResult>;
+    protected _validateAsync(object: any, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): ParseStringSchemaBuilder<T, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): ParseStringSchemaBuilder<any, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): ParseStringSchemaBuilder<TResult, TRequired, true, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): ParseStringSchemaBuilder<TResult, TRequired, false, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): ParseStringSchemaBuilder<TResult, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): ParseStringSchemaBuilder<TResult, false, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): ParseStringSchemaBuilder<TResult, true, TNullable, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): ParseStringSchemaBuilder<TResult, TRequired, TNullable, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): ParseStringSchemaBuilder<TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    readonly(): ParseStringSchemaBuilder<Readonly<TResult>, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    protected createFromProps<T, TReq extends boolean>(props: ParseStringSchemaBuilderCreateProps<T, TReq>): this;
+}
+/**
+ * Creates a parse-string schema that validates a string against a
+ * template pattern and parses it into a strongly-typed object.
+ *
+ * The first argument defines the result shape via `object(...)`, and the
+ * second argument is a callback receiving a typed `$template` tagged-template
+ * function whose template expressions are type-safe property selectors.
+ *
+ * @example
+ * ```ts
+ * const RouteSchema = parseString(
+ *   object({
+ *     userId: string().uuid(),
+ *     id: number()
+ *   }),
+ *   $t => $t`/orders/${t => t.id}/${t => t.userId}`
+ * );
+ *
+ * const result = RouteSchema.validate('/orders/42/550e8400-e29b-41d4-a716-446655440000');
+ * // result.valid === true
+ * // result.object === { id: 42, userId: '550e8400-e29b-41d4-a716-446655440000' }
+ *
+ * type Route = InferType<typeof RouteSchema>;
+ * // { id: number; userId: string }
+ * ```
+ *
+ * @example Nested objects
+ * ```ts
+ * const schema = parseString(
+ *   object({
+ *     order: object({ id: number() }),
+ *     user: object({ name: string() })
+ *   }),
+ *   $t => $t`/orders/${t => t.order.id}/by/${t => t.user.name}`
+ * );
+ * ```
+ *
+ * @param objectSchema - An `ObjectSchemaBuilder` defining the result type and
+ *   per-property validation schemas.
+ * @param templateBuilder - Callback receiving the typed `$template`
+ *   tagged-template function. Must return the result of invoking `$template`.
+ * @returns A `ParseStringSchemaBuilder` whose `validate()` accepts a
+ *   string and whose `InferType` is the object schema's inferred type.
+ */
+export declare function parseString<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(objectSchema: TSchema, templateBuilder: ($template: ParseStringTemplateTag<TSchema>) => ParseStringTemplateDefinition): ParseStringSchemaBuilder<InferType<TSchema>>;
+export {};

package/dist/builders/ParseStringSchemaBuilder.js

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-DY7J6RNN.js";import"../chunk-K6Z47OQY.js";import"../chunk-3JMDGYDT.js";export{a as ParseStringSchemaBuilder,b as parseString};
+//# sourceMappingURL=ParseStringSchemaBuilder.js.map

package/dist/builders/ParseStringSchemaBuilder.js.map

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

package/dist/builders/PromiseSchemaBuilder.d.ts

@@ -0,0 +1,213 @@
+import { type BRAND, type InferType, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type PromiseSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<PromiseSchemaBuilder<R>['introspect']>>;
+/**
+ * Schema builder for promise-like values. Validates that a value is a
+ * thenable (for example, an actual `Promise` or any object with a `then`
+ * function) and optionally carries a typed resolved-value schema so that
+ * the inferred TypeScript type is `Promise<T>` instead of `Promise<any>`.
+ *
+ * **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 promise | promise()} function instead.
+ *
+ * @example Basic validation
+ * ```ts
+ * const schema = promise();
+ * const result = schema.validate(Promise.resolve(42));
+ * // result.valid === true
+ * ```
+ *
+ * @example Optional promise schema
+ * ```ts
+ * const schema = promise().optional();
+ * const result = schema.validate(undefined);
+ * // result.valid === true
+ * // result.object === undefined
+ * ```
+ *
+ * @example Typed resolved value
+ * ```ts
+ * import { promise, string, InferType } from '@cleverbrush/schema';
+ *
+ * const schema = promise(string());
+ *
+ * type PromiseResult = InferType<typeof schema>;
+ * // → Promise<string>
+ *
+ * // Introspect at runtime
+ * const info = schema.introspect();
+ * // info.resolvedType → StringSchemaBuilder
+ * ```
+ *
+ * @see {@link promise}
+ */
+export declare class PromiseSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResolvedTypeSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, TResult = TExplicitType extends undefined ? TResolvedTypeSchema extends SchemaBuilder<any, any, any, any, any> ? Promise<InferType<TResolvedTypeSchema>> : Promise<any> : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: PromiseSchemaBuilderCreateProps<any>): PromiseSchemaBuilder<true, false, undefined, false, {}, undefined, Promise<any>>;
+    protected constructor(props: PromiseSchemaBuilderCreateProps<TRequired>);
+    /**
+     * @hidden
+     */
+    hasType<T>(_notUsed?: T): PromiseSchemaBuilder<true, TNullable, T, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearHasType(): PromiseSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * Returns an object describing the current schema configuration.
+     *
+     * In addition to the base fields exposed by {@link SchemaBuilder.introspect},
+     * the following field is included:
+     *
+     * - `resolvedType` — the {@link SchemaBuilder} set via {@link hasResolvedType},
+     *   or `undefined` when no resolved-type schema has been configured.
+     *
+     * @example
+     * ```ts
+     * const schema = promise(string());
+     *
+     * const info = schema.introspect();
+     * // info.resolvedType instanceof StringSchemaBuilder
+     * ```
+     */
+    introspect(): {
+        /** Resolved-value schema set via {@link hasResolvedType}, or `undefined` if not set. */
+        resolvedType: SchemaBuilder<any, any, any, any, any> | undefined;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        schemaName: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
+    };
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation of the schema over `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Performs async validation of the schema over `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected createFromProps<TReq extends boolean>(props: PromiseSchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): PromiseSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): PromiseSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): PromiseSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): PromiseSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): PromiseSchemaBuilder<TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<Promise<T>>`. Sets the
+     * `isReadonly` introspection flag for tooling consistency.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): PromiseSchemaBuilder<TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): PromiseSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): PromiseSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions, TResolvedTypeSchema> & TExtensions;
+    /**
+     * Sets the schema for the resolved value of the `Promise`.
+     *
+     * The inferred TypeScript type becomes `Promise<T>` where `T` is the type
+     * produced by `schema`. The schema is accessible at runtime via
+     * `introspect().resolvedType`.
+     *
+     * @param schema - The schema describing the resolved value of the promise.
+     *
+     * @example
+     * ```ts
+     * const schema = promise().hasResolvedType(string());
+     *
+     * type Resolved = InferType<typeof schema>;
+     * // → Promise<string>
+     *
+     * schema.introspect().resolvedType; // StringSchemaBuilder
+     * ```
+     */
+    hasResolvedType<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): PromiseSchemaBuilder<TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TSchema> & TExtensions;
+}
+/**
+ * Creates a `promise` schema that validates the value is a JavaScript `Promise`.
+ *
+ * The returned builder is immutable and fully chainable. Pass an optional
+ * schema to {@link promise} to annotate the type of the resolved value —
+ * the inferred TypeScript type becomes `Promise<T>`.
+ *
+ * Alternatively, call {@link PromiseSchemaBuilder.hasResolvedType} on the
+ * returned builder to set or replace the resolved-value schema at any point
+ * in the chain.
+ *
+ * @param resolvedTypeSchema - Optional schema describing the resolved value of
+ *   the promise. When provided, `InferType<typeof schema>` becomes
+ *   `Promise<InferType<typeof resolvedTypeSchema>>`.
+ *
+ * @returns A new {@link PromiseSchemaBuilder} with `isRequired` set to `true`.
+ *
+ * @example
+ * ```ts
+ * import { promise, string, number, InferType } from '@cleverbrush/schema';
+ *
+ * // Untyped — accepts any Promise
+ * const anyPromise = promise();
+ * type AnyPromise = InferType<typeof anyPromise>; // Promise<any>
+ *
+ * anyPromise.validate(Promise.resolve(42));  // { valid: true }
+ * anyPromise.validate('not a promise' as any); // { valid: false }
+ *
+ * // Typed resolved value
+ * const stringPromise = promise(string());
+ * type StringPromise = InferType<typeof stringPromise>; // Promise<string>
+ *
+ * // Optional promise
+ * const optPromise = promise(number()).optional();
+ * type OptPromise = InferType<typeof optPromise>; // Promise<number> | undefined
+ * ```
+ *
+ * @see {@link PromiseSchemaBuilder}
+ */
+export declare function promise(): PromiseSchemaBuilder<true>;
+export declare function promise<TSchema extends SchemaBuilder<any, any, any, any, any>>(resolvedTypeSchema: TSchema): PromiseSchemaBuilder<true, false, undefined, false, {}, TSchema>;
+export {};

package/dist/builders/PromiseSchemaBuilder.js

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-WDMJBGBD.js";import"../chunk-3JMDGYDT.js";export{a as PromiseSchemaBuilder,b as promise};
+//# sourceMappingURL=PromiseSchemaBuilder.js.map

package/dist/builders/PromiseSchemaBuilder.js.map

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

package/dist/builders/RecordSchemaBuilder.d.ts

@@ -250,8 +250,10 @@ export declare class RecordSchemaBuilder<TKeySchema extends StringSchemaBuilder<
         hasDefault: boolean;
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
     };
     /**
      * Core sync validation. {@inheritDoc SchemaBuilder.validate}

package/dist/builders/RecordSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-IJ6FO37G.js";import"../chunk-CTP4RHDG.js";export{a as RecordSchemaBuilder,b as record};
+import{a,b}from"../chunk-ZFI27R3L.js";import"../chunk-3JMDGYDT.js";export{a as RecordSchemaBuilder,b as record};
 //# sourceMappingURL=RecordSchemaBuilder.js.map

package/dist/builders/SchemaBuilder.d.ts

@@ -48,9 +48,30 @@ export type InferType<T> = T extends {
 } ? 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 = {
     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
@@ -170,6 +191,8 @@ export type SchemaBuilderProps<T> = {
     catchValue?: T | (() => T);
     hasCatch?: boolean;
     description?: string;
+    schemaName?: string;
+    example?: unknown;
 };
 export type ValidationContext<TSchema extends SchemaBuilder<any, any, any, any> = SchemaBuilder<any, any, any, any>> = {
     /**
@@ -348,6 +371,19 @@ export type PropertyDescriptorInner<TSchema extends ObjectSchemaBuilder<any, any
      */
     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
@@ -646,6 +682,11 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
          * 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()`.
          */
@@ -654,6 +695,11 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
          * 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)
@@ -763,6 +809,49 @@ export declare abstract class SchemaBuilder<TResult = any, TRequired extends boo
      * ```
      */
     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.

package/dist/builders/StringSchemaBuilder.d.ts

@@ -135,8 +135,10 @@ export declare class StringSchemaBuilder<TResult = string, TRequired extends boo
         hasDefault: boolean;
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
     };
     /**
      * @inheritdoc

package/dist/builders/StringSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-FWUEUW2N.js";import"../chunk-CTP4RHDG.js";export{a as StringSchemaBuilder,b as string};
+import{a,b}from"../chunk-YQZHDMRF.js";import"../chunk-3JMDGYDT.js";export{a as StringSchemaBuilder,b as string};
 //# sourceMappingURL=StringSchemaBuilder.js.map

package/dist/builders/TupleSchemaBuilder.d.ts

@@ -169,8 +169,10 @@ export declare class TupleSchemaBuilder<TElements extends readonly SchemaBuilder
         hasDefault: boolean;
         defaultValue: TResult | (() => TResult) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: TResult | (() => TResult) | undefined;
+        example: unknown;
     };
     /**
      * Sets a schema that all elements beyond the fixed positions must satisfy.

package/dist/builders/TupleSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-S5TC6NSU.js";import"../chunk-CTP4RHDG.js";export{a as TupleSchemaBuilder,b as tuple};
+import{a,b}from"../chunk-QARCEYGO.js";import"../chunk-3JMDGYDT.js";export{a as TupleSchemaBuilder,b as tuple};
 //# sourceMappingURL=TupleSchemaBuilder.js.map

package/dist/builders/UnionSchemaBuilder.d.ts

@@ -101,6 +101,12 @@ export declare class UnionSchemaBuilder<TOptions extends readonly SchemaBuilder<
          * Array of schemas participating in the union.
          */
         options: TOptions;
+        /**
+         * When the union is a discriminated union (all branches are objects
+         * sharing a required property with unique literal values), this is
+         * the name of that property. `undefined` otherwise.
+         */
+        discriminatorPropertyName: string | undefined;
         type: string;
         isRequired: boolean;
         isNullable: boolean;
@@ -114,8 +120,10 @@ export declare class UnionSchemaBuilder<TOptions extends readonly SchemaBuilder<
         hasDefault: boolean;
         defaultValue: (TExplicitType extends undefined ? SchemaArrayToUnion<TOptions> : TExplicitType) | (() => TExplicitType extends undefined ? SchemaArrayToUnion<TOptions> : TExplicitType) | undefined;
         description: string | undefined;
+        schemaName: string | undefined;
         hasCatch: boolean;
         catchValue: (TExplicitType extends undefined ? SchemaArrayToUnion<TOptions> : TExplicitType) | (() => TExplicitType extends undefined ? SchemaArrayToUnion<TOptions> : TExplicitType) | undefined;
+        example: unknown;
     };
     /**
      * Null is a legitimate JavaScript value that a union option (e.g.

package/dist/builders/UnionSchemaBuilder.js

@@ -1,2 +1,2 @@
-import{a,b}from"../chunk-ZUPYV5TI.js";import"../chunk-CTP4RHDG.js";export{a as UnionSchemaBuilder,b as union};
+import{a,b}from"../chunk-WQDYWDOE.js";import"../chunk-3JMDGYDT.js";export{a as UnionSchemaBuilder,b as union};
 //# sourceMappingURL=UnionSchemaBuilder.js.map