flowstudio/datalize

Parameter, query, form data validation and filtering for NodeJS.

Datalize

Parameter, query, form data validation and filtering for Koa and Express.

See also this post about it on the Toptal Engineering Blog.

Installation

npm install --save datalize

Usage

Koa

const Koa = require('koa');
const Router = require('koa-router');
const datalize = require('datalize');
const field = datalize.field;

const app = new Koa();

// add any body parser
app.use(require('koa-body')());

const router = new Router();

router.post('/', datalize([
	field('email', 'E-mail').required().email(),
	field('firstname', 'Firstname').required(),
	field('lastname', 'Lastname').required().trim(),
	field('isTerms').bool(true),
]), (ctx, next) => {
	ctx.body = {
		status: 'success',
		data: ctx.form,
	};
});

app
.use(router.routes())
.use(router.allowedMethods());

Express

const express = require('express');
const datalize = require('datalize');
const field = datalize.field;

const app = express();

// add any body parser
app.use(require('body-parser').json());

app.post('/', datalize([
	field('email', 'E-mail').required().email(),
	field('firstname', 'Firstname').required(),
	field('lastname', 'Lastname').required().trim(),
	field('isTerms').bool(true),
]), (req, res) => {
	res.send({
		status: 'success',
		data: req.form,
	});
});

Methods

datalize(fields, options)

Creates Data object and returns validation middleware, which uses body as source. Result is set to context/request.form object.

datalize.params(fields, options)

Same as datalize(), but uses params as source. Result is set to context/request.data object.

datalize.query(fields, options)

Same as datalize(), but uses query as source. Result is set to context/request.data object.

datalize.field(name, label)

Returns: Field

Creates Field object.

datalize.set(name, value)

Sets global option for datalize.

datalize.set('autoValidate', true);

Options

type

Type: String, Default: 'form'

breakOnRequired

Type: Boolean, Default: true

If required error is returned, no other errors will be collected.

autoValidate

Type: Boolean, Default: false

Auto validates form and throws Data.Error if there is any error.

autoConvertToArray

Type: Boolean, Default: false

Auto converts field.array() fields to array.

error

Type: Error, Default: DataError

Error object thrown on autoValidate.

Filters

All filters and chainable.

field('rooms').required().int().range(1, 20)

• condition: can throw error
• filter: updates value

field.required()

• condition

field.requiredIf(nameOrFn, requiredValue)

• condition
• nameOrFn: String|function
• requiredValue: any (optional) used only if nameOrFn is string

field.optional()

• filter
• The field is removed if value is undefined.

field.optionalIf(nameOrFn, requiredValue)

• filter
• nameOrFn: String|function
• requiredValue: any (optional) used only if nameOrFn is string
• The field is removed if value is undefined and conditions are passed.

field.patch()

• filter
• The same as optional but only if request's method is PATCH.

field.array()

• filter
• Returned value will be an Array.

field.container(children)

• filter
• children: Array
• Creates container will children fields, can be combined with field.array().

field.split(separator = ',')

• filter
• Converts value to array via splitting by separator.

field.custom(fn)

• condition, filter

field.bool(requiredValue)

• condition, filter
• requiredValue: Boolean (optional)
• Converts to boolean and if requiredValue is provided, the field's value must be equal to it.

field.toggle(requiredValue)

• condition, filter
• requiredValue: Number (optional)
• Converts to number (0, 1) and if requiredValue is provided, the field's value must be equal to it.

field.equal(compare)

• condition
• compare: any

field.default(defaultValue)

• filter
• defaultValue: any

field.nullable()

• filter
• Converts to null if is empty.

field.email()

• condition

field.number()

• condition, filter

field.uppercase()

• filter

field.lowercase()

• filter

field.trim()

• filter

field.truncate(length)

• filter
• length: Number

field.range(min, max)

• condition, filter
• min: Number|String|Function (can be a number or name of a field or function that returns number)
• max: Number|String|Function (can be a number or name of a field or function that returns number)

field.min(min)

• condition, filter
• min: Number|String|Function (can be a number or name of a field or function that returns number)

field.max(max)

• condition, filter
• max: Number|String|Function (can be a number or name of a field or function that returns number)

field.length(min, max)

• condition
• min: Number
• max: Number

field.minLength(min)

• condition
• min: Number

field.maxLength(max)

• condition
• max: Number

field.int()

• condition, filter

field.float()

• condition, filter

field.id()

• condition, filter

field.select(options)

• condition
• options: Array

File filters

field.file()

• filter
• Gets file from req.files object.

field.mime(types)

• condition
• types: Array

field.size(limit)

• condition
• limit: Number in Bytes

Custom filter

field.custom(function(value, result, ctx) {
	if (['optionA', 'optionB'].indexOf(value) === -1) {
		throw new Error('%s has invalid value.');
	}
});

field.custom(function(value, result, ctx) {
	return moment(value).format('YYYY/MM/DD');
});

field.custom(async (value, result, ctx) => {
	const typeValue = await result.getValue('type');

	if (type === 'business') {
		return null;
	}
});

Using custom filter globally

const datalize = require('datalize');
const field = datalize.field;

datalize.Field.prototype.isSlug = function(chars = 'a-z-') {
	const regexp = new RegExp(`^([${chars}]+)$`);

	// make sure to return this.add() or this object to allow chaining
	return this.add(function(value, result, ctx) {
		if (!regexp.test(String(value))) {
			throw new Error('%s contains invalid characters.');
		}
	});
};

// then the filter can be used anywhere
datalize([
	field('slug').required().isSlug()
]);

Error handling

router.post('/', datalize([
	field('email', 'E-mail').required().email(),
]), (ctx, next) => {
	if (!ctx.form.isValid) {
		ctx.status = 400;
		ctx.body = {
			status: 'error',
			errors: ctx.form.errors,
		};

		return;
	}

	ctx.body = {
		status: 'success',
		data: ctx.form,
	};
});

Global error handling

Koa

datalize.set('autoValidate', true);

// add to very beginning of koa middlewares
app.use(async (ctx, next) => {
	try {
		await next();
	} catch (err) {
		if (err instanceof datalize.Error) {
			ctx.status = 400;
			ctx.body = Object.assign({
				status: 'error'
			}, err.toJSON());
		}
	}
});

Express

datalize.set('autoValidate', true);

// add to very end of express middlewares
app.use(function(err, req, res, next) {
	if (err instanceof datalize.Error) {
		res.status(400).send(Object.assign({
			status: 'error'
		}, err.toJSON()));
	}
});

---

License

MIT

Copyright (c) 2018 Andrej Adamcik