sindresorhus/ow


Function argument validation for humans

https://sindresorhus.com/ow

License: MIT

Language: TypeScript

Keywords: javascript, nodejs, npm-package, type-checking, validation




Build Status Coverage Status gzip size install size

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

Complete API documentation

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

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

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

validate(fn)

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

This can be useful for creating your own reusable validators which can be extracted to a separate npm package.

Maintainers

Related

License

MIT

Project Statistics

Sourcerank 15
Repository Size 1.36 MB
Stars 2,832
Forks 64
Watchers 22
Open issues 28
Dependencies 25
Contributors 19
Tags 20
Created
Last updated
Last pushed

Top Contributors See all

Sindre Sorhus Sam Verschueren Itai Steinherz Travis Fischer Vadim Demedes Luke Childs Geraint White Alex Zherdev Bart Callant Aron Hafner Alex Driaguine Lukas Tetzlaff Apostrophii Alexander Buiko Alex Nozdriukhin Kevin Mårtensson Stephen Mathieson Steven

Packages Referencing this Repo

ow--fork-by-jblew-with-catching
Function argument validation for humans
Latest release 0.13.3 - Updated - 2.83K stars
@rastopyr/ow
Function argument validation for humans
Latest release 0.13.2 - Updated - 2.83K stars
ow
Function argument validation for humans
Latest release 0.14.0 - Updated - 2.83K stars

Recent Tags See all

v0.15.0 November 12, 2019
v0.14.0 October 20, 2019
v0.13.2 May 17, 2019
v0.13.1 May 13, 2019
v0.13.0 May 12, 2019
v0.12.0 February 01, 2019
v0.11.1 January 29, 2019
v0.11.0 January 27, 2019
v0.10.0 January 15, 2019
v0.9.1 January 10, 2019
v0.9.0 January 09, 2019
v0.8.0 October 16, 2018
v0.7.0 September 28, 2018
v0.6.0 June 21, 2018
v0.5.0 June 10, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-11-12 07:05:01 UTC

Login to resync this repository