Function argument validation for humans
- Expressive chainable API
- Lots of built-in validations
- Supports custom validations
- Automatic label inference in Node.js
- Written in TypeScript
npm install ow
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 import ow from 'ow/dev-only'
instead of the usual import ow from '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.
Ow includes TypeScript type guards, so using it will narrow the type of previously-unknown values.
function (input: unknown) {
input.slice(0, 3) // Error, Property 'slice' does not exist on type 'unknown'
ow(input, ow.string)
input.slice(0, 3) // OK
}
Test if value
matches the provided predicate
. Throws an ArgumentError
if the test fails.
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.
Returns true
if the value matches the predicate, otherwise returns false
.
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`
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`
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));
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);
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.
int8Array
uint8Array
uint8ClampedArray
int16Array
uint16Array
int32Array
uint32Array
float32Array
float64Array
The following predicates are available on every type.
Inverts the following predicate.
ow(1, ow.number.not.infinite);
ow('', ow.string.not.empty);
//=> ArgumentError: Expected string to not be empty, got ``
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 || `Expected \`${x}\` to be greater than \`${max}\``;
};
ow(5, ow.number.is(x => greaterThan(10, x)));
//=> ArgumentError: Expected `5` to be greater than `10`
Use a custom validation object. The difference with is
is that the function should return a validation object, which allows more flexibility.
ow(1, ow.number.validate(value => ({
validator: value > 10,
message: `Expected value to be greater than 10, got ${value}`
})));
//=> ArgumentError: (number) Expected value to be greater than 10, got 1
You can also pass in a function as message
value which accepts the label as argument.
ow(1, 'input', ow.number.validate(value => ({
validator: value > 10,
message: label => `Expected ${label} to be greater than 10, got ${value}`
})));
//=> ArgumentError: Expected number `input` to be greater than 10, got 1
Provide a custom message:
ow('๐', 'unicorn', ow.string.equals('๐ฆ').message('Expected unicorn, got rainbow'));
//=> ArgumentError: Expected unicorn, got rainbow
You can also pass in a function which receives the value as the first parameter and the label as the second parameter and is expected to return the message.
ow('๐', ow.string.minLength(5).message((value, label) => `Expected ${label}, to have a minimum length of 5, got \`${value}\``));
//=> ArgumentError: Expected string, to be have a minimum length of 5, got `๐`
It's also possible to add a separate message per validation:
ow(
'1234',
ow.string
.minLength(5).message((value, label) => `Expected ${label}, to be have a minimum length of 5, got \`${value}\``)
.url.message('This is no url')
);
//=> ArgumentError: Expected string, to be have a minimum length of 5, got `1234`
ow(
'12345',
ow.string
.minLength(5).message((value, label) => `Expected ${label}, to be have a minimum length of 5, got \`${value}\``)
.url.message('This is no url')
);
//=> ArgumentError: This is no url
This can be useful for creating your own reusable validators which can be extracted to a separate npm package.
Requires TypeScript 4.7 or later.
Ow includes a type utility that lets you to extract a TypeScript type from the given predicate.
import ow, {Infer} from 'ow';
const userPredicate = ow.object.exactShape({
name: ow.string
});
type User = Infer<typeof userPredicate>;
Former:
- @sindresorhus/is - Type check values
- ngx-ow - Angular form validation on steroids