Guestlist
Guestlist is a tiny library that whitelists, validates, and sanitizes HTTP request properties. It's backed by validator.js and works great with Express, Fastify, Polkadot, and more.
const list rule validate = const safelist = app
Using Guestlist to validate your request properties means that anything not expected or not following the rules will not be allowed through. In other words:
If you're not on the list, you're not coming in!
Installation
This is a Node.js module available through the npm registry. Node 8 or higher is required.
Installation is done using the npm install command:
$ npm install -S guestlist
Features
- Validate and sanitize request parameters with the full power of validator.js
- A concise, fluent API to create lists of allowed properties and rules to follow
- Configurable functions enable compatibility with Express, Fastify, Polkadot, and more
API
Guestlist provides three functions; one to create a safelist of request properties to expect, a second to create rules for a property to follow, and a third to check the request and extract all of the valid properties.
list()
This function creates a new safelist of request properties to expect and maintains the rules associated with them:
const safelist =
Expected properties are added to the list with the .add()
method which accepts three arguments: the property name, a rule, and an optional options
object.
safelist
The currently supported options
are:
array
If true any single values will be transformed into an array. When false only the last member of any array-like values will be passed through. Defaults tofalse
.default
Returns a default value for a property which is undefined or invalid.
rule()
This function provides a fluent interface for validator.js. All validator and sanitizer methods are available and chainable. Validators will always be called before sanitizers and the methods will be called in the order they were declared.
Here are a few example rules for validating and sanitizing numbers, dates, and strings:
// Validate: Assert the value is a number between 1 and 30 and a factor of 3// Sanitize: Coerce the value to a Number // Validate: Assert the value is an ISO date string// Sanitize: Coerce the value to a Date // Validate: Assert the property is a string between 2 and 10 characters// Sanitize: Escape and trim the value
Occasionally validator.js may not provide the functionality you require. In these cases you may provide a custom validator or sanitizer function:
// Ignore property if a flag is disabledconst checkFlagIsEnabled = flags === 'on' // Format the date as a YYYY-MM-DD stringconst formatDate = date;
validate(request, safelist[, locations])
This function checks a request against a list of rules and extracts all of the valid properties. It accepts three arguments: the request object, a safelist, and an optional array of request properties to check. By default it will look for properties in the following locations:
request.body
(requires post body parsing middleware to be implemented, e.g. body-parser)request.params
request.query
request.cookies
(requires cookie parsing middleware to be implemented, e.g. cookie-parser)
const handler = { const validProperties = }
Differences to express-validator
The express-validator package also wraps validator.js to provide middleware for your express.js apps and Guestlist shares several similarities. The primary difference between the two modules is the way each handles invalid data:
- Guestlist will ignore invalid or unexpected request properties.
- express-validator provides tools for creating error messages and separate methods for retrieving only the valid properties.
If you need to validate the data and return feedback to the user you should use express-validator. If you only need to ignore invalid data then Guestlist may suit you better.
One feature of Guestlist which is not currently available in express-validator is that it supports applying validators and sanitizers to an array of values. This is very useful if you need to permit multiple values for a property, for example when accepting a form which includes a set of checkboxes or a search page which has multiple filters.
Development
Guestlist uses Prettier for code formatting, includes TypeScript declarations and is tested with Jasmine.
License
Guestlist is MIT licensed.