@cleverbrush/schema 1.0.0-beta.5 → 1.1.0

package/README.md

@@ -1,354 +1,152 @@
-# Object Schema Validator
+This package resides in `@cleverbrush/schema` and contains utilities to define object schemas. Once created a Schema can be used to infer type and validate objects for satisfaction of the Schema.
 
-This package contains utilities to validate the JavaScript object's schema. There is only one class exported - `SchemaValidator`
+The library is covered with unit-tests to make sure it works correctly.
 
-## 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 section at the bottom of this page)
+## Installation
 
-### Number
-
-`number` schema can be defined as follows:
-
-```typescript
-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
-);
+```bash
+    npm install @cleverbrush/schema
 ```
 
-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:
+### An example:
 
 ```typescript
-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 { InferType, object, number, string, date } from '@cleverbrush/schema';
 
-```typescript
-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:
-
-```typescript
-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:
-
-```typescript
-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' ] }
-```
+const UserSchema = object({
+    id: number(),
+    name: string(),
+    dateOfBirth: date().optional()
+});
 
-or by detailed descriptor:
+// user has { id: number; name: string; dateOfBirth?: Date } type
+const user: InferType<typeof UserSchema> = {
+    //...
+};
 
-```typescript
-import { SchemaValidator } from '@cleverbrush/schema';
-
-const validator = new SchemaValidator();
-
-let result = await validator.validate(
-    {
-        type: 'string',
-        isNullable: false,
-        isRequired: true
-    },
-    1230
-);
-// { valid: false }
+const { valid, object: result, errors } = await UserSchema.validate(user);
 ```
 
-### Array
+Type inference can be used even on clean JavaScript (without TypeScript):
 
-`array` schema can be defined as follows:
+```javascript
+const { valid, object, errors } = await UserSchema.validate(someObject);
 
-```typescript
-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 }
+if (valid) {
+    // someObject satisfies UserSchema.
+    // And `object` has { id: number; name: string; dateOfBirth: Date; } type.
+} else {
+    // someObject does not satisfy UserSchema which means that
+    // `errors` contains a list of errors.
+}
 ```
 
-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:
-
-```typescript
-import { SchemaValidator } from '@cleverbrush/schema';
-
-const validator = new SchemaValidator();
+Another way to have types using just Javascript is to make use of JSDoc:
 
-let result = await validator.validate('array', []);
-// { valid: true }
-result = await validator.validate('array', 10);
-// { valid: false, errors: [ 'expected array' ] }
+```javascript
+/**
+ * @type {import('@cleverbrush/schema').InferType<typeof UserSchema>}
+ */
+const user = {
+    // inferred type is { id: number; name: string; dateOfBirth?: Date }
+};
 ```
 
-or by detailed descriptor:
+See [Documentation](https://docs.cleverbrush.com/v1.0/modules/Schema_Definition_And_Validation.html) or `docs` folder for more information.
 
-```typescript
-import { SchemaValidator } from '@cleverbrush/schema';
-
-const validator = new SchemaValidator();
-
-let result = await validator.validate(
-    {
-        type: 'array'
-    },
-    1230
-);
-// { valid: false, errors: [ 'expected array' ] }
-```
-
-### Object
+## Schema Types
 
-`object` type allows to define a complex object schema. For example:
+There are several schema types available out of the box:
+
+-   `any` - any object. Similar to the `any` type in TypeScript.
+-   `string` - string value.
+-   `number` - number value.
+-   `boolean` - boolean value.
+-   `func` - function value.
+-   `object` - object schema (you can define list of properties, along with schemas for every property).
+-   `date` - defines object of JavaScript `Date` class.
+-   `array` - defines array, you can define a schema for Array emelement.
+-   `union` - allows to define unions. e.g. `string | number` types (or any combination off schema types from this list).
+-   custom schema types. You just need to inherit `SchemaBuilder` abstract class to implement your own schema type.
+
+## What is exported from the library?
+
+Library exports several functions used to define schemas:
+
+-   `any`
+-   `string`
+-   `number`
+-   `boolean`
+-   `func`
+-   `object`
+-   `date`
+-   `array`
+-   `union`
+
+All these functions returns so called schema builders.
+Schema builder classes are also exported (in case if you want to develop your own schema builder based on it):
+
+-   `AnySchemaBuilder`
+-   `ArraySchemaBuilder`
+-   `BooleanSchemaBuilder`
+-   `DateSchemaBuilder`
+-   `FunctionSchemaBuilder`
+-   `ObjectSchemaBuilder`
+-   `NumberSchemaBuilder`
+-   `SchemaBuilder` - abstract class.
+-   `StringSchemaBuilder`
+-   `UnionSchemaBuilder`
+
+## Schema Builders Are Immutable
+
+All schema builders listed above are immutable, which means that every call of it's methods should return a new Schema builder.
+For example in the example below call to the `.optional()` method will not affect `UserSchema` or any other schemas using it. Instead it will return a new schema builder:
+
+```ts
+const UserSchema = object({
+    id: number(),
+    email: string()
+});
 
-```typescript
-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}
+const OrderSchema = object({
+    id: number(),
+    createdByUser: UserSchema.optional()
+});
 ```
 
-All fields available are:
-
--   `noUnknownProperties` - Validator will return an error if this field is set to `true` and validated objects contain fields not defined in the object schema. Equals to `false` by default.
--   `properties` - the list of properties, every property has corresponding schema definition (see example above).
+By combining immutable schema builders with TypeScript type inference you can create very powerful schemas
+which can be used to validate objects and infer their types.
 
-## Alternative schema
+Every schema is built using a chain/superposition of calls to the schema builder methods. For example:
 
-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:
-
-```typescript
-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}
+```ts
+const UserSchema = object({
+    id: number(),
+    email: string()
+})
+    .optional()
+    .addProps({
+        name: string()
+    });
 ```
 
-## Named schemas
-
-There is a possibility to register a schema, give it a name and then reuse it:
+In the example above `UserSchema` is an object schema with two properties: `id` and `email`. It is also optional and has an additional property `name`.
 
-```typescript
-const validator = new SchemaValidator().addSchemaType('Address', {
-    properties: {
-        id: {
-            type: 'number',
-            min: 1
-        },
-        street: 'string',
-        zip: 'number'
-    }
-});
+There is also a way to define union schemas. For example example below defines an array of strings or numbers
+having at least two elements, but not more than 5:
 
-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 }
+```ts
+const StringOrNumberArraySchema = array()
+    .minLength(2)
+    .maxLength(5)
+    .of(union(string()).or(number()));
 ```
 
-Also there is a possibility to organize schemas in modules (or even submodules):
+You can go further and restrict number to be in the range of 0 to 100 by adding more constraints:
 
-```typescript
-const validator = new SchemaValidator()
-    .addSchemaType('Module1.DTOs.Address', {
-        properties: {
-            id: {
-                type: 'number',
-                min: 1
-            },
-            street: 'string',
-            zip: 'number'
-        }
-    })
-    .addSchemaType('Module1.Models.Person', {
-        properties: {
-            firstName: 'string',
-            lastName: 'string'
-        }
-    });
-
-const resultPerson = await validator.schemas.Module1.Models.Person.validate({
-    fistName: 'John',
-    lastName: 'Smith'
-});
-
-const resultAddress = await validator.schemas.Module1.DTOs.Address.validate({});
+```ts
+const StringOrNumberArraySchema = array()
+    .minLength(2)
+    .maxLength(5)
+    .of(union(string()).or(number().min(0).max(100)));
 ```
-
-## Examples
-
-For Examples see unit tests in the schemaValidator.tests.ts

package/dist/builders/AnySchemaBuilder.d.ts

@@ -0,0 +1,76 @@
+import { SchemaBuilder, ValidationResult, ValidationContext } from './SchemaBuilder.js';
+type AnySchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<AnySchemaBuilder<R>['introspect']>>;
+/**
+ * Any schema builder class. Similar to the `any` type
+ * in TypeScript. Allows to define a schema for `any` value.
+ * Use it when you don't know the type of the 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 `any()` function instead.
+ *
+ * @example
+ * ```ts
+ * const schema = any();
+ * const result = await schema.validate(123);
+ * // result.valid === true
+ * // result.object === 123
+ * ```
+ */
+export declare class AnySchemaBuilder<TRequired extends boolean = true, TExplicitType = undefined, TResult = TExplicitType extends undefined ? any : TExplicitType> extends SchemaBuilder<TResult, TRequired> {
+    /**
+     * @hidden
+     */
+    static create(props: AnySchemaBuilderCreateProps<any>): AnySchemaBuilder<true, undefined, any>;
+    private constructor();
+    /**
+     * @hidden
+     */
+    hasType<T>(notUsed?: T): AnySchemaBuilder<true, T>;
+    /**
+     * @hidden
+     */
+    clearHasType(): AnySchemaBuilder<TRequired, undefined>;
+    /**
+     * Performs validation 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: AnySchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @hidden
+     */
+    required(): AnySchemaBuilder<true, TExplicitType>;
+    /**
+     * @hidden
+     */
+    optional(): AnySchemaBuilder<false, TExplicitType>;
+}
+/**
+ * Creates a `any` schema.
+ * @example
+ * ```
+ *  const anyObject = any();
+ *
+ * // null - invalid
+ * // undefined - invalid
+ * // string - valid
+ * // {} - valid
+ * // Date -valid
+ * // { someProp: 123 } - valid
+ * // etc
+ * ```
+ * @example
+ * ```
+ *  const anyObject = any().optional();
+ *  // null - valid
+ *  // undefined - valid
+ *  // string - valid
+ *  // {} - valid
+ *  // Date -valid
+ *  // { someProp: 123 } - valid
+ * ```
+ */
+export declare const any: () => AnySchemaBuilder<true, undefined, any>;
+export {};

package/dist/builders/AnySchemaBuilder.js

@@ -0,0 +1,112 @@
+import { SchemaBuilder } from './SchemaBuilder.js';
+/**
+ * Any schema builder class. Similar to the `any` type
+ * in TypeScript. Allows to define a schema for `any` value.
+ * Use it when you don't know the type of the 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 `any()` function instead.
+ *
+ * @example
+ * ```ts
+ * const schema = any();
+ * const result = await schema.validate(123);
+ * // result.valid === true
+ * // result.object === 123
+ * ```
+ */
+export class AnySchemaBuilder extends SchemaBuilder {
+    /**
+     * @hidden
+     */
+    static create(props) {
+        return new AnySchemaBuilder({
+            type: 'any',
+            ...props
+        });
+    }
+    constructor(props) {
+        super(props);
+    }
+    /**
+     * @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 validation 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, transaction: preValidationTransaction, errors } = superResult;
+        if (!valid) {
+            return {
+                valid,
+                errors
+            };
+        }
+        const { object: { validatedObject: objToValidate } } = preValidationTransaction;
+        return {
+            valid: true,
+            object: objToValidate
+        };
+    }
+    createFromProps(props) {
+        return AnySchemaBuilder.create(props);
+    }
+    /**
+     * @hidden
+     */
+    required() {
+        return super.required();
+    }
+    /**
+     * @hidden
+     */
+    optional() {
+        return super.optional();
+    }
+}
+/**
+ * Creates a `any` schema.
+ * @example
+ * ```
+ *  const anyObject = any();
+ *
+ * // null - invalid
+ * // undefined - invalid
+ * // string - valid
+ * // {} - valid
+ * // Date -valid
+ * // { someProp: 123 } - valid
+ * // etc
+ * ```
+ * @example
+ * ```
+ *  const anyObject = any().optional();
+ *  // null - valid
+ *  // undefined - valid
+ *  // string - valid
+ *  // {} - valid
+ *  // Date -valid
+ *  // { someProp: 123 } - valid
+ * ```
+ */
+export const any = () => AnySchemaBuilder.create({
+    isRequired: true
+});