Skip to content

Predicates Reference

Coverage License NPM Version Open Issues Size

🧐 Predicate util functions

Usage

📦 Node

Install @lou.codes/predicates as a dependency:

Terminal window
pnpm add @lou.codes/predicates
# or
npm install @lou.codes/predicates
# or
yarn add @lou.codes/predicates

Import it and use it:

import { isBoolean } from "@lou.codes/predicates";
isBoolean(true); // true
isBoolean(false); // true
isBoolean(undefined); // false

🦕 Deno

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

import { isBoolean } from "npm:@lou.codes/predicates";
isBoolean(true); // true
isBoolean(false); // true
isBoolean(undefined); // false

🌎 Browser

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

<script type="module">
import { isBoolean } from "https://esm.sh/@lou.codes/predicates";
isBoolean(true); // true
isBoolean(false); // true
isBoolean(undefined); // false
</script>

Common

is

is<Expected>(expected): (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

Name
Expected

Parameters

NameType
expectedExpected

Returns

fn

Curried function with expected in context.

▸ (actual): actual is Expected

Parameters
NameType
actualunknown
Returns

actual is Expected

Example

const is2 = is(2);
is2(2); // true
is2(8); // false

View source


isFalsy

isFalsy(input): input is Falsy

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

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is Falsy

Returns true if falsy, false otherwise.

Example

isFalsy(false); // true
isFalsy(0); // true
isFalsy(NaN); // true
isFalsy(""); // true
isFalsy(null); // true
isFalsy(undefined); // true
isFalsy(42); // false

View source


isTruthy

isTruthy<Input>(input): input is Truthy<ReadOnly<Input>>

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

Type parameters

Name
Input

Parameters

NameTypeDescription
inputInput | Truthy<ReadOnly<Input>>Value to check.

Returns

input is Truthy<ReadOnly<Input>>

Returns true if truthy, false otherwise.

Example

isTruthy(42); // true
isTruthy(true); // true
isTruthy(false); // false
isTruthy(0); // false

View source

Iterables

hasAsyncIteratorSymbol

hasAsyncIteratorSymbol(object): object is Readonly<Record<typeof asyncIterator, unknown>>

Check if given object has the Symbol.asyncIterator symbol.

Parameters

NameType
objectunknown

Returns

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

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

Example

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

View source


hasIteratorSymbol

hasIteratorSymbol(object): object is Readonly<Record<typeof iterator, unknown>>

Check if given object has the Symbol.iterator symbol.

Parameters

NameType
objectunknown

Returns

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

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

Example

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

View source


isArray

isArray<Item>(input): input is ReadOnlyArray<Item>

Check if given input is an instance of Array.

Type parameters

Name
Item

Parameters

NameType
inputunknown

Returns

input is ReadOnlyArray<Item>

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

Example

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

View source


isAsyncIterable

isAsyncIterable<Item>(input): input is Object

Check if given value is AsyncIterable.

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

Type parameters

Name
Item

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is Object

true when is an AsyncIterable, false otherwise.

Example

isAsyncIterable(
(async function* () {
yield* [];
})(),
); // true
isAsyncIterable([]); // false
isAsyncIterable({}); // false

View source


isIsomorphicIterable

isIsomorphicIterable<Item>(input): 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

Name
Item

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is IsomorphicIterable<Item>

true when is an IsomorphicIterable, false otherwise.

Example

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

View source


isIterable

isIterable<Item>(input): input is Object

Check if given value is Iterable.

Type parameters

Name
Item

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is Object

true when is an Iterable, false otherwise.

Example

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

View source

Objects

has

has<Property>(property): (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

NameType
Propertyextends PropertyKey

Parameters

NameType
propertyProperty

Returns

fn

Curried function with property in context.

▸ (object): object is Readonly<Record<Property, unknown>>

Parameters
NameType
objectunknown
Returns

object is Readonly<Record<Property, unknown>>

Example

const hasCircle = has("🟢");
hasCircle({ "🟢": "🟩" }); // true
hasCircle({ "🟩": "🟢" }); // false

View source


hasAsyncIteratorSymbol

hasAsyncIteratorSymbol(object): object is Readonly<Record<typeof asyncIterator, unknown>>

Check if given object has the Symbol.asyncIterator symbol.

Parameters

NameType
objectunknown

Returns

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

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

Example

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

View source


hasIteratorSymbol

hasIteratorSymbol(object): object is Readonly<Record<typeof iterator, unknown>>

Check if given object has the Symbol.iterator symbol.

Parameters

NameType
objectunknown

Returns

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

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

Example

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

View source


isDate

isDate(input): input is Date

instanceof Date alias.

Parameters

NameType
inputunknown

Returns

input is Date

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

Example

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

View source


isFunction

isFunction(input): input is Function

typeof “function” alias.

Parameters

NameType
inputunknown

Returns

input is Function

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

Example

isFunction(() => {}); // true
isFunction(function () {}); // true
isFunction(function* () {}); // true
isFunction(class {}); // true
isFunction(null); // false

View source


isInstanceOf

isInstanceOf<Expected>(constructor): (input: unknown) => input is InstanceType<Expected>

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

Type parameters

NameType
Expectedextends Class<never>

Parameters

NameType
constructorExpected

Returns

fn

Returns a curried function with constructor in context.

▸ (input): input is InstanceType<Expected>

Parameters
NameType
inputunknown
Returns

input is InstanceType<Expected>

Example

const instanceOfArray = instanceOf(Array);
instanceOfArray([]); // true
instanceOfArray({}); // false

View source


isObject

isObject(input): input is object

typeof “object” alias.

Parameters

NameType
inputunknown

Returns

input is object

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

Example

isObject({}); // true
isObject([]); // true
isObject(new Date()); // true
isObject(null); // false

View source


isPromise

isPromise(input): input is Promise<unknown>

instanceof Promise alias.

Parameters

NameType
inputunknown

Returns

input is Promise<unknown>

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

Example

isPromise(new Promise()); // true
isPromise((async () => {})()); // true
isPromise(fetch("/")); // true
isPromise(Promise.resolve("Lou")); // true
isPromise("Lou"); // false

View source


isPropertyKey

isPropertyKey(input): input is PropertyKey

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

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is PropertyKey

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

Example

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

View source


isPropertyOf

isPropertyOf<Key>(object): (key: Key) => boolean

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

Type parameters

NameType
Keyextends PropertyKey

Parameters

NameTypeDescription
objectReadOnlyRecord<Key>Object to check.

Returns

fn

Curried function with context set.

▸ (key): boolean

Parameters
NameType
keyKey
Returns

boolean

Example

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

View source


isPrototypeOf

isPrototypeOf<Constructor>(constructor): <Input>(object: Input) => boolean

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

Type parameters

NameType
Constructorextends Class

Parameters

NameTypeDescription
constructorConstructorConstructor to check.

Returns

fn

Returns a curried function with constructor in context.

▸ <Input>(object): boolean

Type parameters
NameType
Inputextends object
Parameters
NameType
objectInput
Returns

boolean

Example

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

View source


isRegExp

isRegExp(input): input is RegExp

instanceof RegExp alias.

Parameters

NameType
inputunknown

Returns

input is RegExp

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

Example

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

View source

Predicates

isPropertyOf

isPropertyOf<Key>(object): (key: Key) => boolean

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

Type parameters

NameType
Keyextends PropertyKey

Parameters

NameTypeDescription
objectReadOnlyRecord<Key>Object to check.

Returns

fn

Curried function with context set.

▸ (key): boolean

Parameters
NameType
keyKey
Returns

boolean

Example

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

View source


isPrototypeOf

isPrototypeOf<Constructor>(constructor): <Input>(object: Input) => boolean

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

Type parameters

NameType
Constructorextends Class

Parameters

NameTypeDescription
constructorConstructorConstructor to check.

Returns

fn

Returns a curried function with constructor in context.

▸ <Input>(object): boolean

Type parameters
NameType
Inputextends object
Parameters
NameType
objectInput
Returns

boolean

Example

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

View source


isPrototypeOfObject

isPrototypeOfObject<Input>(object): boolean

Given input’s prototype comes directly from Object.

Type parameters

NameType
Inputextends object

Parameters

NameType
objectInput

Returns

boolean

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

Example

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

View source


isType

isType<Type>(type): (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

NameType
Typeextends keyof TypeOfDictionary

Parameters

NameType
typeType

Returns

fn

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

▸ (input): input is TypeOfDictionary[Type]

Parameters
NameType
inputunknown
Returns

input is TypeOfDictionary[Type]

Example

const isString = isType("string");
isString("value"); // true
isString(1); // false

View source

Primitives

asyncIteratorSymbol

Const asyncIteratorSymbol: typeof Symbol.asyncIterator

Symbol.asyncIterator shorthand (useful for minification/bundling).

See

Symbol.asyncIterator

View source


iteratorSymbol

Const iteratorSymbol: typeof Symbol.iterator

Symbol.iterator shorthand (useful for minification/bundling).

See

Symbol.iterator

View source


between

between(start): (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

NameTypeDescription
startstring | NumericMinimum boundary.

Returns

fn

Curried function with start in context.

▸ (end): (value: string | Numeric) => boolean

Parameters
NameType
endstring | Numeric
Returns

fn

▸ (value): boolean

Parameters
NameType
valuestring | Numeric
Returns

boolean

Example

const between0 = between(0);
const between0And10 = between0(10);
between0And10(5); // true
between0And10(-1); // false
between0And10(11); // false

View source


isBigInt

isBigInt(input): input is bigint

typeof “bigint” alias.

Parameters

NameType
inputunknown

Returns

input is bigint

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

Example

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

View source


isBoolean

isBoolean(input): input is boolean

typeof “boolean” alias.

Parameters

NameType
inputunknown

Returns

input is boolean

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

Example

isBoolean(true); // true
isBoolean(false); // true
isBoolean(null); // false

View source


isNull

isNull(input): 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

NameType
inputunknown

Returns

input is null

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

Example

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

View source


isNullish

isNullish(input?): input is Nullish

Check if input is undefined or null.

Parameters

NameTypeDefault value
inputunknownnull

Returns

input is Nullish

true if nullish, false otherwise.

Example

isNullish(undefined); // true
isNullish(null); // true
isNullish(""); // false
isNullish(42); // false

View source


isNumber

isNumber(input): input is number

typeof “number” alias.

Parameters

NameType
inputunknown

Returns

input is number

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

Example

isNumber(1); // true
isNumber(Infinity); // true
isNumber(NaN); // true
isNumber(1n); // false

View source


isSafeInteger

isSafeInteger(...input): boolean

Check if value passed is a safe integer.

Parameters

NameType
...inputSingle<number>

Returns

boolean

Example

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

View source


isString

isString(input): input is string

typeof “string” alias.

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is string

Returns true if value is a string, false otherwise.

Example

isString("Lou"); // true
isString(`Lou`); // true
isString(Symbol("Lou")); // false

View source


isSymbol

isSymbol(input): input is symbol

typeof “symbol” alias.

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is symbol

Returns true if value is a symbol, false otherwise.

Example

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

View source


isUndefined

isUndefined(input): input is undefined

typeof “undefined” alias.

Parameters

NameTypeDescription
inputunknownValue to check.

Returns

input is undefined

Returns true if value is undefined, false otherwise.

Example

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

View source


match

match(regularExpression): (text: string) => boolean

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

Parameters

NameTypeDescription
regularExpression{ dotAll: boolean ; flags: string ; global: boolean ; hasIndices: boolean ; ignoreCase: boolean ; lastIndex: number ; multiline: boolean ; source: string ; sticky: boolean ; unicode: boolean ; [matchAll]: (str: string) => IterableIterator<RegExpMatchArray> ; [match]: (string: string) => null | RegExpMatchArray ; [replace]: (string: string, replaceValue: string) => string(string: string, replacer: (substring: string, …args: any[]) => string) => string ; [search]: (string: string) => number ; [split]: (string: string, limit?: number) => string[] ; compile: (pattern: string, flags?: string) => this ; exec: (string: string) => null | RegExpExecArray ; test: (string: string) => boolean } | `/${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

fn

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

▸ (text): boolean

Parameters
NameType
textstring
Returns

boolean

Example

const matchNumbers = match(/\d+/u);
matchNumbers("123"); // true
matchNumbers("abc"); // false

View source