A simple plugin for class-transformer and class-validator which combines them in a nice and programmer-friendly API.
npm install class-transformer-validator --save
(or the short way):
npm i -S class-transformer-validator
This package is only a simple plugin/wrapper, so you have to install the required modules too because it can't work without them. See detailed installation instruction for the modules installation:
The usage of this module is very simple.
import { IsEmail } from "class-validator";
import { transformAndValidate } from "class-transformer-validator";
// declare the class using class-validator decorators
class User {
@IsEmail()
public email: string;
public hello(): string {
return "World!";
}
}
// then load the JSON string from any part of your app
const userJson: string = loadJsonFromSomething();
// transform the JSON to class instance and validate it correctness
transformAndValidate(User, userJson)
.then((userObject: User) => {
// now you can access all your class prototype method
console.log(`Hello ${userObject.hello()}`); // prints "Hello World!" on console
})
.catch(err => {
// here you can handle error on transformation (invalid JSON)
// or validation error (e.g. invalid email property)
console.error(err);
});
You can also transform and validate plain JS object (e.g. from express req.body). Using ES7 async/await syntax:
async (req, res) => {
try {
// transform and validate request body
const userObject = await transformAndValidate(User, req.body);
// infered type of userObject is User, you can access all class prototype properties and methods
} catch (err) {
// your error handling
console.error(err);
}
};
And since release 0.3.0
you can also pass array of objects - all of them will be validated using given class validation constraints:
async (req, res) => {
try {
// transform and validate request body - array of User objects
const userObjects = await transformAndValidate(User, req.body);
userObjects.forEach(user => console.log(`Hello ${user.hello()}`));
} catch (err) {
// your error handling
}
};
There is available the transformAndValidate
function with three overloads:
function transformAndValidate<T extends object>(
classType: ClassType<T>,
jsonString: string,
options?: TransformValidationOptions,
): Promise<T | T[]>;
function transformAndValidate<T extends object>(
classType: ClassType<T>,
object: object,
options?: TransformValidationOptions,
): Promise<T>;
function transformAndValidate<T extends object>(
classType: ClassType<T>,
array: object[],
options?: TransformValidationOptions,
): Promise<T[]>;
Be aware that if you validate json string, the return type is a Promise
of T
or T[]
so you need to assert the returned type if you know the shape of json:
const users = (await transformAndValidate(
User,
JSON.stringify([{ email: "test@test.test" }]),
)) as User[];
Or you can just check the type in runtime using Array.isArray
method.
If you need sync validation, use transformAndValidateSync
function instead (available since v0.4.0). It will synchronously return T
or T[]
, not a Promise.
classType
- an class symbol, a constructor function which can be called with new
type ClassType<T> = {
new (...args: any[]): T;
};
jsonString
- a normal string containing JSON
object
- plain JS object of type object
(introduced in TypeScript 2.2), you will have compile-time error while trying to pass number, boolean, null or undefined but unfortunately run-time error when passing a function
array
- array of plain JS objects like described above
options
- optional options object, it has two optional properties
interface TransformValidationOptions {
validator?: ValidatorOptions;
transformer?: ClassTransformOptions;
}
You can use it to pass options for class-validator
(more info) and for class-transformer
(more info).
The class-transformer and class-validator are more powerful than it was showed in the simple usage sample, so go to their github page and check out they capabilities!
0.9.1
class-transformer
peer dependency version range to >=0.2.3
0.9.0
class-validator
peer dependency to version >=0.12.0
^3.9.5
0.8.0
class-transformer
dependency to version ^0.2.3
class-validator
dependency to version ^0.10.1
^3.6.3
0.7.1
class-transformer
dependency to version ^0.2.0
0.6.0
class-validator
dependency to version ^0.9.1
0.5.0
TransformValdiationOptions
interface (typo)class-validator
dependency to version ^0.8.1
and class-transformer
to ^0.1.9
0.4.1
TransformValdiationOptions
interface name typo (deprecate in favour of TransformValidationOptions
)0.4.0
transformAndValidateSync
function for synchronous validationPromise
of T
or T[]
class-validator
dependency to version ^0.7.2
and class-transformer
to ^0.1.7
0.3.0
class-validator
dependency to version ^0.7.1
0.2.0
object
(introduced in TS 2.2)0.1.1
Error
with message0.1.0
transformAndValidate
function