@cleverbrush/schema 1.1.11 → 2.0.0

package/dist/builders/StringSchemaBuilder.js

@@ -1,414 +1,2 @@
-import { SchemaBuilder } from './SchemaBuilder.js';
-/**
- * Allows to define a schema for a string. It can be: required or optional,
- * restricted to be equal to a certain value, restricted to have a certain
- * length, restricted to start with a certain value, restricted to end with
- * a certain value, restricted to match a certain regular expression.
- *
- * **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 string | string()} function instead.
- *
- * @example ```ts
- * const schema = string().equals('hello');
- * const result = await schema.validate('hello');
- * // result.valid === true
- * // result.object === 'hello'
- * ```
- *
- * @example ```ts
- * const schema = string().equals('hello');
- * const result = await schema.validate('world');
- * // result.valid === false
- * // result.errors[0].message === "is expected to be equal to 'hello'"
- * ```
- *
- * @example ```ts
- * const schema = string().minLength(5);
- * const result = await schema.validate('hello');
- * // result.valid === true
- * // result.object === 'hello'
- * ```
- *
- * @example ```ts
- * const schema = string().minLength(5);
- * const result = await schema.validate('hi');
- * // result.valid === false
- * // result.errors[0].message === 'is expected to have a length of at least 5'
- * ```
- *
- * @example ```ts
- * const schema = string().minLength(2).maxLength(5);
- * const result = await schema.validate('yes');
- * // result.valid === true
- * // result.object === 'yes'
- * ```
- *
- * @example ```ts
- * const schema = string('no');
- * const result = await schema.validate('yes');
- * // result.valid === false
- * // result.errors[0].message === "is expected to be equal to 'no'"
- * ```
- *
- * @see {@link string}
- */
-export class StringSchemaBuilder extends SchemaBuilder {
-    #minLength;
-    #maxLength;
-    #equalsTo;
-    #startsWith;
-    #endsWith;
-    #matches;
-    static create(props) {
-        return new StringSchemaBuilder({
-            type: 'string',
-            ...props
-        });
-    }
-    constructor(props) {
-        super(props);
-        if (typeof props.minLength === 'number') {
-            this.#minLength = props.minLength;
-        }
-        if (typeof props.maxLength === 'number') {
-            this.#maxLength = props.maxLength;
-        }
-        if (typeof props.equalsTo === 'string' ||
-            typeof props.equalsTo === 'undefined') {
-            this.#equalsTo = props.equalsTo;
-        }
-        if (typeof props.startsWith === 'string' &&
-            props.startsWith.length > 0) {
-            this.#startsWith = props.startsWith;
-        }
-        if (typeof props.endsWith === 'string' && props.endsWith.length > 0) {
-            this.#endsWith = props.endsWith;
-        }
-        if (props.matches instanceof RegExp) {
-            this.#matches = props.matches;
-        }
-    }
-    introspect() {
-        return {
-            ...super.introspect(),
-            /**
-             * Min length of the string (if defined).
-             */
-            minLength: this.#minLength,
-            /**
-             * Max length of the string (if defined).
-             */
-            maxLength: this.#maxLength,
-            /**
-             * If set, restrict object to be equal to a certain value.
-             */
-            equalsTo: this.#equalsTo,
-            /**
-             * If set, restrict string to start with a certain value.
-             */
-            startsWith: this.#startsWith,
-            /**
-             * If set, restrict string to end with a certain value.
-             */
-            endsWith: this.#endsWith,
-            /**
-             * If set, restrict string to match a certain regular expression.
-             */
-            matches: this.#matches,
-            /**
-             * Array of preprocessor functions
-             */
-            preprocessors: this.preprocessors,
-            /**
-             * Array of validator functions
-             */
-            validators: this.validators
-        };
-    }
-    /**
-     * @hidden
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    hasType(notUsed) {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * @hidden
-     */
-    clearHasType() {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * Performs validion of string schema over `object`.
-     * @param context Optional `ValidationContext` settings.
-     */
-    async validate(object, context) {
-        const superResult = await super.preValidate(object, context);
-        const { valid, context: prevalidationContext, transaction: preValidationTransaction, errors } = superResult;
-        const { path } = prevalidationContext;
-        if (!valid) {
-            return {
-                valid,
-                errors
-            };
-        }
-        const { object: { validatedObject: objToValidate } } = preValidationTransaction;
-        if ((typeof objToValidate === 'undefined' || objToValidate === null) &&
-            this.isRequired === false) {
-            return {
-                valid: true,
-                object: objToValidate
-            };
-        }
-        if (typeof objToValidate !== 'string')
-            return {
-                valid: false,
-                errors: [
-                    {
-                        message: `expected type string, but saw ${typeof objToValidate}`,
-                        path: path
-                    }
-                ]
-            };
-        if (typeof this.#equalsTo !== 'undefined' &&
-            objToValidate !== this.#equalsTo) {
-            return {
-                valid: false,
-                errors: [
-                    {
-                        message: `is expected to be equal to ${this.#equalsTo}`,
-                        path: path
-                    }
-                ]
-            };
-        }
-        if (typeof this.#startsWith === 'string' &&
-            this.#startsWith.length > 0 &&
-            !objToValidate.startsWith(this.#startsWith)) {
-            return {
-                valid: false,
-                errors: [
-                    {
-                        message: `is expected to start with '${this.#startsWith}'`,
-                        path: path
-                    }
-                ]
-            };
-        }
-        if (typeof this.#endsWith === 'string' &&
-            this.#endsWith.length > 0 &&
-            !objToValidate.endsWith(this.#endsWith)) {
-            return {
-                valid: false,
-                errors: [
-                    {
-                        message: `is expected to end with '${this.#endsWith}'`,
-                        path: path
-                    }
-                ]
-            };
-        }
-        if (typeof this.#minLength !== 'undefined') {
-            if (objToValidate.length < this.#minLength)
-                return {
-                    valid: false,
-                    errors: [
-                        {
-                            message: `expected to has at least ${this.#minLength} characters length`,
-                            path: path
-                        }
-                    ]
-                };
-        }
-        if (typeof this.#maxLength !== 'undefined') {
-            if (objToValidate.length > this.#maxLength)
-                return {
-                    valid: false,
-                    errors: [
-                        {
-                            message: `must not exceed ${this.#maxLength} characters`,
-                            path: path
-                        }
-                    ]
-                };
-        }
-        if (this.#matches instanceof RegExp) {
-            if (!this.#matches.test(objToValidate)) {
-                return {
-                    valid: false,
-                    errors: [
-                        {
-                            message: `does not match to ${this.#matches}`,
-                            path: path
-                        }
-                    ]
-                };
-            }
-        }
-        return {
-            valid: true,
-            object: objToValidate
-        };
-    }
-    createFromProps(props) {
-        return StringSchemaBuilder.create(props);
-    }
-    /**
-     * Restricts object to be equal to `value`.
-     */
-    equals(value) {
-        if (typeof value !== 'string')
-            throw new Error('string expected');
-        return this.createFromProps({
-            ...this.introspect(),
-            equalsTo: value
-        });
-    }
-    /**
-     * Cancels `equals()` call.
-     */
-    clearEquals() {
-        return this.createFromProps({
-            ...this.introspect(),
-            equalsTo: undefined
-        });
-    }
-    /**
-     * @hidden
-     */
-    required() {
-        return super.required();
-    }
-    /**
-     * @hidden
-     */
-    optional() {
-        return super.optional();
-    }
-    /**
-     * Set minimal length of the valid value for schema.
-     * @param {number} length
-     */
-    minLength(length) {
-        if (typeof length !== 'number')
-            throw new Error('length must be a number');
-        return this.createFromProps({
-            ...this.introspect(),
-            minLength: length
-        });
-    }
-    /**
-     * Cancel `minLength()` call.
-     */
-    clearMinLength() {
-        const schema = this.introspect();
-        delete schema.minLength;
-        return this.createFromProps({
-            ...schema
-        });
-    }
-    /**
-     * Set maximal length of the valid value for schema.
-     * @length {number} length
-     */
-    maxLength(length) {
-        if (typeof length !== 'number')
-            throw new Error('length must be a number');
-        return this.createFromProps({
-            ...this.introspect(),
-            maxLength: length
-        });
-    }
-    /**
-     * cancel `maxLength()` call.
-     */
-    clearMaxLength() {
-        const schema = this.introspect();
-        delete schema.maxLength;
-        return this.createFromProps({
-            ...schema
-        });
-    }
-    /**
-     * Restricts string to start with `val`.
-     */
-    startsWith(val) {
-        if (typeof val !== 'string' || !val)
-            throw new Error('non empty string expected');
-        return this.createFromProps({
-            ...this.introspect(),
-            startsWith: val
-        });
-    }
-    /**
-     * Cancels `startsWith()` call.
-     */
-    clearStartsWith() {
-        const schema = this.introspect();
-        delete schema.startsWith;
-        return this.createFromProps({
-            ...schema
-        });
-    }
-    /**
-     * Restricts string to end with `val`.
-     */
-    endsWith(val) {
-        if (typeof val !== 'string' || !val)
-            throw new Error('non empty string expected');
-        return this.createFromProps({
-            ...this.introspect(),
-            endsWith: val
-        });
-    }
-    /**
-     * Cancels `endsWith()` call.
-     */
-    clearEndsWith() {
-        const schema = this.introspect();
-        delete schema.endsWith;
-        return this.createFromProps({
-            ...schema
-        });
-    }
-    /**
-     * Restricts string to match `regexp`.
-     */
-    matches(regexp) {
-        if (!(regexp instanceof RegExp))
-            throw new Error('regexp expected');
-        return this.createFromProps({
-            ...this.introspect(),
-            matches: regexp
-        });
-    }
-    /**
-     * Cancels `matches()` call.
-     */
-    clearMatches() {
-        const schema = this.introspect();
-        delete schema.matches;
-        return this.createFromProps({
-            ...schema
-        });
-    }
-}
-/**
- * Creates a string schema.
- */
-export function string(equals) {
-    if (typeof equals === 'string') {
-        return StringSchemaBuilder.create({
-            isRequired: true,
-            equalsTo: equals
-        });
-    }
-    return StringSchemaBuilder.create({
-        isRequired: true
-    });
-}
+import{a,b}from"../chunk-FWUEUW2N.js";import"../chunk-CTP4RHDG.js";export{a as StringSchemaBuilder,b as string};
+//# sourceMappingURL=StringSchemaBuilder.js.map

package/dist/builders/StringSchemaBuilder.js.map

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

package/dist/builders/TupleSchemaBuilder.d.ts

@@ -0,0 +1,248 @@
+import type { ObjectSchemaBuilder, ObjectSchemaValidationResult } from './ObjectSchemaBuilder.js';
+import { type BRAND, type InferType, type NestedValidationResult, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+import type { UnionSchemaBuilder, UnionSchemaValidationResult } from './UnionSchemaBuilder.js';
+/**
+ * Maps a tuple of schema builders to a tuple of their per-position
+ * validation result types.
+ * Union schema elements get `UnionSchemaValidationResult`,
+ * object schema elements get `ObjectSchemaValidationResult`,
+ * other types get `ValidationResult`.
+ */
+export type TupleElementValidationResults<TElements extends readonly SchemaBuilder<any, any, any, any, any>[]> = {
+    [K in keyof TElements]: TElements[K] extends UnionSchemaBuilder<infer UOptions extends readonly SchemaBuilder<any, any, any, any, any>[], any, any> ? UnionSchemaValidationResult<InferType<TElements[K]>, UOptions> : TElements[K] extends ObjectSchemaBuilder<any, any, any, any, any> ? ObjectSchemaValidationResult<InferType<TElements[K]>, TElements[K]> : ValidationResult<InferType<TElements[K]>>;
+};
+/**
+ * Validation result type returned by `TupleSchemaBuilder.validate()`.
+ * Extends `ValidationResult` with `getNestedErrors` for root-level tuple
+ * errors and per-position validation results.
+ */
+export type TupleSchemaValidationResult<TResult, TElements extends readonly SchemaBuilder<any, any, any, any, any>[]> = ValidationResult<TResult> & {
+    /**
+     * Returns root-level tuple validation errors combined with
+     * per-position validation results.
+     * The returned value has both `NestedValidationResult` properties
+     * (`errors`, `isValid`, `descriptor`, `seenValue`) and indexed
+     * position results (`[0]`, `[1]`, etc.).
+     */
+    getNestedErrors(): TupleElementValidationResults<TElements> & NestedValidationResult<any, any, any>;
+};
+type TupleSchemaBuilderCreateProps<TElements extends readonly SchemaBuilder<any, any, any, any, any>[], TRestSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, R extends boolean = true, N extends boolean = false> = Partial<ReturnType<TupleSchemaBuilder<TElements, R, N, undefined, false, {}, TRestSchema>['introspect']>>;
+/**
+ * Fixed-length array schema builder with per-position type validation.
+ * Similar to TypeScript's tuple types — each element at a specific array index
+ * is validated against its own schema.
+ *
+ * Use it when you need to validate function arguments, CSV rows, coordinate
+ * pairs, structured event payloads, or any other fixed-structure array.
+ *
+ * **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 tuple | tuple()} function instead.
+ *
+ * @example
+ * ```ts
+ * const schema = tuple([string(), number(), boolean()]);
+ * // Inferred TypeScript type: [string, number, boolean]
+ *
+ * schema.validate(['hello', 42, true]);
+ * // result.valid === true
+ * // result.object === ['hello', 42, true]
+ *
+ * schema.validate(['hello', 42]);
+ * // result.valid === false  (too few elements)
+ *
+ * schema.validate(['hello', 'oops', true]);
+ * // result.valid === false  (wrong type at position 1)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Tuple with variadic rest elements
+ * const schema = tuple([string(), number()]).rest(boolean());
+ * // Inferred TypeScript type: [string, number, ...boolean[]]
+ *
+ * schema.validate(['hello', 42, true, false]);
+ * // result.valid === true — any number of extra booleans allowed
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Nested tuple combining with object schemas
+ * const point = tuple([number(), number()]);
+ * const segment = tuple([point, point]);
+ *
+ * segment.validate([[0, 0], [10, 20]]);
+ * // result.valid === true
+ * ```
+ *
+ * @see {@link tuple}
+ */
+export declare class TupleSchemaBuilder<TElements extends readonly SchemaBuilder<any, any, any, any, any>[], TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TRestSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, TResult = TExplicitType extends undefined ? TRestSchema extends SchemaBuilder<any, any, any, any, any> ? [
+    ...{
+        [K in keyof TElements]: InferType<TElements[K]>;
+    },
+    ...Array<InferType<TRestSchema>>
+] : {
+    [K in keyof TElements]: InferType<TElements[K]>;
+} : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: TupleSchemaBuilderCreateProps<any, any, any, any>): TupleSchemaBuilder<readonly SchemaBuilder<any, any, any, any, any>[], true, false, undefined, false, {}, undefined, readonly any[]>;
+    protected constructor(props: TupleSchemaBuilderCreateProps<TElements, TRestSchema, TRequired, TNullable>);
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): TupleSchemaBuilder<TElements, true, TNullable, T, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): TupleSchemaBuilder<TElements, TRequired, TNullable, undefined, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * Performs synchronous validation of the schema over `object`. {@inheritDoc SchemaBuilder.validate}
+     */
+    validate(object: TResult, context?: ValidationContext): TupleSchemaValidationResult<TResult, TElements>;
+    /**
+     * Performs asynchronous validation of the schema over `object`. {@inheritDoc SchemaBuilder.validateAsync}
+     */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<TupleSchemaValidationResult<TResult, TElements>>;
+    /**
+     * 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): TupleSchemaValidationResult<TResult, TElements>;
+    /**
+     * 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<TupleSchemaValidationResult<TResult, TElements>>;
+    /**
+     * @hidden
+     */
+    protected createFromProps<TReq extends boolean>(props: TupleSchemaBuilderCreateProps<TElements, TRestSchema, TReq>): this;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): TupleSchemaBuilder<TElements, true, TNullable, TExplicitType, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): TupleSchemaBuilder<TElements, false, TNullable, TExplicitType, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): TupleSchemaBuilder<TElements, true, TNullable, TExplicitType, true, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): TupleSchemaBuilder<TElements, TRequired, TNullable, TExplicitType, false, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): TupleSchemaBuilder<TElements, TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    introspect(): {
+        /**
+         * Per-position element schemas defining the fixed tuple structure.
+         */
+        elements: TElements;
+        /**
+         * Optional schema for elements beyond the fixed positions.
+         * When set, additional elements are validated against this schema.
+         * Mirrors TypeScript's rest element syntax: `[string, number, ...boolean[]]`.
+         */
+        restSchema: (TRestSchema & 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;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+    };
+    /**
+     * Sets a schema that all elements beyond the fixed positions must satisfy.
+     * Mirrors TypeScript's variadic tuple tail: `[string, number, ...boolean[]]`.
+     *
+     * When set, the tuple length must be at least equal to the number of fixed
+     * elements, and any additional elements are validated against `schema`.
+     * When not set, the tuple length must be exactly equal to the fixed count.
+     *
+     * @param schema Schema that extra array elements must satisfy.
+     *
+     * @example
+     * ```ts
+     * const schema = tuple([string(), number()]).rest(boolean());
+     * // Inferred TypeScript type: [string, number, ...boolean[]]
+     *
+     * schema.validate(['hello', 42]);               // valid
+     * schema.validate(['hello', 42, true]);          // valid
+     * schema.validate(['hello', 42, true, false]);   // valid
+     * schema.validate(['hello', 42, 'extra']);       // invalid — 'extra' not boolean
+     * ```
+     */
+    rest<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): TupleSchemaBuilder<TElements, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TSchema> & TExtensions;
+    /**
+     * Removes the rest schema set by `rest()`. After this call, the tuple
+     * length must be exactly equal to the number of fixed element schemas.
+     */
+    clearRest(): TupleSchemaBuilder<TElements, TRequired, TNullable, TExplicitType, THasDefault, TExtensions, undefined> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): TupleSchemaBuilder<TElements, TRequired, true, TExplicitType, THasDefault, TExtensions, TRestSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): TupleSchemaBuilder<TElements, TRequired, false, TExplicitType, THasDefault, TExtensions, TRestSchema> & TExtensions;
+}
+/**
+ * Creates a fixed-length array schema (tuple) where each element at a
+ * specific index is validated against its own schema.
+ *
+ * @param elements Array of per-position schemas. The length of this array
+ *   determines the required tuple length (unless `.rest()` is used).
+ *
+ * @example
+ * ```ts
+ * import { tuple, string, number, boolean } from '@cleverbrush/schema';
+ *
+ * const schema = tuple([string(), number(), boolean()]);
+ * // Inferred TypeScript type: [string, number, boolean]
+ *
+ * schema.validate(['hello', 42, true]);     // valid
+ * schema.validate(['hello', 42]);           // invalid — too few elements
+ * schema.validate(['hello', 'oops', true]); // invalid — wrong type at [1]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // 2-D coordinate pair
+ * const point = tuple([number(), number()]);
+ * const result = point.validate([10.5, 20.3]);
+ * // result.valid === true
+ * // result.object === [10.5, 20.3]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional tuple with default value
+ * const schema = tuple([string(), number()])
+ *     .optional()
+ *     .default(() => ['', 0]);
+ * ```
+ */
+export declare const tuple: <const TElements extends readonly SchemaBuilder<any, any, any, any, any>[]>(elements: [...TElements]) => TupleSchemaBuilder<TElements, true>;
+export {};

package/dist/builders/TupleSchemaBuilder.js

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

package/dist/builders/TupleSchemaBuilder.js.map

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