added sync validation support, refactored custom decorators signature and other small refactorings

Author: Umed Khudoiberdiev

README.md

@@ -6,24 +6,45 @@
 [![Dependency Status](https://david-dm.org/pleerock/class-validator.svg)](https://david-dm.org/pleerock/class-validator)
 [![devDependency Status](https://david-dm.org/pleerock/class-validator/dev-status.svg)](https://david-dm.org/pleerock/class-validator#info=devDependencies)
 
-Allows use of decorator and non-decorator based validation. Internally uses [validator.js][1] to perform validation.
+Allows use of decorator and non-decorator based validation.
+Internally uses [validator.js][1] to perform validation.
+Class-validator works on both browser and node.js platforms.
 
 ## Installation
 
-1. Install module:
+Install module:
 
-    `npm install class-validator --save`
+`npm install class-validator --save`
 
-2. ES6 features are used, so you may want to install [es6-shim](https://github.com/paulmillr/es6-shim) too:
+#### Old versions of node.js/browser
 
-    `npm install es6-shim --save`
+ES6 features are used, if you are using old versions of node (or browser) you may want to install [es6-shim](https://github.com/paulmillr/es6-shim) too:
 
-    and use it somewhere in the global place of your app:
+`npm install es6-shim --save`
 
-    * for nodejs: `require("es6-shim")` (or `import "es6-shim";`) in your app's entry point (for example in `app.ts`)
-    * for browser: `<script src="node_modules/es6-shim/es6-shim.js">` in your `index.html`
+and use it somewhere in the global place of your app:
 
-    For node.js users this step is only required if you are using old versions of node.
+* for nodejs: `require("es6-shim")` (or `import "es6-shim";`) in your app's entry point (for example in `app.ts`)
+* for browser: `<script src="node_modules/es6-shim/es6-shim.js">` in your `index.html`
+
+This step is only required if you are using old versions of node/browser.
+
+#### Using in browser
+
+If you are using class-validator with system.js in browser then use following configuration:
+
+```javascript
+System.config({
+    map: {
+        'class-validator': 'vendor/class-validator',
+        'validator': 'vendor/validator'
+    },
+    packages: {
+        'class-validator': { 'defaultExtension': 'js', 'main': 'index.js' },
+        'validator': { 'defaultExtension': 'js', 'main': 'validator.js' },
+    }
+};
+```
 
 ## Usage
 
@@ -295,7 +316,7 @@ If you have custom validation logic you can create a *Constraint class*:
     ```typescript
     import {ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments} from "class-validator";
 
-    @ValidatorConstraint()
+    @ValidatorConstraint({ name: "customText", async: false })
     export class CustomTextLength implements ValidatorConstraintInterface {
 
         validate(text: string, args: ValidationArguments) {
@@ -389,17 +410,25 @@ Lets create a decorator called `@IsLongerThan`:
 1. Create a decorator itself:
 
     ```typescript
-    import {registerDecorator, ValidationOptions} from "class-validator";
+    import {registerDecorator, ValidationOptions, ValidationArguments} from "class-validator";
 
     export function IsLongerThan(property: string, validationOptions?: ValidationOptions) {
        return function (object: Object, propertyName: string) {
-           registerDecorator(object, propertyName, validationOptions, [property], "is_longer_than", (value, args) => {
-               const [relatedPropertyName] = args.constraints;
-               const relatedValue = (args.object as any)[relatedPropertyName];
-               return  typeof value === "string" &&
-                       typeof relatedValue === "string" &&
-                       value.length > relatedValue.length; // you can return a Promise<boolean> here as well, if you want to make async validation
-           });
+            registerDecorator({
+                name: "isLongerThan",
+                target: object.constructor,
+                propertyName: propertyName,
+                options: validationOptions,
+                validator: {
+                    validate(value: any, args: ValidationArguments) {
+                        const [relatedPropertyName] = args.constraints;
+                        const relatedValue = (args.object as any)[relatedPropertyName];
+                        return  typeof value === "string" &&
+                               typeof relatedValue === "string" &&
+                               value.length > relatedValue.length; // you can return a Promise<boolean> here as well, if you want to make async validation
+                    }
+                }
+            });
        };
     }
     ```
@@ -430,7 +459,7 @@ Lets create another custom validation decorator called `IsUserAlreadyExist`:
     ```typescript
     import {registerDecorator, ValidationOptions, ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments} from "class-validator";
 
-    @ValidatorConstraint()
+    @ValidatorConstraint({ async: true })
     export class IsUserAlreadyExistConstraint implements ValidatorConstraintInterface {
 
         validate(userName: any, args: ValidationArguments) {
@@ -444,11 +473,19 @@ Lets create another custom validation decorator called `IsUserAlreadyExist`:
 
     export function IsUserAlreadyExist(validationOptions?: ValidationOptions) {
        return function (object: Object, propertyName: string) {
-           registerDecorator(object, propertyName, validationOptions, [], IsUserAlreadyExistConstraint);
+            registerDecorator({
+                target: object.constructor,
+                propertyName: propertyName,
+                options: validationOptions,
+                constraints: [],
+                validator: IsUserAlreadyExistConstraint
+            });
        };
     }
     ```
 
+    note that we marked our constraint that it will by async by adding `{ async: true }` in validation options.
+
 2. And put it to use:
 
     ```typescript
@@ -481,6 +518,12 @@ let validator = Container.get(Validator);
 // also you can inject classes using constructor injection into your custom ValidatorConstraint-s
 ```
 
+## Synchronous validation
+
+If you want to perform a simple non async validation you can use `validateSync` method instead of regular `validate`
+ method. It has the same arguments as `validate` method. But note, this method **ignores** all async validations
+ you have.
+
 ## Manual validation
 
 There are several method exist in the Validator that allows to perform non-decorator based validation:

doc/release-notes.md

@@ -1,10 +1,18 @@
 # Release notes
 
+**0.5.0**
+
+* async validations must be marked with `{ async: true }` option now.
+This is optional, but it helps to determine which decorators are async to prevent their execution in `validateSync` method.
+* added `validateSync` method that performs non asynchronous validation and ignores validations that marked with `async: true`.
+* there is a breaking change in `registerDecorator` method. Now it accepts options object.
+* breaking change with `@ValidatorConstraint` decorator. Now it accepts option object instead of single name.
+
 **0.4.1**
 
 * fixed issue with wrong source maps packaged
 
-**0.4.0** *[BREAKING CHANGES]*
+**0.4.0**
 
 * everything should be imported from "class-validator" main entry point now
 * `ValidatorInterface` has been renamed to `ValidatorConstraintInterface`

package.json

@@ -1,8 +1,8 @@
 {
   "name": "class-validator",
   "private": true,
-  "version": "0.4.1",
-  "description": "Class-based validation in Typescript using decorators",
+  "version": "0.5.0-alpha.1",
+  "description": "Class-based validation with Typescript / ES6 / ES5 using decorators or validation schemas. Supports both node.js and browser",
   "license": "MIT",
   "readmeFilename": "README.md",
   "author": {

sample/sample6-custom-decorator/IsLongerThan.ts

@@ -6,11 +6,17 @@ import {ValidationArguments} from "../../src/validation/ValidationArguments";
 
 export function IsLongerThan(property: string, validationOptions?: ValidationOptions) {
     return function (object: Object, propertyName: string) {
-        registerDecorator(object, propertyName, validationOptions, [property], IsLongerThanConstraint);
+        registerDecorator({
+            target: object.constructor,
+            propertyName: propertyName,
+            options: validationOptions,
+            constraints: [property],
+            validator: IsLongerThanConstraint
+        });
     };
 }
 
-@ValidatorConstraint("is_longer_than")
+@ValidatorConstraint({ name: "isLongerThan" })
 export class IsLongerThanConstraint implements ValidatorConstraintInterface {
 
     validate(value: any, args: ValidationArguments) {

sample/sample6-custom-decorator/IsUserAlreadyExist.ts

@@ -4,15 +4,23 @@ import {ValidationArguments} from "../../src/validation/ValidationArguments";
 
 export function IsUserAlreadyExist(validationOptions?: ValidationOptions) {
     return function (object: Object, propertyName: string) {
-        const constraints: any[] = [/*constraints your decorator can have*/];
-        registerDecorator(object, propertyName, validationOptions, constraints, "user_exists", (userName, args) => {
-            return new Promise(ok => {
-                if (userName !== "admin" && userName !== "user") {
-                    ok(true);
-                } else {
-                    ok(false);
+        registerDecorator({
+            name: "isUserAlreadyExist",
+            async: true,
+            target: object.constructor,
+            propertyName: propertyName,
+            options: validationOptions,
+            validator: {
+                validate(value: any, args: ValidationArguments) {
+                    return new Promise(ok => {
+                        if (value !== "admin" && value !== "user") {
+                            ok(true);
+                        } else {
+                            ok(false);
+                        }
+                    });
                 }
-            });
+            }
         });
     };
 }

src/container.ts

@@ -0,0 +1,63 @@
+
+/**
+ * Container options.
+ */
+export interface UseContainerOptions {
+
+    /**
+     * If set to true, then default container will be used in the case if given container haven't returned anything.
+     */
+    fallback?: boolean;
+
+    /**
+     * If set to true, then default container will be used in the case if given container thrown an exception.
+     */
+    fallbackOnErrors?: boolean;
+
+}
+
+/**
+ * Container to be used by this library for inversion control. If container was not implicitly set then by default
+ * container simply creates a new instance of the given class.
+ */
+const defaultContainer: { get<T>(someClass: { new (...args: any[]): T }|Function): T } = new (class {
+    private instances: any[] = [];
+    get<T>(someClass: { new (...args: any[]): T }): T {
+        if (!this.instances[someClass as any])
+            this.instances[someClass as any] = new someClass();
+
+        return this.instances[<any>someClass];
+    }
+})();
+
+let userContainer: { get<T>(someClass: { new (...args: any[]): T }|Function): T };
+let userContainerOptions: UseContainerOptions;
+
+/**
+ * Sets container to be used by this library.
+ */
+export function useContainer(iocContainer: { get(someClass: any): any }, options?: UseContainerOptions) {
+    userContainer = iocContainer;
+    userContainerOptions = options;
+}
+
+/**
+ * Gets the IOC container used by this library.
+ */
+export function getFromContainer<T>(someClass: { new (...args: any[]): T }|Function): T {
+    if (userContainer) {
+        try {
+            const instance = userContainer.get(someClass);
+            if (instance)
+                return instance;
+
+            if (!userContainerOptions || !userContainerOptions.fallback)
+                return instance;
+
+        } catch (error) {
+            if (!userContainerOptions || !userContainerOptions.fallbackOnErrors)
+                throw error;
+        }
+    }
+    return defaultContainer.get<T>(someClass);
+}

src/decorator/decorators.ts

@@ -14,14 +14,15 @@ import {MetadataStorage} from "../metadata/MetadataStorage";
 /**
  * Registers custom validator class.
  */
-export function ValidatorConstraint(name?: string) {
+export function ValidatorConstraint(options?: { name?: string, async?: boolean }) {
     return function(target: Function) {
         if (!name) {
             name = (target as any).name;
             if (!name) // generate name if it was not given
                 name = name.replace(/\.?([A-Z]+)/g, (x, y) => "_" + y.toLowerCase()).replace(/^_/, "");
         }
-        getFromContainer(MetadataStorage).addConstraintMetadata(new ConstraintMetadata(target, name));
+        const metadata = new ConstraintMetadata(target, name, options && options.async ? true : false);
+        getFromContainer(MetadataStorage).addConstraintMetadata(metadata);
     };
 }