@cleverbrush/schema 1.0.0-beta.4 → 1.0.0

package/dist/builders/SchemaBuilder.d.ts

@@ -1,36 +1,160 @@
-import { Schema, Validator } from '../schema.js';
-export interface ISchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false> {
-    readonly _schema: Schema;
-    isRequired: TRequired;
-    isNullable: TNullable;
-    validators?: Validator[];
-    preprocessor?: ((value: unknown) => unknown | Promise<unknown>) | string;
-    addValidator(validator: Validator): this;
+import { Transaction } from '../utils/transaction.js';
+export type InferType<T> = T extends SchemaBuilder<infer TResult, infer TRequired> ? T extends {
+    optimize: (...args: any[]) => SchemaBuilder<infer TOptimizedType, infer TOptimizedRequired>;
+} ? TOptimizedRequired extends true ? TOptimizedType : MakeOptional<TOptimizedType> : TRequired extends true ? TResult : MakeOptional<TResult> : T;
+export type ValidationError = {
+    path: string;
+    message: string;
+};
+export type MakeRequired<T> = NonNullable<T>;
+export type MakeOptional<T> = {
+    prop?: T;
+}['prop'];
+export type ValidationResult<T> = {
+    /**
+     * If `true` - object satisfies schema
+     */
+    valid: boolean;
+    /**
+     * Contains validated object. Can be different (if there are any preprocessors in the schema) from object
+     * passed to the `validate` method of the `SchemaBuilder` class.
+     */
+    object?: T;
+    errors?: ValidationError[];
+};
+export type PreValidationResult<T, TTransactionType> = Omit<ValidationResult<T>, 'object'> & {
+    context: ValidationContext;
+    transaction?: Transaction<TTransactionType>;
+};
+type ValidatorResult<T> = Omit<ValidationResult<T>, 'object' | 'errors'> & {
+    errors?: Omit<ValidationError, 'path'>[];
+};
+export type Preprocessor<T> = (object: T) => Promise<T> | T;
+export type Validator<T> = (object: T) => Promise<ValidatorResult<T>> | ValidatorResult<T>;
+export type SchemaBuilderProps<T> = {
+    type: string;
+    isRequired?: boolean;
+    preprocessors: Preprocessor<T>[];
+    validators: Validator<T>[];
+};
+export type ValidationContext = {
+    /**
+     * Path of the field. **Optional**, used to display correct error path in the {@link ValidationError}
+     */
+    path?: string;
+    /**
+     * Optional. By default validation will stop after the first validation error, in case if
+     * you want to receive all validation erors, please set this flag to `true`.
+     * You might need it to display validation errors.
+     */
+    doNotStopOnFirstError?: boolean;
+};
+/**
+ * Base class for all schema builders. Provides basic functionality for schema building.
+ *
+ * **Note:** this class is not intended to be used directly, use one of the subclasses instead.
+ * @typeparam TResult Type of the object that will be returned by `validate()` method.
+ * @typeparam TRequired If `true`, object will be required. If `false`, object will be optional.
+ */
+export declare abstract class SchemaBuilder<TResult = any, TRequired extends boolean = true> {
+    #private;
+    /**
+     * Set type of schema explicitly. `notUsed` param is needed only for cas when JS is used. E.g. when you
+     * can't call method like `schema.hasType<Date>()`, so instead you can call `schema.hasType(new Date())`
+     * with the same result.
+     */
+    abstract hasType<T>(notUsed?: T): any;
+    /**
+     * Clears type set by call to `.hasType<T>()`, default schema type inference will be used
+     * for schema retuned by this call.
+     */
+    abstract clearHasType(): any;
+    /**
+     * Protected method used to create an new instance of the Builder
+     * defined by the `props` object. Should be used to instanticate new
+     * builders to keep builder's immutability.
+     * @param props arbitrary props object
+     */
+    protected abstract createFromProps(props: any): this;
+    protected get type(): string;
+    protected set type(value: string);
+    /**
+     * A list of preprocessors associated with
+     * the Builder
+     */
+    protected get preprocessors(): Preprocessor<TResult>[];
+    /**
+     * A list of validators associated with
+     * the Builder
+     */
+    protected get validators(): Validator<TResult>[];
+    protected get isRequired(): TRequired;
+    protected set isRequired(value: boolean);
+    protected preValidate(
+    /**
+     * Object to validate
+     */
+    object: any, context?: ValidationContext): Promise<PreValidationResult<any, {
+        validatedObject: any;
+    }>>;
+    /**
+     * Generates a serializable object describing the defined schema
+     */
+    introspect(): {
+        /**
+         * String `id` of schema type, e.g. `string', `number` or `object`.
+         */
+        type: string;
+        /**
+         * If set to `false`, schema will be optional (`null` or `undefined` values
+         * will be considered as valid).
+         */
+        isRequired: boolean;
+        /**
+         * Array of preprocessor functions
+         */
+        preprocessors: readonly Preprocessor<TResult>[];
+        /**
+         * Array of validator functions
+         */
+        validators: readonly Validator<TResult>[];
+    };
+    /**
+     * Makes schema optional (consider `null` and `undefined` as valid objects for this schema)
+     */
+    optional(): any;
+    /**
+     * Makes schema required (consider `null` and `undefined` as invalid objects for this schema)
+     */
+    required(): any;
+    /**
+     * Adds a `preprocessor` to a preprocessors list
+     */
+    addPreprocessor(preprocessor: Preprocessor<TResult>): this;
+    /**
+     * Remove all preprocessors for this schema.
+     */
+    clearPreprocessors(): this;
+    /**
+     * Adds a `validator` to validators list.
+     */
+    addValidator(validator: Validator<TResult>): this;
+    /**
+     * Remove all validators for this schema.
+     */
     clearValidators(): this;
-    addPreprocessor(preprocessor: ((value: unknown) => unknown | Promise<unknown>) | string): this;
-    clearPreprocessor(): this;
-    clone(): this;
-}
-export declare abstract class SchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false> implements ISchemaBuilder<TRequired, TNullable> {
-    protected _isRequired: TRequired;
-    protected _isNullable: TNullable;
-    validators?: Validator[];
-    preprocessor?: ((value: unknown) => unknown | Promise<unknown>) | string;
-    abstract clone(): this;
-    abstract get _schema(): Schema;
-    protected constructor(obj: {
-        isRequired?: boolean;
-        isNullable?: boolean;
-        preprocessor?: ((value: unknown) => unknown | Promise<unknown>) | string;
-        validators?: Validator[];
-    });
-    protected getCommonSchema(): any;
-    addPreprocessor(preprocessor: ((value: unknown) => unknown | Promise<unknown>) | string): this;
-    clearPreprocessor(): this;
-    addValidator(validator: Validator): this;
-    clearValidators(): this;
-    get isRequired(): TRequired;
-    protected set isRequired(val: boolean);
-    get isNullable(): TNullable;
-    protected set isNullable(val: boolean);
+    /**
+     * Perform schema validation on `object`.
+     */
+    abstract validate(
+    /**
+     * Object to validate
+     */
+    object: any, 
+    /**
+     * Optional `ValidationContext` settings
+     */
+    context?: ValidationContext): Promise<ValidationResult<any>>;
+    protected constructor(props: SchemaBuilderProps<TResult>);
 }
+export {};

package/dist/builders/SchemaBuilder.js

@@ -1,88 +1,275 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchemaBuilder = void 0;
-class SchemaBuilder {
-    _isRequired = true;
-    _isNullable = false;
-    validators;
-    preprocessor;
-    constructor(obj) {
-        if (typeof obj === 'object') {
-            if (typeof obj.isRequired !== 'undefined') {
-                this.isRequired = obj.isRequired;
-            }
-            if (typeof obj.isNullable !== 'undefined') {
-                this.isNullable = obj.isNullable;
-            }
-            if (Array.isArray(obj.validators)) {
-                this.validators = [...obj.validators];
+import { transaction } from '../utils/transaction.js';
+/**
+ * Base class for all schema builders. Provides basic functionality for schema building.
+ *
+ * **Note:** this class is not intended to be used directly, use one of the subclasses instead.
+ * @typeparam TResult Type of the object that will be returned by `validate()` method.
+ * @typeparam TRequired If `true`, object will be required. If `false`, object will be optional.
+ */
+export class SchemaBuilder {
+    #isRequired = true;
+    #preprocessors = [];
+    #validators = [];
+    #type = 'base';
+    get type() {
+        return this.#type;
+    }
+    set type(value) {
+        if (typeof value !== 'string' || !value)
+            throw new Error('value should be non empty string');
+        this.#type = value;
+    }
+    /**
+     * A list of preprocessors associated with
+     * the Builder
+     */
+    get preprocessors() {
+        return this.#preprocessors;
+    }
+    /**
+     * A list of validators associated with
+     * the Builder
+     */
+    get validators() {
+        return this.#validators;
+    }
+    get isRequired() {
+        return this.#isRequired;
+    }
+    set isRequired(value) {
+        if (typeof value !== 'boolean')
+            throw new Error('should be a boolean value');
+        this.#isRequired = value;
+    }
+    async preValidate(
+    /**
+     * Object to validate
+     */
+    object, context) {
+        const { doNotStopOnFirstError } = context || {
+            doNotStopOnFirstError: false
+        };
+        let path = '$';
+        if (typeof context?.path === 'string' && context.path)
+            path = context.path;
+        const resultingContext = {
+            path,
+            doNotStopOnFirstError
+        };
+        let preprocessingTransaction = transaction({
+            validatedObject: object
+        });
+        let preprocessedObject = preprocessingTransaction.object.validatedObject;
+        let errors = [];
+        if (Array.isArray(this.preprocessors)) {
+            let currentPrepropIndex = 0;
+            for (const preprocessor of this.preprocessors) {
+                try {
+                    preprocessingTransaction = transaction({
+                        validatedObject: await Promise.resolve(preprocessor(preprocessedObject))
+                    });
+                    preprocessedObject =
+                        preprocessingTransaction.object.validatedObject;
+                }
+                catch (err) {
+                    errors.push({
+                        message: `Preprocessor #${currentPrepropIndex}${preprocessor.name ? ` (${preprocessor.name})` : ''} thrown an error: ${err.message}`,
+                        path: `${path}($preprocessors[${currentPrepropIndex}])`
+                    });
+                    if (!doNotStopOnFirstError) {
+                        preprocessingTransaction.rollback();
+                        return {
+                            valid: false,
+                            errors: [errors[0]].filter((e) => e),
+                            context: resultingContext
+                        };
+                    }
+                }
+                finally {
+                    currentPrepropIndex++;
+                }
             }
-            if (typeof obj.preprocessor !== 'undefined') {
-                this.preprocessor = obj.preprocessor;
+        }
+        if (Array.isArray(this.validators)) {
+            let currentValidatorIndex = 0;
+            for (const validator of this.validators) {
+                try {
+                    const { valid, errors: validatorErrors } = await Promise.resolve(validator(preprocessedObject));
+                    if (!valid) {
+                        errors = [
+                            ...errors,
+                            ...(Array.isArray(validatorErrors) &&
+                                validatorErrors.length
+                                ? validatorErrors.map((err) => ({
+                                    message: err.message,
+                                    path: `${path}($validators[${currentValidatorIndex}])`
+                                }))
+                                : [
+                                    {
+                                        message: `Validator #${currentValidatorIndex}${validator.name
+                                            ? ` (${validator.name})`
+                                            : ''} didn't pass.`,
+                                        path: `${path}($validators[${currentValidatorIndex}])`
+                                    }
+                                ])
+                        ];
+                        if (!doNotStopOnFirstError) {
+                            preprocessingTransaction.rollback();
+                            return {
+                                valid: false,
+                                errors: [errors[0]].filter((e) => e),
+                                context: resultingContext
+                            };
+                        }
+                    }
+                }
+                catch (err) {
+                    errors.push({
+                        message: `Validator #${currentValidatorIndex}${validator.name ? ` (${validator.name})` : ''} thrown an error: ${err.message}`,
+                        path: `${path}($validators[${currentValidatorIndex}])`
+                    });
+                    if (!doNotStopOnFirstError) {
+                        preprocessingTransaction.rollback();
+                        return {
+                            valid: false,
+                            errors: [errors[0]].filter((e) => e),
+                            context: resultingContext
+                        };
+                    }
+                }
+                finally {
+                    currentValidatorIndex++;
+                }
             }
         }
-    }
-    getCommonSchema() {
-        const schemas = [];
-        if (typeof this.preprocessor !== 'undefined') {
-            schemas.push({
-                preprocessor: this.preprocessor
+        if (this.isRequired &&
+            (typeof preprocessedObject === 'undefined' ||
+                preprocessedObject === null)) {
+            errors.push({
+                message: 'is required',
+                path
             });
+            if (!doNotStopOnFirstError) {
+                preprocessingTransaction.rollback();
+                return {
+                    valid: false,
+                    errors: [errors[0]],
+                    context: resultingContext
+                };
+            }
         }
-        if (typeof this.isRequired !== 'undefined') {
-            schemas.push({ isRequired: this.isRequired });
-        }
-        if (typeof this.isNullable !== 'undefined') {
-            schemas.push({ isNullable: this.isNullable });
-        }
-        if (typeof this.validators !== 'undefined') {
-            schemas.push({ validators: [...this.validators] });
+        if (errors.length > 0) {
+            return {
+                valid: false,
+                errors: errors
+                    .filter((e) => e)
+                    .filter((e, i) => (doNotStopOnFirstError ? true : i === 0)),
+                context: resultingContext,
+                transaction: preprocessingTransaction
+            };
         }
-        return Object.assign({}, ...schemas);
+        return {
+            valid: true,
+            context: resultingContext,
+            transaction: preprocessingTransaction
+        };
     }
-    addPreprocessor(preprocessor) {
-        const result = this.clone();
-        result.preprocessor = preprocessor;
-        return result;
+    /**
+     * Generates a serializable object describing the defined schema
+     */
+    introspect() {
+        return {
+            /**
+             * String `id` of schema type, e.g. `string', `number` or `object`.
+             */
+            type: this.type,
+            /**
+             * If set to `false`, schema will be optional (`null` or `undefined` values
+             * will be considered as valid).
+             */
+            isRequired: this.#isRequired,
+            /**
+             * Array of preprocessor functions
+             */
+            preprocessors: [
+                ...this.preprocessors
+            ],
+            /**
+             * Array of validator functions
+             */
+            validators: [...this.validators]
+        };
+    }
+    /**
+     * Makes schema optional (consider `null` and `undefined` as valid objects for this schema)
+     */
+    optional() {
+        return this.createFromProps({
+            ...this.introspect(),
+            isRequired: false
+        });
+    }
+    /**
+     * Makes schema required (consider `null` and `undefined` as invalid objects for this schema)
+     */
+    required() {
+        return this.createFromProps({
+            ...this.introspect(),
+            isRequired: true
+        });
     }
-    clearPreprocessor() {
-        if (typeof this.preprocessor === 'undefined') {
-            return this;
+    /**
+     * Adds a `preprocessor` to a preprocessors list
+     */
+    addPreprocessor(preprocessor) {
+        if (typeof preprocessor !== 'function') {
+            throw new Error('preprocessor must be a function');
         }
-        const result = this.clone();
-        delete result.preprocessor;
-        return result;
+        return this.createFromProps({
+            ...this.introspect(),
+            preprocessors: [...this.preprocessors, preprocessor]
+        });
+    }
+    /**
+     * Remove all preprocessors for this schema.
+     */
+    clearPreprocessors() {
+        return this.createFromProps({
+            ...this.introspect(),
+            preprocessors: []
+        });
     }
+    /**
+     * Adds a `validator` to validators list.
+     */
     addValidator(validator) {
-        const result = this.clone();
-        if (typeof validator !== 'function')
-            throw new Error('validator should be a function');
-        if (Array.isArray(result.validators)) {
-            result.validators.push(validator);
-        }
-        else {
-            result.validators = [validator];
+        if (typeof validator !== 'function') {
+            throw new Error('validator must be a function');
         }
-        return result;
+        return this.createFromProps({
+            ...this.introspect(),
+            validators: [...this.validators, validator]
+        });
     }
+    /**
+     * Remove all validators for this schema.
+     */
     clearValidators() {
-        if (typeof this.validators === 'undefined')
-            return this;
-        const result = this.clone();
-        delete result.validators;
-        return result;
+        return this.createFromProps({
+            ...this.introspect(),
+            validators: []
+        });
     }
-    get isRequired() {
-        return this._isRequired;
-    }
-    set isRequired(val) {
-        this._isRequired = val;
-    }
-    get isNullable() {
-        return this._isNullable;
-    }
-    set isNullable(val) {
-        this._isNullable = val;
+    constructor(props) {
+        const { type, preprocessors, validators, isRequired } = props;
+        this.type = type;
+        if (typeof isRequired === 'boolean')
+            this.isRequired = isRequired;
+        if (Array.isArray(preprocessors)) {
+            this.#preprocessors = [...preprocessors];
+        }
+        if (Array.isArray(validators)) {
+            this.#validators = [...validators];
+        }
     }
 }
-exports.SchemaBuilder = SchemaBuilder;