ow 3.x

Complete instructions

Verified against ow@3.1.1 on 2026-09-08. 4 of 4 examples executed.

ow

Use this skill for ow version ^3.0.0 (the v3 API is documented against 3.1.1). The package is ESM-only and requires Node.js 20 or newer.

Import and core operations

import ow from 'ow';

The main callable validates a value and throws ArgumentError when validation fails:

ow(value, predicate);
ow(value, label, predicate);

Use the other entry points according to the desired failure behavior:

• ow.isValid(value, predicate) returns a boolean.
• ow.validate(value, predicate) returns {success: true, value} or {success: false, error}.
• ow.validate(value, label, predicate) is the labeled form.
• ow.create(predicate) and ow.create(label, predicate) create reusable validation functions.
• ow.any(...predicates) accepts a value matching any supplied predicate.
• ow.isPredicate(value) identifies an ow predicate.

import ow, {ArgumentError} from 'ow';
import assert from 'node:assert/strict';

assert.doesNotThrow(() => ow('hello', ow.string.minLength(5)));
assert.throws(
	() => ow('no', 'username', ow.string.minLength(5)),
	error => error instanceof ArgumentError,
);

assert.equal(ow.isValid(123, ow.number), true);
assert.equal(ow.isValid('123', ow.number), false);

const valid = ow.validate('hello', ow.string);
assert.equal(valid.success, true);
if (valid.success) {
	assert.equal(valid.value.length, 5);
}

const invalid = ow.validate(123, 'name', ow.string);
assert.equal(invalid.success, false);
if (!invalid.success) {
	assert.ok(invalid.error instanceof ArgumentError);
}

const longString = ow.create('value', ow.string.minLength(3));
assert.doesNotThrow(() => longString('abc'));
assert.throws(() => longString('a'), ArgumentError);

assert.equal(ow.isPredicate(ow.string), true);
assert.equal(ow.isPredicate('string'), false);
assert.equal(ow.isValid('abc', ow.any(ow.number, ow.string)), true);
assert.equal(ow.isValid(true, ow.any(ow.number, ow.string)), false);

Built-in predicates and modifiers

The documented built-in predicates include string, number, boolean, array, function, object, date, promise, map, set, typed-array predicates, arrayBuffer, dataView, nan, nullOrUndefined, iterable, and typedArray.

Use modifiers such as ow.optional.{type}, ow.nullable.{type}, and ow.absent.{type} where the corresponding presence/nullability behavior is required. Predicate modifiers are chainable, for example .minLength(), .maxLength(), .not, .empty, and .is().

import ow from 'ow';
import assert from 'node:assert/strict';

assert.equal(ow.isValid('abc', ow.string.minLength(3).maxLength(5)), true);
assert.equal(ow.isValid('', ow.string.not.empty), false);
assert.equal(ow.isValid(7, ow.number.is(value => value < 10)), true);
assert.equal(ow.isValid(10, ow.number.is(value => value < 10)), false);

assert.equal(ow.isValid('red', ow.any(ow.string, ow.number)), true);
assert.equal(ow.isValid(4, ow.any(ow.string, ow.number)), true);
assert.equal(ow.isValid(false, ow.any(ow.string, ow.number)), false);

assert.equal(ow.isValid(1, ow.optional.number), true);
assert.equal(ow.isValid(undefined, ow.optional.number), true);
assert.equal(ow.isValid(null, ow.nullable.number), true);
assert.equal(ow.isValid(undefined, ow.nullable.number), false);

assert.equal(ow.isValid(new Uint8Array([1, 2]), ow.uint8Array), true);
assert.equal(ow.isValid(new ArrayBuffer(2), ow.arrayBuffer), true);

ow.absent is documented as a modifier for presence-sensitive validation, but the research does not establish a standalone value-level example for its semantics. Do not infer its behavior from ow.optional or ow.nullable.

Custom predicates

Use .is() for a predicate based on a boolean callback. Use .validate() when the callback should return a custom validator result and message.

import ow from 'ow';
import assert from 'node:assert/strict';

const underTen = ow.number.is(value => value < 10);
assert.equal(ow.isValid(9, underTen), true);
assert.equal(ow.isValid(10, underTen), false);

const greaterThanTen = ow.number.validate(value => ({
	validator: value > 10,
	message: `Expected value to be greater than 10, got ${value}`,
}));

assert.equal(ow.isValid(11, greaterThanTen), true);
const result = ow.validate(10, greaterThanTen);
assert.equal(result.success, false);
if (!result.success) {
	assert.match(result.error.message, /greater than 10/);
}

Shapes and TypeScript inference

Object shape validation is available through ow.object.exactShape(). Infer derives a TypeScript type from a predicate, while ValidateResult and the other named exports are type exports.

import ow, {type Infer} from 'ow';
import assert from 'node:assert/strict';

const userPredicate = ow.object.exactShape({
	name: ow.string,
});

type User = Infer<typeof userPredicate>;
const user: User = {name: 'Ada'};

assert.equal(ow.isValid(user, userPredicate), true);
assert.equal(ow.isValid({name: 123}, userPredicate), false);

String literal predicates can narrow with string.equals() and string.oneOf() in TypeScript. For example, a value validated by ow.string.oneOf(['red', 'blue']) can be returned as the literal union 'red' | 'blue' after validation.

v3 migration traps

• Do not use ow.buffer. It was removed in v3; use ow.uint8Array instead.
• Predicates are immutable in v3. Do not rely on a modifier changing an existing predicate; use the returned predicate when chaining.
• The package requires Node.js 20 or newer.
• The familiar v2 call shapes still apply: ow(value, predicate), ow(value, label, predicate), ow.isValid(), ow.create(), and ow.any().
• Prefer ow.validate() when failure is expected and should be handled as data rather than caught as an exception.

Development-only entry point

The package also exports ow/dev-only. The documentation describes it for a bundler/build step that replaces the implementation in production, such as a Parcel production build with NODE_ENV="production". It is not documented as a plain-script optimization, so use the normal ow import in standalone scripts.

Not covered

This skill does not cover the complete predicate catalog or every predicate modifier, the exact runtime shape of all built-in error messages, bundler configuration beyond the documented ow/dev-only boundary, or framework/test-runner integration. The research also does not document the full object-shape syntax beyond exactShape, the precise standalone semantics of absent, or the details of every exported type.