Super lean and simple object validation with TypeScript support.
narrows is…
- composable: use any validator inside another
- extensible: validators are simple functions — easily write your own
- safe: in TypeScript, validators turn your variables into static types
- tiny: no dependencies, fewer than 50 lines of code and barely 500b gzipped
Easily validate complex types by using simple validators together:
import { number, record, string } from "narrows";
const validate = record({
a: string,
b: number
});
validate({ a: "abc", b: 123 }); // true
validate(42); // false
If you're using TypeScript, narrows is even more useful: it uses type guards to pull static type information from your validators.
import { number, record, string } from "narrows";
const validate = record({
a: string,
b: number
});
const foo: unknown = {
a: "abc",
b: 123
};
if (validate(foo)) {
foo; // type narrowed to { a: string; b: number; }
}
It's super easy to write your own validators! They're just functions that return true or false. Check it out:
import { all, number } from "narrows";
const positive = x => x > 0; // this is a validator!
const validate = all(number, positive);
validate(5); // true
validate(-1); // false
It's also common to write validator creators: functions that return validators. This lets you apply custom behavior when you use them.
import { all, number } from "narrows";
const greaterThan = x => y => y > x;
const validate = all(number, greaterThan(10));
validate(11); // true
validate(5); // false
In TypeScript, your validators should be user-defined type guards: functions in the form of (x: unknown) => x is T
. This lets TypeScript extract static type information.
import { record, number } from "narrows";
type Actions = "increment" | "decrement";
const action = (x: unknown): x is Actions =>
x === "increment" || x === "decrement";
const validate = record({
type: action,
amount: number
});
const foo: unknown = {
type: "increment",
b: 1
};
if (validate(foo)) {
foo; // type narrowed to { type: "increment" | "decrement"; amount: number; }
}
Validate that a variable is a boolean
, number
, string
, null
/undefined
or a literal value.
Returns true if and only if the argument is a boolean.
import { boolean } from "narrows";
boolean(false); // true
boolean(0); // false
Returns true if and only if the argument is a number.
import { number } from "narrows";
number(0); // true
number("string"); // false
Returns true if and only if the argument is a string.
import { string } from "narrows";
string("test"); // true
string(true); // false
Returns true if and only if the argument is undefined.
import { empty } from "narrows";
empty(undefined); // true
empty("string"); // false
Returns true if and only if the argument is null.
import { nil } from "narrows";
nil(null); // true
nil("string"); // false
Returns true if and only if the argument is strictly equal to the given value. Two values are strictly equal if they are primitives with the same value, or references to the same object.
import { literal } from "narrows";
const validate = literal(5);
validate(5); // true
validate(6); // false
In TypeScript, this will narrow to the widened type instead of the constant (e.g. number
instead of 5
). To fix this, you can assert the type manually:
import { literal } from "narrows";
let validate = literal(5 as 5); // TypeScript 3.3 and below
validate = literal(5 as const); // TypeScript 3.4 and above
const foo: unknown = 5;
if (validate(foo)) {
foo; // type narrowed to 5
}
Validate that a variable conforms to a certain shape, or is an instance of a constructor.
Returns true if and only if each property in an object matches the given validator.
import { object, number } from "narrows";
const validate = object(number);
validate({ a: 1, b: 2 /* ... */ }); // true
validate({ a: "a", b: "b" /* ... */ }); // false
const foo: unknown = {
a: 1,
b: 2
// ...
};
if (validate(foo)) {
foo; // type narrowed to { [key: string]: number }
}
Returns true if and only if each element in an array matches the given validator.
import { array, number } from "narrows";
const validate = array(number);
validate([1, 2 /* ... */]); // true
validate(["a", "b" /* ... */]); // false
const foo: unknown = [1, 2 /* ... */];
if (validate(foo)) {
foo; // type narrowed to number[]
}
Returns true if and only if a variable matches the given constructor.
import { instance } from "narrows";
const validate = instance(Date);
validate(new Date()); // true
validate({ a: 1 }); // false
const foo: unknown = new Date();
if (validate(foo)) {
foo; // type narrowed to Date
}
Validate that all members of a type match corresponding validators in the given schema.
Given an object of validators, returns true if and only if each validator in that object matches the corresponding property in the object being tested.
If extra properties are present, this function still returns true — but the extra properties won't be reflected in the narrowed type.
import { number, record, string } from "narrows";
const validate = record({
a: string,
b: number
});
const foo: unknown = {
a: "abc",
b: 123,
c: true
};
if (validate(foo)) {
foo; // type narrowed to { a: string; b: number; }
}
Given an array of validators, returns true if and only if each validator in that array matches the corresponding element in the array being tested.
If extra elements are present, this function still returns true — but the extra elements won't be reflected in the narrowed type.
import { number, string, tuple } from "narrows";
const validate = tuple([string, number]);
const foo: unknown = ["abc", 123, true];
if (validate(foo)) {
foo; // type narrowed to[string, number]
}
Take in two or more validators and return a single validator that applies all of their rules.
Returns true if the argument matches any of the given validators.
Narrows to a union of the validator types.
import { any, number, string } from "narrows";
const validate = any(number, string);
validate(0); // true
validate("one"); // true
validate(false); // false
const foo: unknown = 0;
if (validate(foo)) {
foo; // type narrowed to number | string
}
Returns true if the argument matches all of the given validators.
Narrows to an intersection of the validator types.
import { all, number, record, string } from "narrows";
const validate = all(record({ a: number }), record({ b: string }));
validate({ a: 1, b: "2" }); // true
validate({ a: 1 }); // false
validate({ b: "2" }); // false
const foo: unknown = {
a: 1,
b: "2"
};
if (validate(foo)) {
foo; // type narrowed to { a: number; b: string; }
}
Returns true if the argument matches the given validator or is undefined.
Narrows to a union of the validator type and undefined
.
import { optional, number } from "narrows";
const validate = optional(number);
validate(0); // true
validate(undefined); // true
validate("string"); // false
const foo: unknown = undefined;
if (validate(foo)) {
foo; // type narrowed to number | undefined
}
Returns true if the argument matches the given validator or is null.
Narrows to a union of the validator type and null
.
import { nullable, number } from "narrows";
const validate = nullable(number);
validate(0); // true
validate(null); // true
validate("string"); // false
const foo: unknown = null;
if (validate(foo)) {
foo; // type narrowed to number | null
}
Throws if the argument doesn't match the given validator.
Narrows to the validator type.
import { asserts, number } from "narrows";
const validate = asserts(number);
try {
validate(0);
// no error is thrown
} catch (e) {}
try {
validate("string");
} catch (e) {
// error is thrown
}
TypeScript type that extracts the validated type from a validator function.
import { boolean, number, record, string, tuple, TypeOf } from "narrows";
const stringValidator = string;
type Foo = TypeOf<typeof stringValidator>; // string
const complexValidator = record({
a: string,
b: tuple(boolean, number)
});
type Bar = TypeOf<typeof complexValidator>; // { a: string; b: [boolean, number] }