Security News
JSR Working Group Kicks Off with Ambitious Roadmap and Plans for Open Governance
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Assurance is a validation library, which:
Node
npm install assurance
Or in the browser
component install danmilon/assurance
Also available as standalone scripts assurance.js
or assurance.min.js (global var assurance
)
When things go right.
var assurance = require('assurance')
var o = {
name: 'john',
age: 16,
adult: false,
likes: ['sports', 'music', 'coding'],
schedule: {
monday: ['school'],
tuesday: ['sleep'],
wednesday: {
start: '10:30',
end: '11:15'
}
}
}
var assure = assurance(o)
assure.me('name').is('string').len(100)
assure.me('age').is('number').isInt().gt(0)
assure.me('adult').is('boolean')
// can nest in arrays
assure.me('likes', function (hobby) {
// I'm passed each single element
hobby.is('string')
})
// can do validations and then ntest
assure.me('schedule').is('object').nest(function () {
// now i'm validating john's schedule
assure.me('monday').is('array')
assure.me('tuesday').is('array')
// nest in objects too
assure.me('wednesday', function () {
// now we're validating internal fields
assure.me('start').is('string').matches(/\d\d:\d\d/)
})
})
console.log(assure.end())
// []
or wrong
var assurance = require('assurance')
var malicious = {
name: 'Eve',
hobbies: ['WHERE', 1, '=', 1],
integer: 3.14,
positive: -666
}
var assure = assurance(malicious)
assure.me('name').is('string')
assure.me('hobbies', function (hobby) {
hobby.is('string')
})
assure.me('integer').is('number').isInt()
assure.me('positive').is('number').isInt().gt(0)
console.log(assure.end())
// [ { type: 'InvalidType',
// expected: 'string',
// is: 'number',
// message: 'value is of type number but string was expected',
// param: 'hobbies[1]' },
// { type: 'InvalidType',
// expected: 'string',
// is: 'number',
// message: 'value is of type number but string was expected',
// param: 'hobbies[3]' },
// { type: 'InvalidValue',
// message: 'value must be an integer',
// is: 3.14,
// param: 'integer' },
// { type: 'InvalidValue',
// message: 'expected a value greater than 0',
// is: -666,
// param: 'positive' } ]
var assure = assurance(object, onlyFields, alias)
object
: The object to validateonlyFields
: Optional array of strings. Only fields in this array will validated (top-level only)alias
: Optional object mapping object fields to other names, in case a field has errors (top-level only)Remember that internally, a single assurance instance is used. Whenever you
call .assurance(...)
, the internal instance is merely brought to a state as it
would be if it was a new object. Due to the single-threaded execution of node,
and the fact that most times you want to validate only one object at a time, by
following this approach, we don't have to create a new Assurance object
every time we need to perform validations and then throw it away through garbage
collection.
var o = {
integer: 'not an integer',
string: 1337
}
var assure = assurance(o, ['string'])
assure.me('integer').is('number').isInt()
assure.me('string').is('string')
console.log(assure.end())
// [ { type: 'InvalidType',
// expected: 'string',
// is: 'number',
// message: 'value is of type number but string was expected',
// param: 'string' } ]
var o = {
kittenParam: 'meew'
}
var assure = assurance(o, { kittenParam: 'kitten' })
assure.me('kittenParam').is('number')
console.log(assure.end())
// [ { type: 'InvalidType',
// expected: 'number',
// is: 'string',
// message: 'value is of type string but number was expected',
// param: 'kitten' } ]
Declares that the following validation calls are about field
. .check
is an alias, because .me
as a name does not make sense when it is not assure.me()
. if fn
is passed, it instantly calls .nest(fn)
.
Returns a boolean indicating whether there are any validation errors yet.
assurance({ age: 5 }).check('age').is('number').hasErrors()
// false
Returns the errors accumulated so far.
.errors()
is an alias.
assurance({ age: 'a' }).check('age').is('number').end()
// [ { type: 'InvalidType' ... } ]
assurance({ age: 5 }).check('age').is('number').end()
// []
Throws the first error caught.
assurance({ age: 'a' }).check('age').is('number').throw()
// Error: value is of type string but number was expected
Indicates that the current field being validated is optional
assurance({}).check('age').optional().is('number').end()
// []
If the currently validated field is missing, a default value is assigned
var o = {}
assurance(o).check('age').default(18).is('number').min(18).end()
// []
console.log(o)
// { age: 18 }
Nests inside an object or array, to validate their inner elements.
assurance({ bands: ['cranberries', 'the doors', 666] }).check('bands').nest(function (band) {
band.is('string')
}).end()
// [ { type: 'InvalidType',
// expected: 'string',
// is: 'number',
// message: 'value is of type number but string was expected',
// param: 'bands[2]' } ]
Allows fn to perform custom checks on the current value being validated. For convention, except the value, fn is passed the built-in errors which you can use and return. But this is not a restriction, fn can return any object which captures the error in whatever way you want.
assurance({ name: 'dan' }).check('name').is('string').custom(function (name, errors) {
if (name[0] === name[0].toLowerCase()) {
return new errors.InvalidValue('expected name to be titled (ie George)', name)
}
}).end()
// [ { type: 'InvalidValue',
// message: 'expected name to be titled (ie George)',
// is: 'dan',
// param: 'name' } ]
Adds a new validator or sanitizer.
type
: validator
or sanitizer
name
: name of the new method (ie assure.me('field')._name_(...)
)fn
: validator or sanitizer functionIf name
is omitted, then the name of the function will be used.
fn
is first passed the value of the field currently being validated, and then
the rest of the arguments passed when the method was invoked.
fn
is a validator, in case of error, it must return an object.fn
is a sanitizer, should return the new value, if needed.assurance.extend('sanitizer', function toUpperCase(val) {
return val.toUpperCase()
})
.is(type) typeof val === type (extra type 'array')
.gt(number) val > number
.lt(number) val < number
.max(number) val <= number
.min(number) val >= number
.equals(other) val === other
.notEquals(other) val !== other
.required() val !== undefined && val !== null
.oneOf(index) val exists in index
.isEmail() val has an email format
.isInt() val is an integral number
.matches(regex) val matches regex
.len(min, max) val.length between min and max
.len(max) val.length at most max
.consistsOf(index) val contains only stuff found in index
.toInt() number & string to integers
.toFloar() string to float
.trim() trims whitespace from left & right
A few methods accept an index (oneOf
, consistsOf
, etc). This can be either
an array, or an object and what you use has performance impacts. For example, if
you'd like to check whether a string is one of many many strings, then an array
is a bad option O(n). Instead you can use an object (hash) as an index, which has O(1)
lookup. Obviously this makes sense for lookups amongst more than a couple thousand elements.
var array = ['option1', 'option2']
var object = {
option1: 1,
option2: 1
}
var assure = assurance({ str: 'option3' })
assure.me('str').oneOf(array) // O(n)
assure.me('str').oneOf(object) // O(1)
npm test
make test
FAQs
Node validation/sanitization library with a handsome API
We found that assurance demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.