Function argument validation for humans

Highlights

• Expressive chainable API
• Lots of built-in validations
• Supports custom validations
• 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 argument to be of type `string` but received type `number`

unicorn('yo');
//=> ArgumentError: Expected string to have a minimum length of `5`, got `yo`

API

Complete API documentation

ow(value, predicate)

Test if value matches the provided predicate. Throws an ArgumentError if the test fails.

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

checkPassword('foo');
//=> ArgumentError: Expected string 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.{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

• undefined
• null
• string
• number
• boolean
• symbol

Built-in types

• array
• function
• buffer
• object
• regExp
• date
• error
• promise
• map
• set
• weakMap
• weakSet

Typed arrays

• int8Array
• uint8Array
• uint8ClampedArray
• int16Array
• uint16Array
• int32Array
• uint32Array
• float32Array
• float64Array

Structured data

• arrayBuffer
• dataView

Miscellaneous

• nan
• nullOrUndefined
• iterable
• typedArray

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: [NOT] Expected string to 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 || `Expected \`${x}\` to be greater than \`${max}\``;
};

ow(5, ow.number.is(x => greaterThan(10, x)));
//=> ArgumentError: Expected `5` to be greater than `10`

label(string)

This assigns a custom label to be used in any error messages. It is useful for making error messages more user-friendly by including the name of the variable which failed validation.

This predicate does not add any additional validation.

ow('', ow.string.nonEmpty);
//=> ArgumentError: Expected string to not be empty

ow('', ow.string.label('foo').nonEmpty);
//=> ArgumentError: Expected string `foo` to not be empty

Maintainers

• Sindre Sorhus
• Sam Verschueren

Related

• @sindresorhus/is - Type check values

License

MIT