@cleverbrush/schema 0.0.3

package/README.md

@@ -0,0 +1,279 @@
+# Object Schema Validator
+
+This package contains utilities to validate the JavaScript object's schema. There is only one class exported - `SchemaValidator`
+
+## Schema Types
+
+There are several schema types available:
+
+-   object
+-   string
+-   number
+-   array
+-   function (_TBD_)
+
+Schemas could be either described by shortcusts (string value from the list above) or by more detailed specification.
+
+## Schema Definitions
+
+### Common for all types
+
+Any schema defined by object can contain the following fields:
+
+-   `type` - schema type (see the list above)
+-   `isRequired` - defines if `undefined` value is considered valid
+-   `isNullable` - defines if `null` value is considered valid
+-   `validators` - optional array of custom validation functions (see [Examples](#examples))
+
+### Number
+
+`number` schema can be defined as follows:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+
+    // validates for integer number between 1 and 100
+    let result = await validator.validate(
+        {
+            type: "number",
+            isInteger: true,
+            min: 1,
+            max: 100,
+        },
+        10
+    );
+
+All fields available (apart of common fields for all schemas) are:
+
+-   `isInteger` - ensures that number is integer
+-   `ensureIsFinite` - ensures that nubmer is finite
+-   `ensureNotNaN` - ensures that number is not NaN
+-   `equals` - checks if a value is equal to provided number
+-   `min` - checks if a value is bigger or equal than a provided lower bound
+-   `max` - checks if a value is lower or equal than a provided upper bound
+
+Also it can be defined either by shortcut:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate('number', 10);
+    // { valid: true }
+    result = await validator.validate('number', 'some string');
+    // { valid: false, errors: [ 'expected type number, but saw string' ] }
+
+which is equal to:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate({
+        type: 'number',
+        isRequired: true,
+        isNullable: false,
+        ensureNotNaN: true,
+        ensureIsFinite: true
+    }, 0 / 0);
+    // { valid: false }
+
+### String
+
+`string` schema can be defined as follows:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+
+    // validates for non empty string no longer than 100 chars
+    let result = await validator.validate(
+        {
+            type: "string",
+            minLength: 1,
+            maxLength: 100
+        },
+        "some value here"
+    );
+    // { valid: true }
+
+All fields available (apart of common fields for all schemas) are:
+
+-   `equals` - checks if value is equal to provided string
+-   `minLength` - checks if value is at least `minLength` characters long
+-   `maxLength` - checks if value is at most `maxLength` characters long
+
+Also it can be defined either by shortcut:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate('string', 'something');
+    // { valid: true }
+    result = await validator.validate('string', 10);
+    // { valid: false, errors: [ 'expected type string, but saw number' ] }
+
+which is equal to:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate({
+        type: 'string',
+        isNullable: false,
+        isRequired: true
+    }, 1230);
+    // { valid: false }
+
+### Array
+
+`array` schema can be defined as follows:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+
+    // validates for non empty string no longer than 100 chars
+    let result = await validator.validate(
+        {
+            type: "array",
+            minLength: 5,
+            maxLength: 10,
+            ofType: {
+                type: "number",
+                min: 1,
+                max: 10
+            }
+        },
+        [5, 6, 7, 8, 9]
+    );
+    // { valid: true }
+
+All fields available (apart of common fields for all schemas) are:
+
+-   `ofType` - here you can pass the `schema` and all array elements will be checked to match this schema
+-   `minLength` - checks if array is at least `minLength` elements long
+-   `maxLength` - checks if array is at most `maxLength` elements long
+
+Also it can be defined either by shortcut:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate('array', []);
+    // { valid: true }
+    result = await validator.validate('array', 10);
+    // { valid: false, errors: [ 'expected array' ] }
+
+which is equal to:
+
+    import { SchemaValidator } from '@cleverbrush/schema';
+    const validator = new SchemaValidator();
+    let result = await validator.validate({
+        type: 'array'
+    }, 1230);
+    // { valid: false, errors: [ 'expected array' ] }
+
+### Object
+
+`object` type allows to define a complex object schema. For example:
+
+    await validator.validate(
+        {
+            type: "object",
+            properties: {
+                id: "number",
+                name: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 100,
+                },
+                address: {
+                    type: "object",
+                    properties: {
+                        city: "string",
+                        street: {
+                            type: "string",
+                            isRequired: false,
+                        },
+                    },
+                },
+            },
+        },
+        {
+            id: 10,
+            name: "Andrew",
+            address: {
+                city: "Madrid",
+            },
+        }
+    );
+    // {valid: true}
+
+All fields available are:
+
+-   `properties` - the list of properties, every property has corresponding schema definition (see example above).
+
+## Alternative schema
+
+Everywhere you pass a `schema` object to the library, you may pass an array of `schema` objects which will validate the object to match at least one schema from this list.
+For example, if you want to check that array is consisting either from number or from `{ name: string, value: number }` objects, you can do the following:
+
+    await validator.validate(
+        {
+        type: "array",
+        ofType: [
+            "number",
+            {
+            type: "object",
+            properties: {
+                name: "string",
+                value: "number",
+            },
+            },
+        ],
+        },
+        [
+        10,
+        { name: "something", value: 1 },
+        100,
+        { name: "another string", value: 1 },
+        ]
+    );
+    // {valid: true}
+
+## Named schemas
+
+There is a possibility to register a schema, give it a name and then reuse it:
+
+    const validator = new SchemaValidator().addSchemaType("Address", {
+    properties: {
+        id: {
+        type: "number",
+        min: 1,
+        },
+        street: "string",
+        zip: "number",
+    },
+    });
+
+    await validator.validate(
+        {
+        type: "object",
+        properties: {
+            name: "string",
+            address1: "Address",
+            address2: "Address",
+        },
+        },
+        {
+        name: "Andrew",
+        address1: {
+            id: 1,
+            street: "some street",
+            zip: 12345,
+        },
+        address2: {
+            id: 2,
+            street: "some street 2",
+            zip: 3456,
+        },
+        }
+    );
+
+    // { valid: true }
+
+## Examples {#examples}
+
+For Examples see unit tests in the schemaValidator.tests.ts

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import SchemaValidator from './schemaValidator';
+export declare type DefaultSchemaType = 'object' | 'function' | 'number' | 'string' | 'array';
+export declare type PropType<TObj, TProp extends keyof TObj> = TObj[TProp];
+export declare type DefaultPropertyDefinition = {
+    isRequired: boolean;
+    isNullable: boolean;
+};
+export declare type ValidationResultRaw = {
+    valid: boolean;
+    errors?: Array<string>;
+};
+export declare type ValidationResult = ValidationResultRaw | Promise<ValidationResultRaw>;
+export declare type Validator<TObj> = (value: TObj) => ValidationResult;
+export declare type SchemaDefintion<TObj> = {
+    type: DefaultSchemaType;
+    isRequired?: boolean;
+    isNullable?: boolean;
+    validators?: Array<Validator<TObj>>;
+};
+export declare type ObjectSchemaDefinition<T> = Omit<SchemaDefintion<T>, 'type'> & {
+    type: 'object';
+    extends?: string;
+    properties?: Partial<{
+        [S in keyof T]: Schema<PropType<T, S>>;
+    }>;
+};
+export declare type ObjectSchemaDefinitionParam<T> = Omit<ObjectSchemaDefinition<T>, 'type'>;
+export declare type ParamsValidators<TFunc extends (...args: any) => any> = {
+    [S in keyof Parameters<TFunc>]: SingleSchema<Parameters<TFunc>[S]>;
+};
+export declare type FunctionSchemaDefinition<T extends (...args: any) => any> = Omit<SchemaDefintion<T>, 'type'> & {
+    type: 'function';
+    params?: ParamsValidators<T>;
+};
+export declare type NumberSchemaDefinition<TObj> = Omit<SchemaDefintion<TObj>, 'type'> & {
+    type: 'number';
+    min?: number;
+    max?: number;
+    equals?: number;
+    isInteger?: boolean;
+    ensureNotNaN?: boolean;
+    ensureIsFinite?: boolean;
+};
+export declare type StringSchemaDefinition<TObj> = Omit<SchemaDefintion<TObj>, 'type'> & {
+    type: 'string';
+    equals?: string;
+    minLength?: number;
+    maxLength?: number;
+};
+export declare type ArraySchemaDefinition<TObj> = Omit<SchemaDefintion<TObj>, 'type'> & {
+    type: 'array';
+    ofType?: Schema<any>;
+    minLength?: number;
+    maxLength?: number;
+};
+export declare type CompositeSchema<TObj> = TObj extends (...args: any) => any ? FunctionSchemaDefinition<TObj> : TObj extends number ? NumberSchemaDefinition<TObj> : TObj extends string ? StringSchemaDefinition<TObj> | 'string' : NumberSchemaDefinition<TObj> | StringSchemaDefinition<TObj> | ArraySchemaDefinition<TObj> | ObjectSchemaDefinition<TObj>;
+export declare type SingleSchema<TObj = Record<string, never>> = number | string | DefaultSchemaType | CompositeSchema<TObj>;
+export declare type Schema<TObj> = SingleSchema<TObj> | Array<SingleSchema<TObj>>;
+export interface ISchemaActions<K, T extends keyof K> {
+    validate(value: any): Promise<ValidationResult>;
+    schema: PropType<K, T>;
+}
+export interface ISchemasProvider<T = Record<string, never>> {
+    schemas: {
+        [K in keyof T]: ISchemaActions<T, K>;
+    };
+}
+export interface ISchemaValidator<T = Record<string, never>> {
+    addSchemaType<K, L extends ObjectSchemaDefinitionParam<M>, M = any>(name: keyof K, schema: L): SchemaValidator<T & {
+        [key in keyof K]: L;
+    }>;
+    validate(schema: keyof T | DefaultSchemaType | Schema<any>, obj: any): Promise<ValidationResult>;
+}
+export { SchemaValidator };
+export default SchemaValidator;

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidator = void 0;
+const schemaValidator_1 = __importDefault(require("./schemaValidator"));
+exports.SchemaValidator = schemaValidator_1.default;
+exports.default = schemaValidator_1.default;

package/dist/schemaValidator.d.ts

@@ -0,0 +1,14 @@
+import { ISchemasProvider, Schema, ISchemaActions, ObjectSchemaDefinitionParam, ValidationResult, ISchemaValidator, DefaultSchemaType } from './index';
+export default class SchemaValidator<T = Record<string, never>> implements ISchemasProvider<T>, ISchemaValidator<T> {
+    private _schemasMap;
+    private _schemasCache;
+    addSchemaType<K, L extends ObjectSchemaDefinitionParam<M>, M = any>(name: keyof K, schema: L): SchemaValidator<T & {
+        [key in keyof K]: L;
+    }>;
+    get schemas(): {
+        [K in keyof T]: ISchemaActions<T, K>;
+    };
+    private validateDefaultType;
+    private checkValidators;
+    validate(schema: keyof T | DefaultSchemaType | Schema<any>, obj: any): Promise<ValidationResult>;
+}

package/dist/schemaValidator.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const deep_1 = require("@cleverbrush/deep");
+const validateNumber_1 = require("./validators/validateNumber");
+const validateString_1 = require("./validators/validateString");
+const validateArray_1 = require("./validators/validateArray");
+const validateObject_1 = require("./validators/validateObject");
+const defaultSchemaNames = ['string', 'number', 'date', 'array'];
+const defaultSchemas = {
+    number: {
+        type: 'number',
+        isRequired: true,
+        isNullable: false,
+        ensureNotNaN: true,
+        ensureIsFinite: true
+    },
+    string: {
+        type: 'string',
+        isNullable: false,
+        isRequired: true
+    },
+    array: {
+        type: 'array'
+    },
+    object: {
+        type: 'object',
+        isNullable: false,
+        isRequired: true
+    }
+};
+const defaultSchemasValidationStrategies = {
+    number: (obj, schema, validator) => (0, validateNumber_1.validateNumber)(obj, schema, validator),
+    string: (obj, schema, validator) => (0, validateString_1.validateString)(obj, schema, validator),
+    array: (obj, schema, validator) => (0, validateArray_1.validateArray)(obj, schema, validator)
+};
+const isDefaultType = (name) => defaultSchemaNames.indexOf(name) !== -1;
+class SchemaValidator {
+    _schemasMap = new Map();
+    _schemasCache = null;
+    addSchemaType(name, schema) {
+        if (typeof name !== 'string' || !name)
+            throw new Error('Name is required');
+        if (typeof schema !== 'object')
+            throw new Error('Object is required');
+        if (isDefaultType(name.toString()))
+            throw new Error(`You can't add a schema named "${name}" because it's a name of a default schema, please consider another name to be used`);
+        if (this._schemasMap.has(name.toString())) {
+            throw new Error(`Schema "${name}" already exists`);
+        }
+        this._schemasMap.set(name.toString(), {
+            ...schema,
+            type: 'object'
+        });
+        this._schemasCache = null;
+        return this;
+    }
+    get schemas() {
+        if (this._schemasCache)
+            return this._schemasCache;
+        const res = {};
+        for (const key of this._schemasMap.keys()) {
+            res[key] = {
+                validate: (value) => this.validate(this._schemasMap.get(key), value),
+                schema: this._schemasMap.get(key)
+            };
+        }
+        this._schemasCache = res;
+        return this._schemasCache;
+    }
+    async validateDefaultType(name, value, mergeSchema) {
+        const strategy = defaultSchemasValidationStrategies[name];
+        let finalSchema = defaultSchemas[name];
+        if (strategy) {
+            if (typeof mergeSchema === 'object') {
+                finalSchema = (0, deep_1.deepExtend)(finalSchema, mergeSchema);
+            }
+            if (typeof mergeSchema === 'number') {
+                finalSchema = {
+                    ...finalSchema,
+                    equals: mergeSchema
+                };
+                mergeSchema;
+            }
+            let preliminaryResult = await strategy(value, finalSchema, this);
+            if (!preliminaryResult.valid)
+                return preliminaryResult;
+            preliminaryResult = await this.checkValidators(finalSchema, value);
+            return preliminaryResult;
+        }
+        throw new Error('not implemented');
+    }
+    async checkValidators(schema, value) {
+        if (Array.isArray(schema.validators)) {
+            const validatorsResults = await Promise.allSettled(schema.validators.map((v) => Promise.resolve(v(value))));
+            const rejections = validatorsResults
+                .filter((f) => f.status === 'rejected')
+                .map((f) => f.reason);
+            const errors = validatorsResults
+                .filter((f) => f.status === 'fulfilled' &&
+                typeof f.value !== 'boolean' &&
+                f.value.valid === false)
+                .map((f) => f.value)
+                .map((f) => f.errors);
+            if (rejections.length === 0 && errors.length === 0) {
+                return {
+                    valid: true
+                };
+            }
+            return {
+                valid: false,
+                errors: [...rejections, ...errors]
+            };
+        }
+        return {
+            valid: true
+        };
+    }
+    async validate(schema, obj) {
+        if (!schema)
+            throw new Error('schemaName is required');
+        if (typeof schema === 'string') {
+            if (isDefaultType(schema)) {
+                return await this.validateDefaultType(schema, obj);
+            }
+            else if (typeof this.schemas[schema] !== 'undefined') {
+                const objSchema = (0, deep_1.deepExtend)(defaultSchemas.object, this.schemas[schema].schema);
+                const res = await (0, validateObject_1.validateObject)(obj, objSchema, this);
+                if (!res.valid)
+                    return res;
+                return await this.checkValidators(objSchema, obj);
+            }
+            else {
+                return await this.validateDefaultType('string', obj, {
+                    type: 'string',
+                    equals: schema
+                });
+            }
+        }
+        if (Array.isArray(schema)) {
+            for (let i = 0; i < schema.length; i++) {
+                const res = await this.validate(schema[i], obj);
+                if (res.valid) {
+                    return res;
+                }
+            }
+            return {
+                valid: false,
+                errors: ['object does not match any schema']
+            };
+        }
+        if (typeof schema === 'number') {
+            return await this.validateDefaultType('number', obj, schema);
+        }
+        if (typeof schema === 'object') {
+            if (typeof schema.type !== 'string')
+                throw new Error('Schema has no type');
+            if (isDefaultType(schema.type)) {
+                return await this.validateDefaultType(schema.type, obj, schema);
+            }
+            else if (schema.type === 'object') {
+                const preliminaryResult = await (0, validateObject_1.validateObject)(obj, schema, this);
+                if (!preliminaryResult.valid)
+                    return preliminaryResult;
+                return await this.checkValidators(schema, obj);
+            }
+        }
+        throw new Error("Coldn't understand the Schema provided");
+    }
+}
+exports.default = SchemaValidator;

package/dist/validators/validateArray.d.ts

@@ -0,0 +1,2 @@
+import { ValidationResult, ArraySchemaDefinition, ISchemaValidator } from '../index';
+export declare const validateArray: (obj: any, schema: ArraySchemaDefinition<any>, validator: ISchemaValidator<any>) => Promise<ValidationResult>;

package/dist/validators/validateArray.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateArray = void 0;
+const validateArray = async (obj, schema, validator) => {
+    if (typeof obj === 'undefined' &&
+        typeof schema === 'object' &&
+        schema.isRequired === false) {
+        return {
+            valid: true
+        };
+    }
+    if (!Array.isArray(obj))
+        return {
+            valid: false,
+            errors: ['expected type array']
+        };
+    if (typeof schema.minLength === 'number' && obj.length < schema.minLength) {
+        return {
+            valid: false,
+            errors: [`expected to be at least ${schema.minLength} chars long`]
+        };
+    }
+    if (typeof schema.maxLength === 'number' && obj.length > schema.maxLength) {
+        return {
+            valid: false,
+            errors: [`expected to be at most ${schema.maxLength} chars long`]
+        };
+    }
+    if (typeof schema.ofType !== 'undefined') {
+        const results = await Promise.all(obj.map((i) => validator.validate(schema.ofType, i)));
+        const errors = results
+            .filter((r) => !r.valid)
+            .map((r) => r.errors)
+            .flat(Infinity);
+        if (errors.length) {
+            return {
+                valid: false,
+                errors
+            };
+        }
+        return {
+            valid: true
+        };
+    }
+    return {
+        valid: true
+    };
+};
+exports.validateArray = validateArray;

package/dist/validators/validateNumber.d.ts

@@ -0,0 +1,2 @@
+import { ValidationResult, NumberSchemaDefinition, ISchemaValidator } from '../index';
+export declare const validateNumber: (obj: any, schema: NumberSchemaDefinition<any>, validator: ISchemaValidator<any>) => Promise<ValidationResult>;

package/dist/validators/validateNumber.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNumber = void 0;
+const validateNumber = async (obj, schema, validator) => {
+    if (typeof obj === 'undefined' &&
+        typeof schema === 'object' &&
+        schema.isRequired === false) {
+        return {
+            valid: true
+        };
+    }
+    if (typeof obj !== 'number')
+        return {
+            valid: false,
+            errors: [`expected type number, but saw ${typeof obj}`]
+        };
+    if (typeof schema === 'number') {
+        return obj === schema
+            ? { valid: true }
+            : {
+                valid: false,
+                errors: [`should be equal to ${schema}`]
+            };
+    }
+    const num = obj;
+    if (schema.ensureNotNaN && Number.isNaN(num)) {
+        return {
+            valid: false,
+            errors: ['is not expected to be NaN']
+        };
+    }
+    if (schema.ensureIsFinite &&
+        !Number.isFinite(num) &&
+        schema.ensureNotNaN &&
+        !Number.isNaN(num)) {
+        return {
+            valid: false,
+            errors: ['is expected to be a finite number']
+        };
+    }
+    if (typeof schema.equals !== 'undefined' && num !== schema.equals) {
+        return {
+            valid: false,
+            errors: [`expected to be equal to ${schema.equals}`]
+        };
+    }
+    if (typeof schema.min !== 'undefined') {
+        if (typeof schema.min !== 'number')
+            throw new Error('min constraint should be a number');
+        if (num < schema.min)
+            return {
+                valid: false,
+                errors: [`expected to be at least ${schema.min}`]
+            };
+    }
+    if (typeof schema.max !== 'undefined') {
+        if (typeof schema.max !== 'number')
+            throw new Error('max constraint should be a number');
+        if (num > schema.max)
+            return {
+                valid: false,
+                errors: [`expected to be no more than ${schema.max}`]
+            };
+    }
+    return {
+        valid: true
+    };
+};
+exports.validateNumber = validateNumber;

package/dist/validators/validateObject.d.ts

@@ -0,0 +1,2 @@
+import { ValidationResult, ObjectSchemaDefinition, ISchemaValidator } from '../index';
+export declare const validateObject: (obj: any, schema: ObjectSchemaDefinition<any>, validator: ISchemaValidator<any>) => Promise<ValidationResult>;