or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdasync.mdcollections.mdindex.mdnumbers.mdobjects.mdprimitives.mdstrings.mdtyped-arrays.mdvalidation.mdweb-apis.md
tile.json

tessl/npm-sindresorhus--is

Type check values with comprehensive TypeScript type guards and runtime assertions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@sindresorhus/is@7.0.x

To install, run

npx @tessl/cli install tessl/npm-sindresorhus--is@7.0.0

index.mddocs/

@sindresorhus/is

@sindresorhus/is is a comprehensive TypeScript type checking library that provides runtime type validation with extensive TypeScript type guards and assertion methods. It offers both validation functions (returning boolean) and assertion functions (throwing errors), enabling reliable type checking for all JavaScript built-in types, web APIs, and Node.js specific objects.

Package Information

  • Package Name: @sindresorhus/is
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @sindresorhus/is

Core Imports

import is from '@sindresorhus/is';
import { assert } from '@sindresorhus/is';

For tree-shakable imports:

import { isString, isNumber, assertArray } from '@sindresorhus/is';

CommonJS:

const is = require('@sindresorhus/is');
const { assert } = require('@sindresorhus/is');

Named export for type detection:

import { detect } from '@sindresorhus/is';
// detect is the same as the default is function

Basic Usage

import is from '@sindresorhus/is';
import { assert } from '@sindresorhus/is';

// Type detection - returns string type name
is('hello'); // => 'string'
is(42); // => 'number'
is(new Map()); // => 'Map'

// Type validation - returns boolean
is.string('hello'); // => true
is.number('hello'); // => false

// Type assertions - throws if type doesn't match
assert.string('hello'); // passes
assert.number('hello'); // throws TypeError

// TypeScript type guards
function processValue(value: unknown) {
  if (is.string(value)) {
    // value is now typed as string
    return value.toUpperCase();
  }
  
  if (is.number(value)) {
    // value is now typed as number
    return value * 2;
  }
}

// Array validation with item assertion
const numbers = [1, 2, 3];
if (is.array(numbers, is.number)) {
  // numbers is typed as number[]
  console.log(numbers.map(n => n * 2));
}

Architecture

@sindresorhus/is is built around several key components:

  • Type Detection: Core is() function returns string type names for any value
  • Type Guards: Boolean-returning methods that provide TypeScript type narrowing
  • Assertions: Error-throwing methods for runtime type validation with custom messages
  • Tree Shaking: All methods available as named exports for optimal bundle size
  • Generic Support: Type-aware generics with runtime safety considerations
  • Comprehensive Coverage: Support for all JavaScript built-ins, web APIs, and Node.js types

Capabilities

Primitives and Basic Types

Core type checking for JavaScript primitive values including string, number, boolean, symbol, bigint, null, and undefined.

function is(value: unknown): TypeName;

// Type guards for primitives
function isString(value: unknown): value is string;
function isNumber(value: unknown): value is number;
function isBoolean(value: unknown): value is boolean;
function isSymbol(value: unknown): value is symbol;
function isBigint(value: unknown): value is bigint;
function isNull(value: unknown): value is null;
function isUndefined(value: unknown): value is undefined;

Primitives and Basic Types

Objects and Built-in Types

Type checking for JavaScript built-in objects including arrays, functions, dates, regular expressions, maps, sets, and more.

function isArray<T = unknown>(value: unknown, assertion?: (value: T) => value is T): value is T[];
function isFunction(value: unknown): value is Function;
function isObject(value: unknown): value is object;
function isDate(value: unknown): value is Date;
function isRegExp(value: unknown): value is RegExp;
function isMap<Key = unknown, Value = unknown>(value: unknown): value is Map<Key, Value>;
function isSet<T = unknown>(value: unknown): value is Set<T>;

Objects and Built-in Types

Collections and Emptiness

Specialized checks for empty and non-empty collections including arrays, objects, strings, maps, and sets.

function isEmptyArray(value: unknown): value is never[];
function isNonEmptyArray<T = unknown, Item = unknown>(value: T | Item[]): value is [Item, ...Item[]];
function isEmptyObject<Key extends keyof any = string>(value: unknown): value is Record<Key, never>;
function isNonEmptyObject<Key extends keyof any = string, Value = unknown>(value: unknown): value is Record<Key, Value>;
function isEmptyString(value: unknown): value is '';
function isNonEmptyString(value: unknown): value is NonEmptyString;

Collections and Emptiness

Async and Promises

Type checking for promises, async functions, generators, and iterables including both sync and async variants.

function isPromise<T = unknown>(value: unknown): value is Promise<T>;
function isNativePromise<T = unknown>(value: unknown): value is Promise<T>;
function isAsyncFunction<T = unknown>(value: unknown): value is ((...arguments_: any[]) => Promise<T>);
function isAsyncGenerator(value: unknown): value is AsyncGenerator;
function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T>;
function isGenerator(value: unknown): value is Generator;
function isIterable<T = unknown>(value: unknown): value is Iterable<T>;

Async and Promises

Typed Arrays and Binary Data

Type checking for typed arrays, array buffers, and binary data structures including all variants of typed arrays.

function isTypedArray(value: unknown): value is TypedArray;
function isArrayBuffer(value: unknown): value is ArrayBuffer;
function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
function isDataView(value: unknown): value is DataView;
function isInt8Array(value: unknown): value is Int8Array;
function isUint8Array(value: unknown): value is Uint8Array;
function isFloat32Array(value: unknown): value is Float32Array;
function isFloat64Array(value: unknown): value is Float64Array;

Typed Arrays and Binary Data

Numbers and Math

Specialized number validation including integers, safe integers, positive/negative numbers, even/odd checks, and range validation.

function isInteger(value: unknown): value is number;
function isSafeInteger(value: unknown): value is number;
function isPositiveNumber(value: unknown): value is number;
function isNegativeNumber(value: unknown): value is number;
function isEvenInteger(value: unknown): value is number;
function isOddInteger(value: unknown): value is number;
function isInfinite(value: unknown): value is number;
function isInRange(value: number, range: number | [number, number]): value is number;

Numbers and Math

Strings and Text

String-specific validation including empty strings, whitespace detection, numeric strings, URL strings, and text content validation.

function isEmptyString(value: unknown): value is '';
function isEmptyStringOrWhitespace(value: unknown): value is '' | Whitespace;
function isNonEmptyStringAndNotWhitespace(value: unknown): value is NonEmptyString;
function isNumericString(value: unknown): value is `${number}`;
function isUrlString(value: unknown): value is string;
function isWhitespaceString(value: unknown): value is Whitespace;

Strings and Text

Web APIs and DOM

Type checking for web-specific APIs including DOM elements, form data, URL objects, and browser-specific types.

function isHtmlElement(value: unknown): value is HTMLElement;
function isBlob(value: unknown): value is Blob;
function isFormData(value: unknown): value is FormData;
function isUrlInstance(value: unknown): value is URL;
function isUrlSearchParams(value: unknown): value is URLSearchParams;

Web APIs and DOM

Validation and Logic

Multi-value validation, logical operations, and specialized validation patterns including predicate testing and enum checking.

function isAll(predicate: Predicate, ...values: unknown[]): boolean;
function isAny(predicate: Predicate | Predicate[], ...values: unknown[]): boolean;
function isTruthy<T>(value: T | Falsy): value is T;
function isFalsy(value: unknown): value is Falsy;
function isEnumCase<T = unknown>(value: unknown, targetEnum: T): value is T[keyof T];
function isDirectInstanceOf<T>(instance: unknown, class_: Class<T>): instance is T;

Validation and Logic

Assertions

Error-throwing assertion methods corresponding to all type checking functions, with optional custom error messages.

interface Assert {
  string: (value: unknown, message?: string) => asserts value is string;
  number: (value: unknown, message?: string) => asserts value is number;
  array: <T = unknown>(value: unknown, assertion?: (element: unknown) => asserts element is T, message?: string) => asserts value is T[];
  all: (predicate: Predicate, ...values: unknown[]) => void | never;
  any: (predicate: Predicate | Predicate[], ...values: unknown[]) => void | never;
}

const assert: Assert;

Assertions

Types

type TypeName = ObjectTypeName | PrimitiveTypeName;
type AssertionTypeDescription = string;

type Primitive = null | undefined | string | number | boolean | symbol | bigint;
type Class<T, Arguments extends unknown[] = any[]> = Constructor<T, Arguments> & {prototype: T};
type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
type ObservableLike = {
  subscribe(observer: (value: unknown) => void): void;
  [Symbol.observable](): ObservableLike;
};
type Falsy = false | 0 | 0n | '' | null | undefined;
type ArrayLike<T> = {
  readonly [index: number]: T;
  readonly length: number;
};
type NodeStream = {
  pipe<T extends NodeJS.WritableStream>(destination: T, options?: {end?: boolean}): T;
} & NodeJS.EventEmitter;
type Predicate = (value: unknown) => boolean;
type NonEmptyString = string & {0: string};
type Whitespace = ' ';