Sanitization Chain API

The sanitization chain is a middleware, and it should be passed to an Express route handler.

You can add as many sanitizers to a chain as you need. When the middleware runs, it will modify each field in place, applying each of the sanitizers in the order they were specified:

const { body } = require('express-validator');
app.get('/', body('trimMe').trim(), (req, res, next) => {
  // If req.body.trimMe was originally "  something ",
  // its sanitized value will be "something"
  console.log(req.body.trimMe);
});

Standard sanitizers

All sanitizers listed by validator.js are made available within a Sanitization Chain, and are called "standard sanitizers" in express-validator.

This means you can use any of those methods, e.g. normalizeEmail, trim, toInt, etc.

info

For a complete list of standard sanitizers and their options, please check validator.js' docs.

note

Since validator.js only accepts string as input, any value (including arrays and objects) that needs to be sanitized by a Standard Sanitizer is first converted to such type.

Additional methods

In addition to the standard sanitizers, the following methods are also available within a Sanitization Chain:

.customSanitizer(sanitizer)

• sanitizer(value, { req, location, path }): the custom sanitizer function. Receives the value of the field being sanitized, as well as the express request, the location and the field path.

Returns: the current sanitization chain instance

Adds a custom sanitizer to the current sanitization chain. It must synchronously return the new value.

Example:

const { param } = require('express-validator');
app.get(
  '/object/:id',
  param('id').customSanitizer((value, { req }) => {
    return req.query.type === 'user' ? ObjectId(value) : Number(value);
  }),
  objectHandler,
);

.default(default_value)

Returns: the current sanitization chain instance

Replaces the current value with a default one if the current value is included in ['', null, undefined, NaN].

app.post('/', body('username').default('foo'), (req, res, next) => {
  // 'bar'     => 'bar'
  // ''        => 'foo'
  // undefined => 'foo'
  // null      => 'foo'
  // NaN       => 'foo'
});

.replace(values_to_replace, new_value)

Returns: the current sanitization chain instance

Replaces the current value with a new one if the current value is included in a given Array.

app.post('/', body('username').replace(['bar', 'BAR'], 'foo'), (req, res, next) => {
  // 'bar_' => 'bar_'
  // 'bar'  => 'foo'
  // 'BAR'  => 'foo'
  console.log(req.body.username);
});

.run(req)

Returns: a promise that resolves when the sanitization chain ran.

Runs the current sanitization chain in an imperative way.

const { check } = require('express-validator');
app.post('/create-post', async (req, res, next) => {
  // BEFORE:
  // req.body.content = ' hey your forum is amazing! <script>runEvilFunction();</script>    ';
  await check('content').escape().trim().run(req);

  // AFTER:
  // req.body.content = 'hey your forum is amazing! &lt;script&gt;runEvilFunction();&lt;/script&gt;';
});

.toArray()

Returns: the current sanitization chain instance

Converts the value to an array. undefined will result in an empty array.

app.post('/', [body('checkboxes').toArray()], (req, res, next) => {
  // ['foo', 'bar']  => ['foo', 'bar']
  // 'foo'          => ['foo']
  // undefined      => []
  console.log(req.body.checkboxes);
});

.toLowerCase()

Returns: the current sanitization chain instance

Converts the value to lower case. Non string value will return itself.

app.post('/', [body('username').toLowerCase()], (req, res, next) => {
  // 'Foo'      => 'foo'
  // undefined  => undefined
  // null       => null
  console.log(req.body.username);
});

.toUpperCase()

Returns: the current sanitization chain instance

Converts the value to upper case. Non string value will return itself.

app.post('/', [body('username').toUpperCase()], (req, res, next) => {
  // 'Foo'      => 'FOO'
  // undefined  => undefined
  // null       => null
  console.log(req.body.username);
});