npm:sound | Skypack

README

sound.js - make sure your data is sound!

About

Take an incoming form from the web (a single-level object of strings), convert and validate them, and use the output values.

e.g. Take a web form of title and Markdown:

const schema = {
  title : sound('title').isString().toTrim().isRequired().isMaxLen(256),
  markdown : sound('body').hasDefault('').isString(),
}

Here you can see that the title is required (after trimming) and can't be more than 256 chars long. The body can be left out but will be set to the empty string as a default.

An input of:

{
  title : ' Hello, World! ',
}

Would give an output of:

{
  ok : true,
  arg : {
    title : ' Hello, World! ',
  },
  val : {
    title : 'Hello, World!',
    body : '',
  },
  err : {},
}

If ok is false, then err will contain errors related to each field.

Synopsis

Examples

var schema = {
    username : sound().isString().toLowerCase().toTrim().isRequired().isMatch(/^[a-z0-9]{4,16}$/),
    password : sound().isString().isRequired().isMinLen(8).isMaxLen(100),
    email    : sound().isString().isRequired().isEmailAddress(),
    logins   : sound().isInteger().isRequired().isMinVal(0),
    awesome  : sound().isString().hasDefault('yes').toBoolean().isBoolean(),
    url      : sound().isString().isUrl(), // optional
    isAdmin  : sound().isString().isRequired().toBoolean().isBoolean(),
    dob      : sound().isDate(), // accepts 'yyyy-mm-dd'
    agree    : sound().isString().toBoolean().isEqual(true), // make sure they tick T&C's
    color    : sound().isString().toLowerCase().toTrim().isRequired().isEnum([ 'red', 'green', 'blue' ]),
};

var params = {
    username : 'chilts',
    password : 'abcdefgh',
    email : 'me@example.com',
    agree : 'on', // will convert to true
};

var out = sound.validate(params, schema);
if ( out.ok ) {
    // everything validated ... params contained in `out.val`
}
else {
    // something failed validation ... errors contained in `out.err`
}

If anything fails validation, then err will be an object with keys set to each field for each error. Only one error per field in the schema will be reported.

If no failures are detected, err is just {}. You need to check out.ok to see if validation passed or failed.

var out = sound.validate(params1, schema)
if ( !out.ok ) {
    // something failed, check the keys in `out.err.*`
    ...
    return;
}

// all ok

An error may look like:

{
    password: 'Password should be at least 8 characters'
    logins: 'Logins should be of type integer',
    pi: 'PI should be of type float',
    date: 'Date should be of type date'
}

Unknown Params

Only params that we know about are passed back as out.val.

Other Validation Libraries

There are other validation libraries out there, but they all give me errors which are arrays. To me, this is useless. I don't want to list all of the errors at the top of a form, nor do I know which order those errors are in if I want to pick and choose. I want the err to be an object with the only keys set to be to ones that fail.

Currently 'sound' only reports the first error it encounters with each field and it is likely to stay this way (due to problem and overlap required to keep trying every test even if the first one has failed).

Author

Written by Andrew Chilton - Blog - Twitter.

License

MIT - http://chilts.mit-license.org/2013/

(Ends)

Usage no npm install needed!