Predicates Reference

Coverage License NPM Version Open Issues

🧐 Predicate util functions

Usage

📦 Node

Install @lou.codes/predicates as a dependency:

1
pnpm add @lou.codes/predicates
2
# or
3
npm install @lou.codes/predicates
4
# or
5
yarn add @lou.codes/predicates

Import it and use it:

1
import { isBoolean } from "@lou.codes/predicates";
2

3
isBoolean(true); // true
4
isBoolean(false); // true
5
isBoolean(undefined); // false

🦕 Deno

Import @lou.codes/predicates using the npm: prefix, and use it directly:

1
import { isBoolean } from "npm:@lou.codes/predicates";
2

3
isBoolean(true); // true
4
isBoolean(false); // true
5
isBoolean(undefined); // false

🌎 Browser

Import @lou.codes/predicates using esm.sh, and use it directly:

1
<script type="module">
2
	import { isBoolean } from "https://esm.sh/@lou.codes/predicates";
3

4
	isBoolean(true); // true
5
	isBoolean(false); // true
6
	isBoolean(undefined); // false
7
</script>

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Common

is()

1
function is<Expected>(
2
	expected: Expected,
3
): (actual: unknown) => actual is Expected;

Curried wrapper for Object.is. Given and expected value and an actual value, returns true if those values are equal, or false if not.

Type parameters

Type parameter
`Expected`

Parameters

Parameter	Type
`expected`	`Expected`

Returns

Function

Curried function with expected in context.

Parameters

Parameter	Type
`actual`	`unknown`

Returns

actual is Expected

Example

1
const is2 = is(2);
2

3
is2(2); // true
4
is2(8); // false

isFalsy()

1
function isFalsy(input: unknown): input is Falsy;

Check if given input is falsy (0, NaN, "", false, or nullish).

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is Falsy

Returns true if falsy, false otherwise.

Example

1
isFalsy(false); // true
2
isFalsy(0); // true
3
isFalsy(NaN); // true
4
isFalsy(""); // true
5
isFalsy(null); // true
6
isFalsy(undefined); // true
7
isFalsy(42); // false

isTruthy()

1
function isTruthy<Input>(
2
	input: Input | Truthy<Readonly<Input>>,
3
): input is Truthy<Readonly<Input>>;

Check if given input is truthy (so not 0, NaN, "", false, or nullish).

Type parameters

Type parameter
`Input`

Parameters

Parameter	Type	Description
`input`	`Input` \| `Truthy`<`Readonly`<`Input`>>	Value to check.

Returns

input is Truthy<Readonly<Input>>

Returns true if truthy, false otherwise.

Example

1
isTruthy(42); // true
2
isTruthy(true); // true
3
isTruthy(false); // false
4
isTruthy(0); // false

Iterables

hasAsyncIteratorSymbol()

1
function hasAsyncIteratorSymbol(
2
	object: unknown,
3
): object is Readonly<Record<typeof asyncIterator, unknown>>;

Check if given object has the Symbol.asyncIterator symbol.

Parameters

Parameter	Type
`object`	`unknown`

Returns

object is Readonly<Record<typeof asyncIterator, unknown>>

true when given object has the Symbol.asyncIterator symbol, false otherwise.

Example

1
hasAsyncIteratorSymbol({ [Symbol.asyncIterator]() {} }); // true
2
hasAsyncIteratorSymbol({ bar: "bar" }); // false

hasIteratorSymbol()

1
function hasIteratorSymbol(
2
	object: unknown,
3
): object is Readonly<Record<typeof iterator, unknown>>;

Check if given object has the Symbol.iterator symbol.

Parameters

Parameter	Type
`object`	`unknown`

Returns

object is Readonly<Record<typeof iterator, unknown>>

true when given object has the Symbol.iterator symbol, false otherwise.

Example

1
hasIteratorSymbol({ [Symbol.iterator]() {} }); // true
2
hasIteratorSymbol({ bar: "bar" }); // false

isArray()

1
function isArray<Item>(input: unknown): input is ReadOnlyArray<Item>;

Check if given input is an instance of Array.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is ReadOnlyArray<Item>

true if the given value is an array, false otherwise.

Example

1
isArray([]); // true
2
isArray({ length: 42 }); // false

isAsyncIterable()

1
function isAsyncIterable<Item>(
2
	input: unknown,
3
): input is Readonly<AsyncIterable<Item>>;

Check if given value is AsyncIterable.

Not to be confused with isAsynchronousIterable which checks for both AsyncIterable and Iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is Readonly<AsyncIterable<Item>>

true when is an AsyncIterable, false otherwise.

Example

1
isAsyncIterable(
2
	(async function* () {
3
		yield* [];
4
	})(),
5
); // true
6
isAsyncIterable([]); // false
7
isAsyncIterable({}); // false

isIsomorphicIterable()

1
function isIsomorphicIterable<Item>(
2
	input: unknown,
3
): input is IsomorphicIterable<Item>;

Check if given value is IsomorphicIterable (either Iterable or AsyncIterable).

Not to be confused with isAsyncIterable which only checks for AsyncIterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is IsomorphicIterable<Item>

true when is an IsomorphicIterable, false otherwise.

Example

1
isIterable([]); // true
2
isIterable({}); // false

isIterable()

1
function isIterable<Item>(input: unknown): input is Readonly<Iterable<Item>>;

Check if given value is Iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is Readonly<Iterable<Item>>

true when is an Iterable, false otherwise.

Example

1
isIterable([]); // true
2
isIterable({}); // false

Objects

has()

1
function has<Property>(
2
	property: Property,
3
): (object: unknown) => object is Readonly<Record<Property, unknown>>;

Curried wrapper for the in operator. Given a property name and an object, returns true the object contains that property, false otherwise.

Type parameters

Type parameter
`Property` extends `PropertyKey`

Parameters

Parameter	Type
`property`	`Property`

Returns

Function

Curried function with property in context.

Parameters

Parameter	Type
`object`	`unknown`

Returns

object is Readonly<Record<Property, unknown>>

Example

1
const hasCircle = has("🟢");
2

3
hasCircle({ "🟢": "🟩" }); // true
4
hasCircle({ "🟩": "🟢" }); // false

hasAsyncIteratorSymbol()

1
function hasAsyncIteratorSymbol(
2
	object: unknown,
3
): object is Readonly<Record<typeof asyncIterator, unknown>>;

Check if given object has the Symbol.asyncIterator symbol.

Parameters

Parameter	Type
`object`	`unknown`

Returns

object is Readonly<Record<typeof asyncIterator, unknown>>

true when given object has the Symbol.asyncIterator symbol, false otherwise.

Example

1
hasAsyncIteratorSymbol({ [Symbol.asyncIterator]() {} }); // true
2
hasAsyncIteratorSymbol({ bar: "bar" }); // false

hasIteratorSymbol()

1
function hasIteratorSymbol(
2
	object: unknown,
3
): object is Readonly<Record<typeof iterator, unknown>>;

Check if given object has the Symbol.iterator symbol.

Parameters

Parameter	Type
`object`	`unknown`

Returns

object is Readonly<Record<typeof iterator, unknown>>

true when given object has the Symbol.iterator symbol, false otherwise.

Example

1
hasIteratorSymbol({ [Symbol.iterator]() {} }); // true
2
hasIteratorSymbol({ bar: "bar" }); // false

isDate()

1
function isDate(input: unknown): input is Date;

instanceof Date alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is Date

true if the given value is a Date, false otherwise.

Example

1
isBigInt(1n); // true
2
isBigInt(1); // false

isFunction()

1
function isFunction(input: unknown): input is Function;

typeof “function” alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is Function

true if the given value is a function, false otherwise.

Example

1
isFunction(() => {}); // true
2
isFunction(function () {}); // true
3
isFunction(function* () {}); // true
4
isFunction(class {}); // true
5
isFunction(null); // false

isInstanceOf()

1
function isInstanceOf<Expected>(
2
	constructor: Expected,
3
): (input: unknown) => input is InstanceType<Expected>;

Takes a constructor and checks if given input is an instance of it.

Type parameters

Type parameter
`Expected` extends `Class`<`never`>

Parameters

Parameter	Type
`constructor`	`Expected`

Returns

Function

Returns a curried function with constructor in context.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is InstanceType<Expected>

Example

1
const instanceOfArray = instanceOf(Array);
2

3
instanceOfArray([]); // true
4
instanceOfArray({}); // false

isObject()

1
function isObject(input: unknown): input is object;

typeof “object” alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is object

true if the given value is an object, false otherwise.

Example

1
isObject({}); // true
2
isObject([]); // true
3
isObject(new Date()); // true
4
isObject(null); // false

isPromise()

1
function isPromise(input: unknown): input is Promise<unknown>;

instanceof Promise alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is Promise<unknown>

true if the given value is an instance of Promise, false otherwise.

Example

1
isPromise(new Promise()); // true
2
isPromise((async () => {})()); // true
3
isPromise(fetch("/")); // true
4
isPromise(Promise.resolve("Lou")); // true
5
isPromise("Lou"); // false

isPropertyKey()

1
function isPropertyKey(input: unknown): input is PropertyKey;

Checks if the given value is a valid PropertyKey of an object (string, symbol, or number).

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is PropertyKey

true if the given value is a valid PropertyKey of an object, false otherwise.

Example

1
isPropertyKey("Lou"); // true
2
isPropertyKey(1); // true
3
isPropertyKey(Symbol("Lou")); // true
4
isPropertyKey({}); // false

isPropertyOf()

1
function isPropertyOf<Key>(
2
	object: Readonly<Record<Key, unknown>>,
3
): (key: Key) => boolean;

Check if the given key is present in the given object (not inherited).

Type parameters

Type parameter
`Key` extends `PropertyKey`

Parameters

Parameter	Type	Description
`object`	`Readonly`<`Record`<`Key`, `unknown`>>	Object to check.

Returns

Function

Curried function with context set.

Parameters

Parameter	Type
`key`	`Key`

Returns

boolean

Example

1
const isPropertyOfFoo = isPropertyOf({ "🟢": "🟩" });
2
isPropertyOfFoo("🟢"); // true
3
isPropertyOfFoo("🟩"); // false

isPrototypeOf()

1
function isPrototypeOf<Constructor>(
2
	constructor: Constructor,
3
): <Input>(object: Input) => boolean;

Checks if given input’s prototype comes directly from given constructor.

Type parameters

Type parameter
`Constructor` extends `Class`

Parameters

Parameter	Type	Description
`constructor`	`Constructor`	Constructor to check.

Returns

Function

Returns a curried function with constructor in context.

Type parameters

Type parameter
`Input` extends `object`

Parameters

Parameter	Type
`object`	`Input`

Returns

boolean

Example

1
const isPrototypeOfObject = isPrototypeOf(Object);
2
isPrototypeOfObject({}); // true
3
isPrototypeOfObject(/./); // false

isRegExp()

1
function isRegExp(input: unknown): input is RegExp;

instanceof RegExp alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is RegExp

true if the given value is an instance of RegExp, false otherwise.

Example

1
isRegExp(new RegExp("-")); // true
2
isRegExp(/-/); // true
3
isRegExp("Lou"); // false

Predicates

isPropertyOf()

1
function isPropertyOf<Key>(
2
	object: Readonly<Record<Key, unknown>>,
3
): (key: Key) => boolean;

Check if the given key is present in the given object (not inherited).

Type parameters

Type parameter
`Key` extends `PropertyKey`

Parameters

Parameter	Type	Description
`object`	`Readonly`<`Record`<`Key`, `unknown`>>	Object to check.

Returns

Function

Curried function with context set.

Parameters

Parameter	Type
`key`	`Key`

Returns

boolean

Example

1
const isPropertyOfFoo = isPropertyOf({ "🟢": "🟩" });
2
isPropertyOfFoo("🟢"); // true
3
isPropertyOfFoo("🟩"); // false

isPrototypeOf()

1
function isPrototypeOf<Constructor>(
2
	constructor: Constructor,
3
): <Input>(object: Input) => boolean;

Checks if given input’s prototype comes directly from given constructor.

Type parameters

Type parameter
`Constructor` extends `Class`

Parameters

Parameter	Type	Description
`constructor`	`Constructor`	Constructor to check.

Returns

Function

Returns a curried function with constructor in context.

Type parameters

Type parameter
`Input` extends `object`

Parameters

Parameter	Type
`object`	`Input`

Returns

boolean

Example

1
const isPrototypeOfObject = isPrototypeOf(Object);
2
isPrototypeOfObject({}); // true
3
isPrototypeOfObject(/./); // false

isPrototypeOfObject()

1
function isPrototypeOfObject<Input>(object: Input): boolean;

Given input’s prototype comes directly from Object.

Type parameters

Type parameter
`Input` extends `object`

Parameters

Parameter	Type
`object`	`Input`

Returns

boolean

true if the given value is an object inheriting directly from Object, false otherwise.

Example

1
isPrototypeOfObject({}); // true
2
isPrototypeOfObject(/./); // false

isType()

1
function isType<Type>(
2
	type: Type,
3
): (input: unknown) => input is TypeOfDictionary[Type];

Takes a type string and checks if given input is of that typeof. This “patches” typeof so null is not "object" but "null" instead (rejected proposal for lack of backwards compatibility, more details here).

Type parameters

Type parameter
`Type` extends keyof `TypeOfDictionary`

Parameters

Parameter	Type
`type`	`Type`

Returns

Function

Curried function with type in context that returns true if input is of typeof type, false otherwise.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is TypeOfDictionary[Type]

Example

1
const isString = isType("string");
2

3
isString("value"); // true
4
isString(1); // false

Primitives

between()

1
function between(
2
	start: string | Numeric,
3
): (end: string | Numeric) => (value: string | Numeric) => boolean;

Takes a start and end and returns a boolean if value number or string is between them.

Parameters

Parameter	Type	Description
`start`	`string` \| `Numeric`	Minimum boundary.

Returns

Function

Curried function with start in context.

Parameters

Parameter	Type
`end`	`string` \| `Numeric`

Returns

Function

Parameters

Parameter	Type
`value`	`string` \| `Numeric`

Returns

boolean

Example

1
const between0 = between(0);
2
const between0And10 = between0(10);
3

4
between0And10(5); // true
5
between0And10(-1); // false
6
between0And10(11); // false

isBigInt()

1
function isBigInt(input: unknown): input is bigint;

typeof “bigint” alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is bigint

true if the given value is a bigint, false otherwise.

Example

1
isBigInt(1n); // true
2
isBigInt(1); // false

isBoolean()

1
function isBoolean(input: unknown): input is boolean;

typeof “boolean” alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is boolean

true if the given value is a boolean, false otherwise.

Example

1
isBoolean(true); // true
2
isBoolean(false); // true
3
isBoolean(null); // false

isNull()

1
function isNull(input: unknown): input is null;

typeof “null” alias. This “patches” typeof so null is not "object" but "null" instead (rejected proposal for lack of backwards compatibility, more details here).

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is null

true if the given value is a null, false otherwise.

Example

1
isNull(null); // true
2
isNull(undefined); // false

isNullish()

1
function isNullish(input: unknown): input is Nullish;

Check if input is undefined or null.

Parameters

Parameter	Type	Default value
`input`	`unknown`	`null`

Returns

input is Nullish

true if nullish, false otherwise.

Example

1
isNullish(undefined); // true
2
isNullish(null); // true
3
isNullish(""); // false
4
isNullish(42); // false

isNumber()

1
function isNumber(input: unknown): input is number;

typeof “number” alias.

Parameters

Parameter	Type
`input`	`unknown`

Returns

input is number

true if the given value is a number, false otherwise.

Example

1
isNumber(1); // true
2
isNumber(Infinity); // true
3
isNumber(NaN); // true
4
isNumber(1n); // false

isSafeInteger()

1
function isSafeInteger(input: number): boolean;

Check if value passed is a safe integer.

Parameters

Parameter	Type
`input`	`number`

Returns

boolean

Example

1
isSafeInteger(13); // true
2
isSafeInteger(10.13); // false

isString()

1
function isString(input: unknown): input is string;

typeof “string” alias.

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is string

Returns true if value is a string, false otherwise.

Example

1
isString("Lou"); // true
2
isString(`Lou`); // true
3
isString(Symbol("Lou")); // false

isSymbol()

1
function isSymbol(input: unknown): input is symbol;

typeof “symbol” alias.

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is symbol

Returns true if value is a symbol, false otherwise.

Example

1
isSymbol(Symbol("Lou")); // true
2
isSymbol(Symbol.iterator); // true
3
isSymbol("Lou"); // false

isUndefined()

1
function isUndefined(input: unknown): input is undefined;

typeof “undefined” alias.

Parameters

Parameter	Type	Description
`input`	`unknown`	Value to check.

Returns

input is undefined

Returns true if value is undefined, false otherwise.

Example

1
isUndefined(undefined); // true
2
isUndefined(null); // false

match()

1
function match(
2
	regularExpression:
3
		| Readonly<RegExp>
4
		| `/${string}/u`
5
		| `/${string}/su`
6
		| `/${string}/mu`
7
		| `/${string}/msu`
8
		| `/${string}/iu`
9
		| `/${string}/isu`
10
		| `/${string}/imu`
11
		| `/${string}/imsu`
12
		| `/${string}/gu`
13
		| `/${string}/gsu`
14
		| `/${string}/gmu`
15
		| `/${string}/gmsu`
16
		| `/${string}/giu`
17
		| `/${string}/gisu`
18
		| `/${string}/gimu`
19
		| `/${string}/gimsu`,
20
): (text: string) => boolean;

Given a regular expression and a string, returns true if the string matches the regular expression.

Parameters

Parameter	Type	Description
`regularExpression`	\| `Readonly`<`RegExp`> \| `/${string}/u` \| `/${string}/su` \| `/${string}/mu` \| `/${string}/msu` \| `/${string}/iu` \| `/${string}/isu` \| `/${string}/imu` \| `/${string}/imsu` \| `/${string}/gu` \| `/${string}/gsu` \| `/${string}/gmu` \| `/${string}/gmsu` \| `/${string}/giu` \| `/${string}/gisu` \| `/${string}/gimu` \| `/${string}/gimsu`	Instance of `RegExp` or a string.

Returns

Function

true if the string matches the regular expression, false otherwise.

Parameters

Parameter	Type
`text`	`string`

Returns

boolean

Example

1
const matchNumbers = match(/\d+/u);
2

3
matchNumbers("123"); // true
4
matchNumbers("abc"); // false