Form validation and data filtering for Express
JavaScript
Switch branches/tags
Nothing to show
Pull request Compare This branch is 3 commits ahead, 19 commits behind dandean:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
LICENSE
README.md
TODO.md
index.js
package.json

README.md

Express Form provides data filtering and validation as route middleware to your Express applications.

Usage:

var form = require("express-form"),
    filter = form.filter,
    validate = form.validate;

var app = express.createServer();

app.configure(function() {
  app.use(express.bodyDecoder());
  app.use(app.router);
});

app.post(

  // Route
  '/user',
  
  // Form filter and validation middleware
  form(
    filter("username").trim(),
    validate("username").required().is(/^[a-z]+$/),
    filter("password").trim(),
    validate("password").required().is(/^[0-9]+$/),
    filter("email").trim(),
    validate("email").isEmail()
  ),
  
  // Express request-handler now receives filtered and validated data
  function(req, res){
    if (!req.form.isValid) {
      // Handle errors
      console.log(req.form.errors);

    } else {
      // Or, use filtered form data from the form object:
      console.log("Username:", req.form.username);
      console.log("Password:", req.form.password);
      console.log("Email:", req.form.email);
    }
  }
);

Documentation:

Module

The Express Form module returns an Express Route Middleware function. You specify filtering and validation by passing filters and validators as arguments to the main module function. For example:

var form = require("express-form");

app.post('/user',
  
  // Express Form Route Middleware: trims whitespace off of
  // the `username` field.
  form(form.filter("username").trim()),
  
  // standard Express handler
  function(req, res) {
    // ...
  }
);

Filters

The filter property of the module creates a filter object tied to a specific field.

filter(fieldname);
// -> Filter

The API is chainable, so you can keep calling filter methods one after the other:

filter("username").trim().toLower().truncate(5)

Filter API:

Type Coercion

toFloat()           -> Number

toInt()             -> Number, rounded down

toBoolean()         -> Boolean from truthy and falsy values

toBooleanStrict()   -> Only true, "true", 1 and "1" are `true`

ifNull(replacement) -> "", undefined and null get replaced by `replacement`

HTML Encoding for & " < >

entityEncode() -> encodes HTML entities

entityDecode() -> decodes HTML entities 

String Transformations

trim(chars)                 -> `chars` defaults to whitespace

ltrim(chars)

rtrim(chars)

toLower() / toLowerCase()

toUpper() / toUpperCase()

truncate(length)            -> Chops value at (length - 3), appends `...`

Custom Filters

custom(function)

    Filters the field value using custom logic.

    Example:
    If the `name` field has a value of "hello there", this would
    transform it to "hello-there". 

    filter("name").custom(function(value) {
      return value.replace(/\s+/g, "-");
    });

Validators

The validate property of the module creates a validator object tied to a specific field.

validate(fieldname[, label]);
// -> Validator

The API is chainable, so you can keep calling validator methods one after the other:

validate("username").required().isAlphanumeric()

Validator API:

Validation messages: each validator has its own default validation message. These can easily be overridden at runtime by passing a custom validation message to the validator. The custom message is always the last argument passed to the validator.

Use "%s" in the message to have the field name or label printed in the message:

validate("username").required()
// -> "username is required"

validate("username").required("What is your %s?")
// -> "What is your username?"

validate("username", "Username").required("What is your %s?")
// -> "What is your Username?"

Validation Methods

By Regular Expressions

regex(pattern[, modifiers[, message]])
- pattern (RegExp|String): RegExp (with flags) or String pattern.
- modifiers (String): Optional, and only if `pattern` is a String.
- message (String): Optional validation message.

    alias: is

    Checks that the value matches the given regular expression.

    Example:

    validate("username").is("[a-z]", "i", "Only letters are valid in %s")
    validate("username").is(/[a-z]/i, "Only letters are valid in %s")


notRegex(pattern[, modifiers[, message]])
- pattern (RegExp|String): RegExp (with flags) or String pattern.
- modifiers (String): Optional, and only if `pattern` is a String.
- message (String): Optional validation message.

    alias: not

    Checks that the value does NOT match the given regular expression.

    Example:

    validate("username").not("[a-z]", "i", "Letters are not valid in %s")
    validate("username").not(/[a-z]/i, "Letters are not valid in %s")

By Type

isNumeric([message])

isInt([message])

isDecimal([message])

isFloat([message])

By Format

isEmail([message])

isUrl([message])

isIP([message])

isAlpha([message])

isAlphanumeric([message])

isLowercase([message])

isUppercase([message])

By Content

notEmpty([message])

    Checks if the value is not just whitespace.
    

equals( value [, message] )
- value (String): A value that should match the field value OR a fieldname
                  token to match another field, ie, `field::password`.
    
    Compares the field to `value`.

    Example:
    validate("username").equals("admin")

    validate("password").is(/^\w{6,20}$/)
    validate("password_confirmation").equals("field::password")


contains(value[, message])
- value (String): The value to test for.
    
    Checks if the field contains `value`.
    

notContains(string[, message])
- value (String): A value that should not exist in the field.

    Checks if the field does NOT contain `value`.

Other

required([message])

    Checks that the field is present in form data, and has a value.
    
    
custom(function[, message])
- function (Function): A custom validation function.

    Validates the field using a custom validation function. If the function
    throws, and `message` is not provided, the thrown error message is used.
    
    Example:
    
    validate("username").custom(function(value) {
        if (value !== "admin") {
            throw new Error("%s must be 'admin'.");
        }
    });

http.ServerRequest.prototype.form

Express Form adds a form object with various properties to the request.

isValid -> Boolean

errors  -> Array

flashErrors(name) -> undefined

    Flashes all errors. Configurable, enabled by default.

getErrors(name) -> Array
- fieldname (String): The name of the field

    Gets all errors for the field with the given name.

Example request handler:

function(req, res) {
  if (req.isValid == false) {
    console.log(req.errors);
    console.log(req.getErrors("username"))
  }
}

Installation:

npm install express-form

Credits

Currently, Express Form uses many of the validation and filtering functions provided by Chris O'Hara's node-validator.