@cleverbrush/schema 1.1.11 → 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/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>;
+    };
+}