express-form

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.validator;

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]+$/)
  ),
  
  // 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);
    }
  }
);

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])

notNull([message])

isNull([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

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.