Function argument validation for humans
Highlights
- Expressive chainable API
- Lots of built-in validations
- Supports custom validations
- Automatic label inference in Node.js
- Written in TypeScript
Install
$ npm install ow
Usage
import ow from 'ow';
const unicorn = input => {
ow(input, ow.string.minLength(5));
// …
};
unicorn(3);
//=> ArgumentError: Expected `input` to be of type `string` but received type `number`
unicorn('yo');
//=> ArgumentError: Expected string `input` to have a minimum length of `5`, got `yo`
We can also match the shape of an object.
import ow from 'ow';
const unicorn = {
rainbow: '?',
stars: {
value: '?'
}
};
ow(unicorn, ow.object.exactShape({
rainbow: ow.string,
stars: {
value: ow.number
}
}));
//=> ArgumentError: Expected property `stars.value` to be of type `number` but received type `string` in object `unicorn`
Note: If you intend on using ow for development purposes only, use require('ow/dev-only') instead of the usual import 'ow', and run the bundler with NODE_ENV set to production (e.g. $ NODE_ENV="production" parcel build index.js). This will make ow automatically export a shim when running in production, which should result in a significantly lower bundle size.
API
ow(value, predicate)
Test if value matches the provided predicate. Throws an ArgumentError if the test fails.
ow(value, label, predicate)
Test if value matches the provided predicate. Throws an ArgumentError with the specified label if the test fails.
The label is automatically inferred in Node.js but you can override it by passing in a value for label. The automatic label inference doesn't work in the browser.
ow.isValid(value, predicate)
Returns true if the value matches the predicate, otherwise returns false.
ow.create(predicate)
Create a reusable validator.
const checkPassword = ow.create(ow.string.minLength(6));
const password = 'foo';
checkPassword(password);
//=> ArgumentError: Expected string `password` to have a minimum length of `6`, got `foo`
ow.create(label, predicate)
Create a reusable validator with a specific label.
const checkPassword = ow.create('password', ow.string.minLength(6));
checkPassword('foo');
//=> ArgumentError: Expected string `password` to have a minimum length of `6`, got `foo`
ow.any(...predicate[])
Returns a predicate that verifies if the value matches at least one of the given predicates.
ow('foo', ow.any(ow.string.maxLength(3), ow.number));
ow.optional.{type}
Makes the predicate optional. An optional predicate means that it doesn't fail if the value is undefined.
ow(1, ow.optional.number);
ow(undefined, ow.optional.number);
ow.{type}
All the below types return a predicate. Every predicate has some extra operators that you can use to test the value even more fine-grained.
Primitives
Built-in types
Typed arrays
int8Arrayuint8Arrayuint8ClampedArrayint16Arrayuint16Arrayint32Arrayuint32Arrayfloat32Arrayfloat64Array
Structured data
Miscellaneous
Predicates
The following predicates are available on every type.
not
Inverts the following predicate.
ow(1, ow.number.not.infinite);
ow('', ow.string.not.empty);
//=> ArgumentError: Expected string to not be empty, got ``
is(fn)
Use a custom validation function. Return true if the value matches the validation, return false if it doesn't.
ow(1, ow.number.is(x => x < 10));
ow(1, ow.number.is(x => x > 10));
//=> ArgumentError: Expected `1` to pass custom validation function
Instead of returning false, you can also return a custom error message which results in a failure.
const greaterThan = (max: number, x: number) => {
return x > max