@cleverbrush/schema 1.0.0-beta.4 → 1.0.0

package/dist/builders/ArraySchemaBuilder.d.ts

@@ -1,15 +1,113 @@
-import { ISchemaBuilder } from './SchemaBuilder.js';
-import { Schema } from '../schema.js';
-export interface IArraySchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TOfType extends Schema | undefined = undefined, TMaxLength extends number | undefined = undefined, TMinLength extends number | undefined = undefined> extends ISchemaBuilder<TRequired, TNullable> {
-    optional(): IArraySchemaBuilder<false, TNullable, TOfType, TMaxLength, TMinLength>;
-    required(): IArraySchemaBuilder<true, TNullable, TOfType, TMaxLength, TMinLength>;
-    ofType<T extends Schema>(schema: T): IArraySchemaBuilder<TRequired, TNullable, T, TMaxLength, TMinLength>;
-    nullable(): IArraySchemaBuilder<TRequired, true, TOfType, TMaxLength, TMinLength>;
-    notNullable(): IArraySchemaBuilder<TRequired, false, TOfType, TMaxLength, TMinLength>;
-    clearOfType(): IArraySchemaBuilder<TRequired, TNullable, undefined, TMaxLength, TMinLength>;
-    maxLength<T extends number>(length: T): IArraySchemaBuilder<TRequired, TNullable, TOfType, T, TMinLength>;
-    clearMaxLength(): IArraySchemaBuilder<TRequired, TNullable, TOfType, undefined, TMinLength>;
-    minLength<T extends number>(length: T): IArraySchemaBuilder<TRequired, TNullable, TOfType, TMaxLength, T>;
-    clearMinLength(): IArraySchemaBuilder<TRequired, TNullable, TOfType, TMaxLength, TMinLength>;
+import { SchemaBuilder, ValidationResult, ValidationContext, InferType } from './SchemaBuilder.js';
+type ArraySchemaBuilderCreateProps<TElementSchema extends SchemaBuilder<any, any>, R extends boolean = true> = Partial<ReturnType<ArraySchemaBuilder<TElementSchema, R>['introspect']>>;
+/**
+ * Similar to the `Array` type in TypeScript. It can be used to validate arrays of any type.
+ * It can also be used to validate arrays of specific type.
+ * For example, if you want to validate an array of numbers,
+ * you can use `array(number())` to create a schema builder.
+ * If you want to validate an array of users, you can use
+ * `array().of(object({ name: string(), age: number() }))` to create a schema builder.
+ * If you want to validate an array of numbers or strings,
+ * you can use `array(union(number()).or(string()))`.
+ *
+ * Also you can limit the length of the array by using `minLength`
+ * and `maxLength` methods.
+ *
+ * **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 array | array()} function instead.
+ * @see {@link array}
+ */
+export declare class ArraySchemaBuilder<TElementSchema extends SchemaBuilder<any, any>, TRequired extends boolean = true, TExplicitType = undefined, TResult = TExplicitType extends undefined ? TElementSchema extends undefined ? Array<any> : TElementSchema extends SchemaBuilder<infer T1, infer T2> ? Array<InferType<SchemaBuilder<T1, T2>>> : never : TExplicitType> extends SchemaBuilder<TResult, TRequired> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: ArraySchemaBuilderCreateProps<any, any>): ArraySchemaBuilder<SchemaBuilder<any, any>, true, undefined, any[]>;
+    private constructor();
+    /**
+     * @hidden
+     */
+    hasType<T>(notUsed?: T): ArraySchemaBuilder<TElementSchema, true, T>;
+    /**
+     * @hidden
+     */
+    clearHasType(): ArraySchemaBuilder<TElementSchema, TRequired, undefined>;
+    /**
+     * Performs validion of the schema over `object`. Basically runs
+     * validators, preprocessors and checks for required (if schema is not optional).
+     * @param context Optional `ValidationContext` settings.
+     */
+    validate(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * @hidden
+     */
+    protected createFromProps<TReq extends boolean>(props: ArraySchemaBuilderCreateProps<TElementSchema, TReq>): this;
+    /**
+     * @hidden
+     */
+    required(): ArraySchemaBuilder<TElementSchema, true, TExplicitType>;
+    /**
+     * @hidden
+     */
+    optional(): ArraySchemaBuilder<TElementSchema, false, TExplicitType>;
+    introspect(): {
+        /**
+         * Schema of array item (if defined)
+         */
+        elementSchema: TElementSchema | undefined;
+        /**
+         * Min length of a valid array
+         */
+        minLength: number | undefined;
+        /**
+         * Max length of a valid array
+         */
+        maxLength: number | undefined;
+        type: string;
+        isRequired: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").Preprocessor<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").Validator<TResult>[];
+    };
+    /**
+     * Set a schema that every array item has to satisfy. If it is not set,
+     * Item of any type is allowed.
+     * @param schema Schema that every array item has to satisfy
+     */
+    of<TSchema extends SchemaBuilder<any, any>>(schema: TSchema): ArraySchemaBuilder<TSchema, TRequired, TExplicitType>;
+    clearOf(): ArraySchemaBuilder<any, TRequired, TExplicitType>;
+    /**
+     * Set minimal length of the valid array value for schema.
+     */
+    minLength<T extends number>(length: T): ArraySchemaBuilder<TElementSchema, TRequired, TExplicitType>;
+    /**
+     * Clear minimal length of the valid array value for schema.
+     */
+    clearMinLength(): ArraySchemaBuilder<TElementSchema, TRequired, TExplicitType>;
+    /**
+     * Set max length of the valid array value for schema.
+     */
+    maxLength<T extends number>(length: T): ArraySchemaBuilder<TElementSchema, TRequired, TExplicitType>;
+    /**
+     * Clear max length of the valid array value for schema.
+     */
+    clearMaxLength(): ArraySchemaBuilder<TElementSchema, TRequired, TExplicitType>;
 }
-export declare const array: () => IArraySchemaBuilder<true, false, undefined, undefined, undefined>;
+/**
+ * Creates a `Array` schema.
+ *
+ * @example
+ * ```typescript
+ *  const schema = array().minLength(2).maxLength(5).of(string());
+ *  // [] - invalid
+ *  // ['a', 'b'] - valid
+ *  // ['a', 'b', 'c', 'd', 'e', 'f'] - invalid
+ *  // ['a', 'b', 'c', 'd', 'e'] - valid
+ *  // ['a', 'b', 'c', 'd', 1] - invalid
+ *  // ['a', 'b', null] - invalid
+ *  // null - invalid
+ *  // undefined - invalid
+ * ```
+ */
+export declare const array: <TElementSchema extends SchemaBuilder<any, any>>(elementSchema?: TElementSchema | undefined) => ArraySchemaBuilder<TElementSchema, true, undefined, TElementSchema extends undefined ? any[] : TElementSchema extends SchemaBuilder<infer T1, infer T2 extends boolean> ? (T2 extends true ? T1 : T1 | undefined)[] : never>;
+export {};

package/dist/builders/ArraySchemaBuilder.js

@@ -1,141 +1,284 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.array = void 0;
-const SchemaBuilder_js_1 = require("./SchemaBuilder.js");
-const defaultSchemas_js_1 = require("../defaultSchemas.js");
-class ArraySchemaBuilder extends SchemaBuilder_js_1.SchemaBuilder {
-    clone() {
-        return ArraySchemaBuilder.create(this._schema);
+import { SchemaBuilder } from './SchemaBuilder.js';
+/**
+ * Similar to the `Array` type in TypeScript. It can be used to validate arrays of any type.
+ * It can also be used to validate arrays of specific type.
+ * For example, if you want to validate an array of numbers,
+ * you can use `array(number())` to create a schema builder.
+ * If you want to validate an array of users, you can use
+ * `array().of(object({ name: string(), age: number() }))` to create a schema builder.
+ * If you want to validate an array of numbers or strings,
+ * you can use `array(union(number()).or(string()))`.
+ *
+ * Also you can limit the length of the array by using `minLength`
+ * and `maxLength` methods.
+ *
+ * **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 array | array()} function instead.
+ * @see {@link array}
+ */
+export class ArraySchemaBuilder extends SchemaBuilder {
+    #minLength;
+    #maxLength;
+    #elementSchema;
+    /**
+     * @hidden
+     */
+    static create(props) {
+        return new ArraySchemaBuilder({
+            type: 'array',
+            ...props
+        });
     }
-    get _schema() {
-        return Object.assign({
-            type: this.type
-        }, this.getCommonSchema(), typeof this._ofType !== 'undefined'
-            ? {
-                ofType: this._ofType
-            }
-            : {}, typeof this._minLength !== 'undefined'
-            ? { minLength: this._minLength }
-            : {}, typeof this._maxLength !== 'undefined'
-            ? { maxLength: this._maxLength }
-            : {});
+    constructor(props) {
+        super(props);
+        if (typeof props.minLength === 'number') {
+            this.#minLength = props.minLength;
+        }
+        if (typeof props.maxLength === 'number') {
+            this.#maxLength = props.maxLength;
+        }
+        if (props.elementSchema instanceof SchemaBuilder) {
+            this.#elementSchema = props.elementSchema;
+        }
+    }
+    /**
+     * @hidden
+     */
+    hasType(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    notUsed) {
+        return this.createFromProps({
+            ...this.introspect()
+        });
     }
-    static create(obj) {
-        return new ArraySchemaBuilder(obj);
+    /**
+     * @hidden
+     */
+    clearHasType() {
+        return this.createFromProps({
+            ...this.introspect()
+        });
     }
-    constructor(obj) {
-        super(obj);
-        if (typeof obj === 'object' && obj) {
-            if (typeof obj.ofType !== 'undefined') {
-                this._ofType =
-                    obj.ofType instanceof SchemaBuilder_js_1.SchemaBuilder
-                        ? obj.ofType.clone()
-                        : { ...obj.ofType };
-            }
-            if (typeof obj.maxLength !== 'undefined') {
-                this._maxLength = obj.maxLength;
+    /**
+     * Performs validion of the schema over `object`. Basically runs
+     * validators, preprocessors and checks for required (if schema is not optional).
+     * @param context Optional `ValidationContext` settings.
+     */
+    async validate(object, context) {
+        const superResult = await super.preValidate(object, context);
+        const { valid, context: prevalidationContext, errors, transaction: preValidationTransaction } = 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 (!Array.isArray(objToValidate)) {
+            return {
+                valid: false,
+                errors: [{ message: 'array expected', path: path }]
+            };
+        }
+        if (typeof this.#maxLength === 'number' &&
+            objToValidate.length > this.#maxLength) {
+            return {
+                valid: false,
+                errors: [
+                    {
+                        message: `cannot contain more than ${this.#maxLength} elements`,
+                        path: path
+                    }
+                ]
+            };
+        }
+        if (typeof this.#minLength === 'number' &&
+            objToValidate.length < this.#minLength) {
+            return {
+                valid: false,
+                errors: [
+                    {
+                        message: `cannot contain less than ${this.#minLength} elements`,
+                        path: path
+                    }
+                ]
+            };
+        }
+        if (objToValidate.length > 0 &&
+            this.#elementSchema instanceof SchemaBuilder) {
+            if (prevalidationContext.doNotStopOnFirstError) {
+                const results = await Promise.all(objToValidate.map((o) => this.#elementSchema?.validate(o, prevalidationContext)));
+                let valid = true;
+                for (let i = 0; i < results.length; i++) {
+                    if (!results[i]?.valid) {
+                        valid = false;
+                    }
+                }
+                return Object.assign({
+                    valid
+                }, valid
+                    ? {}
+                    : {
+                        errors: results
+                            .map((r) => r?.errors)
+                            .filter((r) => r)
+                            .map((e) => e?.map((r, index) => ({
+                            ...r,
+                            path: `${r.path}[${index}]`
+                        })))
+                            .flat()
+                    }, valid
+                    ? {
+                        object: results.map((r) => r?.object)
+                    }
+                    : {});
             }
-            if (typeof obj.minLength !== 'undefined') {
-                this._minLength = obj.minLength;
+            else {
+                for (let i = 0; i < objToValidate.length; i++) {
+                    const { valid, errors, object: validatedItem } = await this.#elementSchema.validate(objToValidate[i], {
+                        ...prevalidationContext,
+                        path: `${path}[${i}]`
+                    });
+                    if (valid) {
+                        objToValidate[i] = validatedItem;
+                    }
+                    else {
+                        return {
+                            valid: false,
+                            errors: Array.isArray(errors) && errors.length > 0
+                                ? [errors[0]]
+                                : []
+                        };
+                    }
+                }
             }
         }
-        else {
-            const defaultSchema = defaultSchemas_js_1.defaultSchemas['array'];
-            this.isRequired = defaultSchema.isRequired;
-            this.isNullable = defaultSchema.isNullable;
-        }
+        return {
+            valid: true,
+            object: objToValidate
+        };
     }
-    type = 'array';
-    _ofType;
-    _maxLength;
-    _minLength;
-    optional() {
-        if (this.isRequired === false) {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            isRequired: false
-        });
+    /**
+     * @hidden
+     */
+    createFromProps(props) {
+        return ArraySchemaBuilder.create(props);
     }
+    /**
+     * @hidden
+     */
     required() {
-        if (this.isRequired === true) {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            isRequired: true
-        });
+        return super.required();
     }
-    nullable() {
-        if (this._isNullable === true) {
-            return this;
-        }
+    /**
+     * @hidden
+     */
+    optional() {
+        return super.optional();
+    }
+    introspect() {
+        return {
+            ...super.introspect(),
+            /**
+             * Schema of array item (if defined)
+             */
+            elementSchema: this.#elementSchema,
+            /**
+             * Min length of a valid array
+             */
+            minLength: this.#minLength,
+            /**
+             * Max length of a valid array
+             */
+            maxLength: this.#maxLength
+        };
+    }
+    /**
+     * Set a schema that every array item has to satisfy. If it is not set,
+     * Item of any type is allowed.
+     * @param schema Schema that every array item has to satisfy
+     */
+    of(schema) {
         return ArraySchemaBuilder.create({
-            ...this._schema,
-            isNullable: true
+            ...this.introspect(),
+            elementSchema: schema
         });
     }
-    notNullable() {
-        if (this.isNullable === false) {
-            return this;
-        }
+    clearOf() {
         return ArraySchemaBuilder.create({
-            ...this._schema,
-            isNullable: false
+            ...this.introspect(),
+            elementSchema: undefined
         });
     }
-    ofType(schema) {
+    /**
+     * Set minimal length of the valid array value for schema.
+     */
+    minLength(length) {
+        if (typeof length !== 'number' || length < 0)
+            throw new Error('length is expected to be a number which is >= 0');
         return ArraySchemaBuilder.create({
-            ...this._schema,
-            ofType: schema
+            ...this.introspect(),
+            minLength: length
         });
     }
-    clearOfType() {
-        if (typeof this._ofType === 'undefined') {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            ofType: undefined
+    /**
+     * Clear minimal length of the valid array value for schema.
+     */
+    clearMinLength() {
+        const schema = this.introspect();
+        delete schema.minLength;
+        return this.createFromProps({
+            ...schema
         });
     }
+    /**
+     * Set max length of the valid array value for schema.
+     */
     maxLength(length) {
-        if (this._maxLength === length) {
-            return this;
-        }
+        if (typeof length !== 'number' || length < 0)
+            throw new Error('length is expected to be a number which is >= 0');
         return ArraySchemaBuilder.create({
-            ...this._schema,
+            ...this.introspect(),
             maxLength: length
         });
     }
+    /**
+     * Clear max length of the valid array value for schema.
+     */
     clearMaxLength() {
-        if (typeof this._maxLength === 'undefined') {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            maxLength: undefined
-        });
-    }
-    minLength(length) {
-        if (this._minLength === length) {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            minLength: length
-        });
-    }
-    clearMinLength() {
-        if (typeof this._minLength === 'undefined') {
-            return this;
-        }
-        return ArraySchemaBuilder.create({
-            ...this._schema,
-            minLength: undefined
+        const schema = this.introspect();
+        delete schema.maxLength;
+        return this.createFromProps({
+            ...schema
         });
     }
 }
-const array = () => ArraySchemaBuilder.create();
-exports.array = array;
+/**
+ * Creates a `Array` schema.
+ *
+ * @example
+ * ```typescript
+ *  const schema = array().minLength(2).maxLength(5).of(string());
+ *  // [] - invalid
+ *  // ['a', 'b'] - valid
+ *  // ['a', 'b', 'c', 'd', 'e', 'f'] - invalid
+ *  // ['a', 'b', 'c', 'd', 'e'] - valid
+ *  // ['a', 'b', 'c', 'd', 1] - invalid
+ *  // ['a', 'b', null] - invalid
+ *  // null - invalid
+ *  // undefined - invalid
+ * ```
+ */
+export const array = (elementSchema) => ArraySchemaBuilder.create({
+    isRequired: true,
+    elementSchema
+});

package/dist/builders/BooleanSchemaBuilder.d.ts

@@ -1,31 +1,71 @@
-import { Schema, Validator } from '../schema.js';
-import { ISchemaBuilder, SchemaBuilder } from './SchemaBuilder.js';
-export interface IBooleanSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TEqualsTo extends boolean | undefined = undefined> extends ISchemaBuilder<TRequired, TNullable> {
-    equals<T extends boolean>(val: T): IBooleanSchemaBuilder<TRequired, TNullable, T>;
-    clearEqualsTo(): IBooleanSchemaBuilder<TRequired, TNullable, undefined>;
-    optional(): IBooleanSchemaBuilder<false, TNullable, TEqualsTo>;
-    required(): IBooleanSchemaBuilder<true, TNullable, TEqualsTo>;
-    nullable(): IBooleanSchemaBuilder<TRequired, true, TEqualsTo>;
-    notNullable(): IBooleanSchemaBuilder<TRequired, false, TEqualsTo>;
-}
-export declare class BooleanSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TEqualsTo extends boolean | undefined = undefined> extends SchemaBuilder<TRequired, TNullable> implements IBooleanSchemaBuilder<TRequired, TNullable, TEqualsTo> {
-    protected readonly type = "boolean";
-    get _schema(): Schema;
-    clone(): this;
-    static create<TRequired extends boolean = true, TNullable extends boolean = false, TEqualsTo extends boolean | undefined = undefined>(obj?: {
-        isRequired: TRequired;
-        isNullable: TNullable;
-        equals?: TEqualsTo;
-        validators?: Validator[];
-        preprocessor?: ((value: unknown) => unknown | Promise<unknown>) | string;
-    }): IBooleanSchemaBuilder<TRequired, TNullable, TEqualsTo>;
+import { SchemaBuilder, ValidationResult, ValidationContext } from './SchemaBuilder.js';
+type BooleanSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<BooleanSchemaBuilder<R>['introspect']>>;
+/**
+ * Similar to `boolean` type in TypeScript.
+ * Allows to define a schema for a boolean value. It can be required or optional.
+ * It can be restricted to be equal to a certain value.
+ *
+ * **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 boolean | boolean()} function instead.
+ *
+ * @example ```ts
+ * const schema = boolean().equals(true);
+ * const result = await schema.validate(true);
+ * // result.valid === true
+ * // result.object === true
+ * ```
+ * @example ```ts
+ * const schema = boolean().equals(false);
+ * const result = await schema.validate(true);
+ * // result.valid === false
+ * // result.errors[0].message === 'is expected to be equal to 'false''
+ * ```
+ * @example ```ts
+ * const schema = boolean().equals(true).optional();
+ * const result = await schema.validate(undefined);
+ * // result.valid === true
+ * // result.object === undefined
+ * ```
+ *
+ * @see {@link boolean}
+ */
+export declare class BooleanSchemaBuilder<TResult = boolean, TRequired extends boolean = true, TExplicitType = undefined, TFinalResult = TExplicitType extends undefined ? TResult : TExplicitType> extends SchemaBuilder<TFinalResult, TRequired> {
+    #private;
+    static create(props: BooleanSchemaBuilderCreateProps<any>): BooleanSchemaBuilder<boolean, any, undefined, boolean>;
     private constructor();
-    protected _equals?: TEqualsTo;
-    equals<T extends boolean>(val: T): IBooleanSchemaBuilder<TRequired, TNullable, T>;
-    clearEqualsTo(): IBooleanSchemaBuilder<TRequired, TNullable, undefined>;
-    optional(): IBooleanSchemaBuilder<false, TNullable, TEqualsTo>;
-    required(): IBooleanSchemaBuilder<true, TNullable, TEqualsTo>;
-    nullable(): IBooleanSchemaBuilder<TRequired, true, TEqualsTo>;
-    notNullable(): IBooleanSchemaBuilder<TRequired, false, TEqualsTo>;
+    introspect(): {
+        /**
+         * If set, restrict object to be equal to a certain value.
+         */
+        equalsTo: boolean | undefined;
+        type: string;
+        isRequired: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").Preprocessor<TFinalResult>[];
+        validators: readonly import("./SchemaBuilder.js").Validator<TFinalResult>[];
+    };
+    hasType<T>(notUsed?: T): BooleanSchemaBuilder<TResult, true, T>;
+    clearHasType(): BooleanSchemaBuilder<TResult, TRequired, undefined>;
+    /**
+     * Performs validion of the schema over `object`. Basically runs
+     * validators, preprocessors and checks for required (if schema is not optional).
+     * @param context Optional `ValidationContext` settings.
+     */
+    validate(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected createFromProps<TReq extends boolean>(props: BooleanSchemaBuilderCreateProps<TReq>): this;
+    required(): BooleanSchemaBuilder<TResult, true, TExplicitType>;
+    optional(): BooleanSchemaBuilder<TResult, false, TExplicitType>;
+    /**
+     * Restricts object to be equal to `value`.
+     */
+    equals<T extends boolean>(value: T): BooleanSchemaBuilder<T, TRequired, TExplicitType, TExplicitType extends undefined ? T : TExplicitType>;
+    /**
+     * Removes a `value` defeined by `equals()` call.
+     */
+    clearEquals(): BooleanSchemaBuilder<boolean, TRequired, TExplicitType>;
 }
-export declare const boolean: () => IBooleanSchemaBuilder;
+/**
+ * Creates a `boolean` schema.
+ */
+export declare const boolean: () => BooleanSchemaBuilder<boolean, true, undefined, boolean>;
+export {};