tessl/npm-sindresorhus--is

Type check values with comprehensive TypeScript type guards and runtime assertions

—

Pending

Overview

Eval results

Files

Objects and Built-in Types

Name: tessl/npm-sindresorhus--is
Author: tessl

Type checking for JavaScript built-in objects including arrays, functions, dates, regular expressions, maps, sets, errors, and other object types.

Capabilities

Array Type Checking

Check if a value is an array, with optional validation of all array items.

/**
 * Check if value is an array, optionally validating all items
 * @param value - Value to check
 * @param assertion - Optional function to validate each array item
 * @returns True if value is array and all items pass assertion (if provided)
 */
function isArray<T = unknown>(value: unknown, assertion?: (value: T) => value is T): value is T[];

Usage Examples:

import is from '@sindresorhus/is';

is.array([]); // => true
is.array([1, 2, 3]); // => true
is.array('not array'); // => false

// With item validation
is.array([1, 2, 3], is.number); // => true
is.array([1, '2', 3], is.number); // => false
is.array(['a', 'b'], is.string); // => true

// Type guard with validation
if (is.array(someValue, is.string)) {
  // someValue is now typed as string[]
  console.log(someValue.map(s => s.toUpperCase()));
}

Function Type Checking

Check if a value is a function.

/**
 * Check if value is a function
 * @param value - Value to check
 * @returns True if value is function
 */
function isFunction(value: unknown): value is Function;

Usage Examples:

import is from '@sindresorhus/is';

is.function(() => {}); // => true
is.function(function() {}); // => true
is.function(Math.max); // => true
is.function({}); // => false

Object Type Checking

Check if a value is an object. Note that functions are also considered objects in JavaScript.

/**
 * Check if value is an object (includes functions)
 * @param value - Value to check
 * @returns True if value is object
 */
function isObject(value: unknown): value is object;

Usage Examples:

import is from '@sindresorhus/is';

is.object({}); // => true
is.object([]); // => true
is.object(() => {}); // => true (functions are objects)
is.object(new Date()); // => true
is.object(null); // => false
is.object('string'); // => false

Plain Object Type Checking

Check if a value is a plain object created by {}, new Object(), or Object.create(null).

/**
 * Check if value is a plain object
 * @param value - Value to check
 * @returns True if value is plain object
 */
function isPlainObject<Value = unknown>(value: unknown): value is Record<PropertyKey, Value>;

Usage Examples:

import is from '@sindresorhus/is';

is.plainObject({}); // => true
is.plainObject(Object.create(null)); // => true
is.plainObject(new Object()); // => true
is.plainObject([]); // => false
is.plainObject(new Date()); // => false
is.plainObject(() => {}); // => false

Date Type Checking

Check if a value is a Date object.

/**
 * Check if value is a Date object
 * @param value - Value to check
 * @returns True if value is Date
 */
function isDate(value: unknown): value is Date;

Usage Examples:

import is from '@sindresorhus/is';

is.date(new Date()); // => true
is.date(new Date('invalid')); // => true (but may be Invalid Date)
is.date('2023-01-01'); // => false
is.date(1640995200000); // => false

Valid Date Checking

Check if a value is a valid Date object (not Invalid Date).

/**
 * Check if value is a valid Date object
 * @param value - Value to check
 * @returns True if value is valid Date
 */
function isValidDate(value: unknown): value is Date;

Usage Examples:

import is from '@sindresorhus/is';

is.validDate(new Date()); // => true
is.validDate(new Date('2023-01-01')); // => true
is.validDate(new Date('invalid')); // => false
is.validDate('2023-01-01'); // => false

RegExp Type Checking

Check if a value is a regular expression.

/**
 * Check if value is a RegExp
 * @param value - Value to check
 * @returns True if value is RegExp
 */
function isRegExp(value: unknown): value is RegExp;

Usage Examples:

import is from '@sindresorhus/is';

is.regExp(/abc/); // => true
is.regExp(new RegExp('abc')); // => true
is.regExp('abc'); // => false

Error Type Checking

Check if a value is an Error object.

/**
 * Check if value is an Error
 * @param value - Value to check
 * @returns True if value is Error
 */
function isError(value: unknown): value is Error;

Usage Examples:

import is from '@sindresorhus/is';

is.error(new Error()); // => true
is.error(new TypeError()); // => true
is.error(new ReferenceError()); // => true
is.error('error message'); // => false

Map Type Checking

Check if a value is a Map object.

/**
 * Check if value is a Map
 * @param value - Value to check
 * @returns True if value is Map
 */
function isMap<Key = unknown, Value = unknown>(value: unknown): value is Map<Key, Value>;

Usage Examples:

import is from '@sindresorhus/is';

is.map(new Map()); // => true
is.map(new Map([['key', 'value']])); // => true
is.map({}); // => false
is.map(new Set()); // => false

Set Type Checking

Check if a value is a Set object.

/**
 * Check if value is a Set
 * @param value - Value to check
 * @returns True if value is Set
 */
function isSet<T = unknown>(value: unknown): value is Set<T>;

Usage Examples:

import is from '@sindresorhus/is';

is.set(new Set()); // => true
is.set(new Set([1, 2, 3])); // => true
is.set([]); // => false
is.set(new Map()); // => false

WeakMap Type Checking

Check if a value is a WeakMap object.

/**
 * Check if value is a WeakMap
 * @param value - Value to check
 * @returns True if value is WeakMap
 */
function isWeakMap<Key extends object = object, Value = unknown>(value: unknown): value is WeakMap<Key, Value>;

Usage Examples:

import is from '@sindresorhus/is';

is.weakMap(new WeakMap()); // => true
is.weakMap(new Map()); // => false

WeakSet Type Checking

Check if a value is a WeakSet object.

/**
 * Check if value is a WeakSet
 * @param value - Value to check
 * @returns True if value is WeakSet
 */
function isWeakSet<T extends object = object>(value: unknown): value is WeakSet<T>;

Usage Examples:

import is from '@sindresorhus/is';

is.weakSet(new WeakSet()); // => true
is.weakSet(new Set()); // => false

WeakRef Type Checking

Check if a value is a WeakRef object.

/**
 * Check if value is a WeakRef
 * @param value - Value to check
 * @returns True if value is WeakRef
 */
function isWeakRef<T extends object = object>(value: unknown): value is WeakRef<T>;

Usage Examples:

import is from '@sindresorhus/is';

const obj = {};
is.weakRef(new WeakRef(obj)); // => true
is.weakRef(obj); // => false

Class Type Checking

Check if a value is a class constructor.

/**
 * Check if value is a class constructor
 * @param value - Value to check
 * @returns True if value is class
 */
function isClass<T = unknown>(value: unknown): value is Class<T>;

type Class<T, Arguments extends unknown[] = any[]> = Constructor<T, Arguments> & {prototype: T};

Usage Examples:

import is from '@sindresorhus/is';

class MyClass {}
is.class(MyClass); // => true
is.class(function() {}); // => false
is.class(() => {}); // => false

Direct Instance Checking

Check if an instance is a direct instance of a class (not inherited).

/**
 * Check if instance is direct instance of class
 * @param instance - Instance to check
 * @param class_ - Class to check against
 * @returns True if instance is direct instance of class
 */
function isDirectInstanceOf<T>(instance: unknown, class_: Class<T>): instance is T;

Usage Examples:

import is from '@sindresorhus/is';

class Parent {}
class Child extends Parent {}

const parent = new Parent();
const child = new Child();

is.directInstanceOf(parent, Parent); // => true
is.directInstanceOf(child, Parent); // => false
is.directInstanceOf(child, Child); // => true

Bound Function Type Checking

Check if a value is a bound function.

/**
 * Check if value is a bound function
 * @param value - Value to check
 * @returns True if value is bound function
 */
function isBoundFunction(value: unknown): value is Function;

Usage Examples:

import is from '@sindresorhus/is';

const fn = function() {};
const boundFn = fn.bind(null);
const arrowFn = () => {};

is.boundFunction(boundFn); // => true
is.boundFunction(arrowFn); // => true (arrow functions are bound)
is.boundFunction(fn); // => false

Property Key Type Checking

Check if a value can be used as an object property key (string, number, or symbol).

/**
 * Check if value can be used as property key
 * @param value - Value to check
 * @returns True if value is valid property key
 */
function isPropertyKey(value: unknown): value is PropertyKey;

type PropertyKey = string | number | symbol;

Usage Examples:

import is from '@sindresorhus/is';

is.propertyKey('key'); // => true
is.propertyKey(42); // => true
is.propertyKey(Symbol('key')); // => true
is.propertyKey({}); // => false
is.propertyKey(null); // => false

Notes

Functions are considered objects in JavaScript, so is.object(fn) returns true
Use is.plainObject() to exclude arrays, functions, and other object types
is.date() returns true for Invalid Date objects; use is.validDate() for valid dates only
All object type checks work with TypeScript type guards for compile-time type narrowing