@absoluteui/helpers/is

Type guards and assertion functions.

import { ... } from '@absoluteui/helpers/is';

How to use

Type guards and assertions for values of unknown shape: parsed JSON, postMessage data, storage, and third-party callbacks. Each is... function narrows the TypeScript type; each assert... function throws a ValidationError (HLP_TYPE_ASSERTION) naming the field, never the value. For whole-object schemas, use helpers/validate; the Helpers and services guide covers the shared conventions.

How do I check a JSON payload before using it?

Combine isPlainObject, hasKey, and the primitive guards into one type guard; after it returns true, the fields are typed without casts.

import { hasKey, isFiniteNumber, isOneOf, isPlainObject, isString } from '@absoluteui/helpers/is';

interface LeaveRequest { employeeId: string; days: number; type: 'annual' | 'sick' }

function isLeaveRequest(value: unknown): value is LeaveRequest {
  return isPlainObject(value)
    && hasKey(value, 'employeeId') && isString(value.employeeId)
    && hasKey(value, 'days') && isFiniteNumber(value.days)
    && hasKey(value, 'type') && isOneOf(value.type, ['annual', 'sick'] as const);
}
isLeaveRequest(JSON.parse('{"employeeId":"E-7","days":3,"type":"annual"}')); // => true
isLeaveRequest(JSON.parse('{"employeeId":"E-7","days":"3","type":"annual"}')); // => false
isLeaveRequest(JSON.parse('[1,2]')); // => false

How do I fail fast on a missing or wrong value?

The assertions narrow the variable for the rest of the scope, so later code needs no checks or !.

import { assertDefined, assertFiniteNumber } from '@absoluteui/helpers/is';

const settings = new Map<string, unknown>([['maxCarryOverDays', 5]]);
const carryOver = settings.get('maxCarryOverDays');
assertFiniteNumber(carryOver, 'maxCarryOverDays');
carryOver * 8; // => 40
const manager = settings.get('manager');
assertDefined(manager, 'manager'); // => throws HLP_TYPE_ASSERTION

How do I tell whether an optional form field was filled in?

isBlank treats whitespace-only strings as empty; isEmpty also covers empty arrays, maps, sets, and objects. Numbers and booleans, including 0 and false, are never empty.

import { isBlank, isEmpty } from '@absoluteui/helpers/is';

const form = { middleName: '   ', skills: [], overtimeHours: 0 };
isBlank(form.middleName); // => true
isEmpty(form.skills); // => true
isEmpty(form.overtimeHours); // => false

How do I filter out missing values with the right type?

isDefined is a type guard, so filter(isDefined) removes null and undefined and narrows the element type.

import { isDefined, isNonEmptyArray } from '@absoluteui/helpers/is';

const managerIds: (string | null | undefined)[] = ['E-1', null, 'E-4', undefined];
const ids: string[] = managerIds.filter(isDefined);
ids; // => ['E-1', 'E-4']
isNonEmptyArray(ids) ? ids[0].toLowerCase() : ''; // => 'e-1'

API reference

Functions

assertArray

function assertArray(value: unknown, name?: string): asserts value is unknown[];

Example:

assertArray({ length: 0 }, 'rows'); // => throws HLP_TYPE_ASSERTION

assertBoolean

function assertBoolean(value: unknown, name?: string): asserts value is boolean;

Example:

assertBoolean('yes', 'active'); // => throws HLP_TYPE_ASSERTION

assertDefined

function assertDefined<T>(value: T, name?: string): asserts value is NonNullable<T>;

Example:

const manager: string | undefined = undefined;
assertDefined(manager, 'manager'); // => throws HLP_TYPE_ASSERTION

assertFiniteNumber

function assertFiniteNumber(value: unknown, name?: string): asserts value is number;

Example:

assertFiniteNumber(Infinity, 'salary'); // => throws HLP_TYPE_ASSERTION

assertInteger

function assertInteger(value: unknown, name?: string): asserts value is number;

Example:

assertInteger(2.5, 'leaveDays'); // => throws HLP_TYPE_ASSERTION

assertPlainObject

function assertPlainObject(value: unknown, name?: string): asserts value is Record<string, unknown>;

Example:

assertPlainObject([], 'filters'); // => throws HLP_TYPE_ASSERTION

assertString

function assertString(value: unknown, name?: string): asserts value is string;

Example:

const input: unknown = 'ada@example.com';
assertString(input, 'input');
input.toUpperCase(); // => 'ADA@EXAMPLE.COM'
assertString(42, 'email'); // => throws HLP_TYPE_ASSERTION

assertValidDate

function assertValidDate(value: unknown, name?: string): asserts value is Date;

Example:

assertValidDate(new Date('not a date'), 'hireDate'); // => throws HLP_TYPE_ASSERTION

hasKey

Key exists as an own property; narrows the object type.

function hasKey<K extends PropertyKey>(value: unknown, key: K): value is Record<K, unknown>;

Example:

const payload: unknown = JSON.parse('{"id":42}');
hasKey(payload, 'id'); // => true

isArray

function isArray(value: unknown): value is unknown[];

Example:

isArray('abc'); // => false

isAsyncIterable

function isAsyncIterable(value: unknown): value is AsyncIterable<unknown>;

Example:

async function* rows() { yield 1; }
isAsyncIterable(rows()); // => true

isBigInt

function isBigInt(value: unknown): value is bigint;

Example:

isBigInt(10n); // => true

isBinary

ArrayBuffer, typed array, or DataView.

function isBinary(value: unknown): value is ArrayBuffer | ArrayBufferView;

Example:

isBinary(new Uint8Array(4)); // => true

isBlank

null, undefined, or a string with only whitespace.

function isBlank(value: unknown): boolean;

Example:

isBlank('   '); // => true
isBlank(0); // => false

isBoolean

function isBoolean(value: unknown): value is boolean;

Example:

isBoolean('true'); // => false

isBrowserLike

Running in a browser main thread or worker with document or self.

function isBrowserLike(): boolean;

Example:

isBrowserLike(); // true in a browser or worker, false in Node without a DOM

isDate

function isDate(value: unknown): value is Date;

Example:

isDate(new Date(NaN)); // => true

isDefined

Neither null nor undefined. Useful as a filter: arr.filter(isDefined).

function isDefined<T>(value: T): value is NonNullable<T>;

Example:

[1, null, 2, undefined].filter(isDefined); // => [1, 2]

isEmpty

Empty check: null/undefined, '', [], empty Map/Set, {} with no own keys. Numbers and booleans are never empty.

function isEmpty(value: unknown): boolean;

Example:

isEmpty({}) // => true

isError

function isError(value: unknown): value is Error;

Example:

isError(new TypeError('Bad input.')); // => true

isFiniteNumber

A number that is not NaN or ±Infinity.

function isFiniteNumber(value: unknown): value is number;

Example:

isFiniteNumber(NaN) // => false

isFunction

function isFunction(value: unknown): value is Function;

Example:

isFunction(() => 1); // => true

isInteger

function isInteger(value: unknown): value is number;

Example:

isInteger(40.5); // => false

isIterable

Implements Symbol.iterator (strings included).

function isIterable(value: unknown): value is Iterable<unknown>;

Example:

isIterable('abc'); // => true
isIterable({}); // => false

isMap

function isMap(value: unknown): value is Map<unknown, unknown>;

Example:

isMap(new Map()); // => true

isNil

null or undefined.

function isNil(value: unknown): value is null | undefined;

Example:

isNil(undefined) // => true

isNonEmptyArray

Non-empty array with a narrowed tuple type.

function isNonEmptyArray<T>(value: readonly T[] | null | undefined): value is readonly [T, ...T[]];

Example:

const ids: number[] = [7, 9];
if (isNonEmptyArray(ids)) ids[0].toFixed(); // first element typed as number
isNonEmptyArray([]); // => false

isNumber

Any number, including NaN and Infinity. Prefer isFiniteNumber.

function isNumber(value: unknown): value is number;

Example:

isNumber(NaN); // => true

isObject

Any non-null object, including arrays.

function isObject(value: unknown): value is object;

Example:

isObject([]); // => true

isOneOf

Value is one of options (uses SameValueZero).

function isOneOf<const T extends readonly unknown[]>(value: unknown, options: T): value is T[number];

Example:

const status: unknown = 'active';
isOneOf(status, ['active', 'on-leave'] as const); // => true

isPlainObject

Object literal or Object.create(null); not arrays, dates, maps, class instances.

function isPlainObject(value: unknown): value is Record<string, unknown>;

Example:

isPlainObject({ id: 1 }); // => true
isPlainObject(new Date()); // => false

isPrimitive

string | number | boolean | bigint | symbol | null | undefined.

function isPrimitive(value: unknown): value is string | number | boolean | bigint | symbol | null | undefined;

Example:

isPrimitive(null); // => true
isPrimitive({}); // => false

isPromiseLike

Has a callable then.

function isPromiseLike(value: unknown): value is PromiseLike<unknown>;

Example:

isPromiseLike(Promise.resolve(1)); // => true
isPromiseLike({ then: 1 }); // => false

isRegExp

function isRegExp(value: unknown): value is RegExp;

Example:

isRegExp(/^EMP-/); // => true

isSafeInteger

Integer within Number.MIN_SAFE_INTEGER..MAX_SAFE_INTEGER.

function isSafeInteger(value: unknown): value is number;

Example:

isSafeInteger(2 ** 53); // => false

isSet

function isSet(value: unknown): value is Set<unknown>;

Example:

isSet(new Set([1])); // => true

isString

function isString(value: unknown): value is string;

Example:

isString('EMP-001'); // => true

isSymbol

function isSymbol(value: unknown): value is symbol;

Example:

isSymbol(Symbol.iterator); // => true

isValidDate

Any valid Date (not Invalid Date).

function isValidDate(value: unknown): value is Date;

Example:

isValidDate(new Date('2026-13-45')); // => false