@cleverbrush/schema 0.0.0-beta-20260410073748

package/dist/builders/DateSchemaBuilder.d.ts

@@ -0,0 +1,277 @@
+import { type BRAND, type PreprocessorEntry, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult, type ValidatorEntry } from './SchemaBuilder.js';
+type DateSchemaBuilderCreateProps<T = Date, R extends boolean = true> = Partial<ReturnType<DateSchemaBuilder<T, R, any>['introspect']>>;
+/**
+ * Allows to create Date schema. It can be required or optional.
+ * It can be restricted to be: equal to a certain value, in future, in past, in a certain range.
+ * Supports parsing from JSON string and UNIX epoch (using preprocessors).
+ *
+ * **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 date | date()} function instead.
+ *
+ * @example ```ts
+ * const date = new Date(2020, 0, 2);
+ * const schema = date().min(new Date(2020, 0, 1));
+ * const result = schema.validate(date);
+ * // result.valid === true
+ * // result.object === date
+ * ```
+ *
+ * @example ```ts
+ * const schema = date();
+ * const result = schema.validate('2020-01-01');
+ * // result.valid === false
+ * // result.errors[0].message === 'is expected to be a date'
+ * ```
+ *
+ * @example ```ts
+ * const schema = date().parseFromJson();
+ * const result = schema.validate('2020-01-01T00:00:00.000Z');
+ * // result.valid === true
+ * // result.object is equal to corresponding Date object
+ * ```
+ *
+ * @example ```ts
+ * const schema = date().parseFromEpoch();
+ * const result = schema.validate(1577836800000);
+ * // result.valid === true
+ * // result.object is equal to corresponding Date object
+ * ```
+ *
+ * @see {@link date}
+ */
+export declare class DateSchemaBuilder<TResult = Date, 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: DateSchemaBuilderCreateProps): DateSchemaBuilder<Date, true, false, false, {}>;
+    protected constructor(props: DateSchemaBuilderCreateProps);
+    introspect(): {
+        /**
+         * Min valid value (if defined).
+         */
+        min: Date | undefined;
+        /**
+         * Min value validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        minValidationErrorMessageProvider: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired, false, false, {}>>;
+        /**
+         * Max valid value (if defined).
+         */
+        max: Date | undefined;
+        /**
+         * Max value validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        maxValidationErrorMessageProvider: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired, false, false, {}>>;
+        /**
+         * Make sure that date is in future. `false` by default.
+         */
+        ensureIsInFuture: boolean;
+        /**
+         * Ensure in future validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        ensureIsInFutureValidationErrorMessageProvider: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired, false, false, {}>>;
+        /**
+         * Make sure that date is in past. `false` by default.
+         */
+        ensureIsInPast: boolean;
+        /**
+         * Ensure in past validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        ensureIsInPastValidationErrorMessageProvider: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired, false, false, {}>>;
+        /**
+         * If set, restrict date to be equal to a certain value.
+         */
+        equalsTo: Date | undefined;
+        /**
+         * Equals to validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        equalsToValidationErrorMessageProvider: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired, false, false, {}>>;
+        /**
+         * If set, schema will try to parse date from the UNIX epoch (number).
+         * `false` by default.
+         */
+        parseFromEpoch: boolean;
+        /**
+         * If set, schema will try to parse date from JSON string.
+         * `false` by default.
+         */
+        parseFromJson: boolean;
+        /**
+         * Array of preprocessor functions
+         */
+        preprocessors: PreprocessorEntry<TResult>[];
+        /**
+         * Array of validator functions
+         */
+        validators: ValidatorEntry<TResult>[];
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+    };
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): DateSchemaBuilder<T, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): DateSchemaBuilder<Date, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /** {@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 Date 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 Date 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>>;
+    /**
+     * @hidden
+     */
+    protected createFromProps<T, TReq extends boolean>(props: DateSchemaBuilderCreateProps<T, TReq>): this;
+    /**
+     * Restricts Date to be equal to `value`.
+     */
+    equals<T extends Date>(value: T, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired>>): DateSchemaBuilder<T, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Clears `equals()` call.
+     */
+    clearEquals(): DateSchemaBuilder<Date, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): DateSchemaBuilder<TResult, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): DateSchemaBuilder<TResult, false, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): DateSchemaBuilder<TResult, true, TNullable, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): DateSchemaBuilder<TResult, TRequired, TNullable, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): DateSchemaBuilder<TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<Date>` — prevents mutation of
+     * Date methods like `setFullYear()` at the type level. Validation
+     * behaviour is unchanged.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): DateSchemaBuilder<Readonly<TResult>, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Accept only dates in the future.
+     */
+    isInFuture(
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired>>): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Cancel `isInFuture()` call.
+     */
+    clearIsInFuture(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Accept only dates in the past.
+     */
+    isInPast(
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired>>): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Cancel `isInPast()` call.
+     */
+    clearIsInPast(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Set minimal valid Date value for schema.
+     */
+    min(minValue: Date, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired>>): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Clear `min()` call.
+     */
+    clearMin(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Set maximal valid Date value for schema.
+     */
+    max(maxValue: Date, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<DateSchemaBuilder<TResult, TRequired>>): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Clear `max()` call.
+     */
+    clearMax(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Accepts JSON string as a valid Date.
+     * String must be in ISO format and will be parsed using `JSON.parse()`.
+     */
+    acceptJsonString(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Cancel `acceptJsonString()` call.
+     */
+    doNotAcceptJsonString(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Accepts epoch number as a valid Date.
+     * Epoch number will be parsed using `new Date(epoch)`.
+     */
+    acceptEpoch(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Cancel `acceptEpoch()` call.
+     */
+    doNotAcceptEpoch(): DateSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): DateSchemaBuilder<TResult, TRequired, true, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): DateSchemaBuilder<TResult, TRequired, false, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Creates a Date schema.
+ */
+export declare const date: () => DateSchemaBuilder<Date, true, false, false, {}>;
+export {};

package/dist/builders/DateSchemaBuilder.js

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

package/dist/builders/DateSchemaBuilder.js.map

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

package/dist/builders/ExternSchemaBuilder.d.ts

@@ -0,0 +1,200 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type BRAND, SchemaBuilder, SYMBOL_HAS_PROPERTIES, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type ExternSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<ExternSchemaBuilder<any, R>['introspect']>> & {
+    standardSchema: StandardSchemaV1;
+};
+/**
+ * Schema builder that wraps an external
+ * [Standard Schema v1](https://standardschema.dev/) compatible schema
+ * (e.g. Zod, Valibot, ArkType) into a `@cleverbrush/schema` builder.
+ *
+ * This enables cross-library schema composition — you can use a Zod schema
+ * as a property inside a `@cleverbrush/schema` object schema, and the
+ * inferred TypeScript type will be correct.
+ *
+ * Validation is delegated entirely to the external schema's
+ * `['~standard'].validate()` method. Standard Schema issues are mapped to
+ * `@cleverbrush/schema` `ValidationError` objects, with any issue paths
+ * formatted as dotted prefixes (e.g. `"address.city: must be a string"`).
+ *
+ * When used inside an `object()` schema, the property descriptor tree is
+ * built dynamically (via Proxy) from the external schema's output type,
+ * so `getErrorsFor(t => t.order.id)` works without any additional
+ * configuration.
+ *
+ * **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 the {@link extern | extern()} factory function instead.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { object, date, extern, InferType } from '@cleverbrush/schema';
+ *
+ * const zodUser = z.object({ first: z.string(), last: z.string() });
+ *
+ * const order = object({
+ *   user: extern(zodUser),
+ *   date: date(),
+ * });
+ *
+ * type Order = InferType<typeof order>;
+ * // { user: { first: string; last: string }; date: Date }
+ * ```
+ *
+ * @see {@link extern}
+ */
+export declare class ExternSchemaBuilder<TStandardSchema extends StandardSchemaV1 = StandardSchemaV1, TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? StandardSchemaV1.InferOutput<TStandardSchema> : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * Always `true` for extern schemas — enables Proxy-based property
+     * descriptor trees and nested error propagation in
+     * `ObjectSchemaBuilder`.
+     */
+    readonly [SYMBOL_HAS_PROPERTIES] = true;
+    /**
+     * @hidden
+     */
+    static create(props: ExternSchemaBuilderCreateProps<any>): ExternSchemaBuilder<StandardSchemaV1<unknown, unknown>, true, false, undefined, false, {}, unknown>;
+    protected constructor(props: ExternSchemaBuilderCreateProps<TRequired>);
+    /**
+     * Returns the wrapped Standard Schema instance.
+     */
+    get standardSchema(): TStandardSchema;
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): ExternSchemaBuilder<TStandardSchema, true, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): ExternSchemaBuilder<TStandardSchema, TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation by delegating to the external
+     * Standard Schema's `validate()` method.
+     *
+     * If the external schema returns a `Promise` (async validation),
+     * this method throws — use {@link validateAsync} instead.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Performs async validation by delegating to the external
+     * Standard Schema's `validate()` method. Supports external schemas
+     * that return a `Promise` from their `validate()`.
+     */
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected createFromProps<TReq extends boolean>(props: ExternSchemaBuilderCreateProps<TReq>): this;
+    /**
+     * Returns a snapshot of the builder's internal state.
+     * Includes the wrapped `standardSchema` reference.
+     */
+    introspect(): {
+        standardSchema: TStandardSchema;
+        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;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+    };
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): ExternSchemaBuilder<TStandardSchema, true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): ExternSchemaBuilder<TStandardSchema, false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): ExternSchemaBuilder<TStandardSchema, true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): ExternSchemaBuilder<TStandardSchema, TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): ExternSchemaBuilder<TStandardSchema, TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<T>`. Sets the `isReadonly`
+     * introspection flag for tooling consistency.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): ExternSchemaBuilder<TStandardSchema, TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): ExternSchemaBuilder<TStandardSchema, TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): ExternSchemaBuilder<TStandardSchema, TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Wraps an external [Standard Schema v1](https://standardschema.dev/)
+ * compatible schema into a `@cleverbrush/schema` builder.
+ *
+ * This enables cross-library schema composition — use schemas from Zod,
+ * Valibot, ArkType, or any Standard Schema v1 compliant library as
+ * properties inside `@cleverbrush/schema` object schemas with full type
+ * inference.
+ *
+ * @param standardSchema - A Standard Schema v1 compliant schema instance
+ *   (any object that exposes a `['~standard']` property with `version: 1`
+ *   and a `validate` function).
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { object, date, extern, InferType } from '@cleverbrush/schema';
+ *
+ * const zodUser = z.object({ first: z.string(), last: z.string() });
+ *
+ * const order = object({
+ *   user: extern(zodUser),
+ *   date: date(),
+ * });
+ *
+ * type Order = InferType<typeof order>;
+ * // { user: { first: string; last: string }; date: Date }
+ *
+ * order.validate({
+ *   user: { first: 'Alice', last: 'Smith' },
+ *   date: new Date(),
+ * }); // { valid: true, object: { user: …, date: … } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional external schema
+ * const schema = extern(zodUser).optional();
+ * schema.validate(undefined); // valid
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Inside an array
+ * import { array, extern } from '@cleverbrush/schema';
+ * const users = array(extern(zodUser));
+ * ```
+ */
+export declare const extern: <T extends StandardSchemaV1>(standardSchema: T) => ExternSchemaBuilder<T, true>;
+export {};

package/dist/builders/ExternSchemaBuilder.js

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

package/dist/builders/ExternSchemaBuilder.js.map

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