tessl/npm-sindresorhus--is

Type check values with comprehensive TypeScript type guards and runtime assertions

—

Pending

Overview

Eval results

Files

Async and Promises

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

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

Capabilities

Promise Type Checking

Check if a value is a promise-like object or native Promise.

/**
 * Check if value is promise-like (has .then() and .catch() methods)
 * @param value - Value to check
 * @returns True if value is promise-like
 */
function isPromise<T = unknown>(value: unknown): value is Promise<T>;

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

Usage Examples:

import is from '@sindresorhus/is';

is.promise(Promise.resolve(42)); // => true
is.promise(new Promise(() => {})); // => true

// Promise-like objects
const thenable = {
  then: (resolve: Function) => resolve(42),
  catch: (reject: Function) => {}
};
is.promise(thenable); // => true

// Native Promise checking
is.nativePromise(Promise.resolve(42)); // => true
is.nativePromise(thenable); // => false

// Type guard usage
async function handlePromise(value: unknown) {
  if (is.promise(value)) {
    // value is now typed as Promise<unknown>
    const result = await value;
    console.log(result);
  }
}

Async Function Type Checking

Check if a value is an async function.

/**
 * Check if value is an async function
 * @param value - Value to check
 * @returns True if value is async function
 */
function isAsyncFunction<T = unknown>(value: unknown): value is ((...arguments_: any[]) => Promise<T>);

Usage Examples:

import is from '@sindresorhus/is';

is.asyncFunction(async () => {}); // => true
is.asyncFunction(async function() {}); // => true
is.asyncFunction(() => {}); // => false
is.asyncFunction(function() {}); // => false

// Type guard usage
async function executeAsync(fn: unknown) {
  if (is.asyncFunction(fn)) {
    // fn is now typed as async function
    const result = await fn();
    console.log(result);
  }
}

Generator Type Checking

Check if a value is a generator object.

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

Usage Examples:

import is from '@sindresorhus/is';

function* myGenerator() {
  yield 1;
  yield 2;
}

const gen = myGenerator();
is.generator(gen); // => true
is.generator(myGenerator); // => false (function, not generator instance)

// Type guard usage
function processGenerator(value: unknown) {
  if (is.generator(value)) {
    // value is now typed as Generator
    const { value: firstValue, done } = value.next();
    console.log(firstValue, done);
  }
}

Generator Function Type Checking

Check if a value is a generator function.

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

Usage Examples:

import is from '@sindresorhus/is';

function* myGenerator() {
  yield 1;
}

is.generatorFunction(myGenerator); // => true
is.generatorFunction(myGenerator()); // => false (generator instance)
is.generatorFunction(() => {}); // => false

// Type guard usage
function createGenerator(fn: unknown) {
  if (is.generatorFunction(fn)) {
    // fn is now typed as GeneratorFunction
    const generator = fn();
    return generator;
  }
}

Async Generator Type Checking

Check if a value is an async generator object.

/**
 * Check if value is an async generator
 * @param value - Value to check
 * @returns True if value is async generator
 */
function isAsyncGenerator(value: unknown): value is AsyncGenerator;

Usage Examples:

import is from '@sindresorhus/is';

async function* myAsyncGenerator() {
  yield 1;
  yield 2;
}

const asyncGen = myAsyncGenerator();
is.asyncGenerator(asyncGen); // => true

// Regular generator is not async generator
function* regularGen() { yield 1; }
is.asyncGenerator(regularGen()); // => false

// Type guard usage
async function processAsyncGenerator(value: unknown) {
  if (is.asyncGenerator(value)) {
    // value is now typed as AsyncGenerator
    const { value: firstValue, done } = await value.next();
    console.log(firstValue, done);
  }
}

Async Generator Function Type Checking

Check if a value is an async generator function.

/**
 * Check if value is an async generator function
 * @param value - Value to check
 * @returns True if value is async generator function
 */
function isAsyncGeneratorFunction(value: unknown): value is AsyncGeneratorFunction;

Usage Examples:

import is from '@sindresorhus/is';

async function* myAsyncGenerator() {
  yield 1;
}

is.asyncGeneratorFunction(myAsyncGenerator); // => true
is.asyncGeneratorFunction(myAsyncGenerator()); // => false (async generator instance)

function* regularGenerator() { yield 1; }
is.asyncGeneratorFunction(regularGenerator); // => false

// Type guard usage
function createAsyncGenerator(fn: unknown) {
  if (is.asyncGeneratorFunction(fn)) {
    // fn is now typed as AsyncGeneratorFunction
    const asyncGenerator = fn();
    return asyncGenerator;
  }
}

Iterable Type Checking

Check if a value is iterable (has Symbol.iterator).

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

Usage Examples:

import is from '@sindresorhus/is';

is.iterable([]); // => true
is.iterable('hello'); // => true
is.iterable(new Set()); // => true
is.iterable(new Map()); // => true
is.iterable({}); // => false

function* generator() { yield 1; }
is.iterable(generator()); // => true

// Type guard usage
function processIterable(value: unknown) {
  if (is.iterable(value)) {
    // value is now typed as Iterable<unknown>
    for (const item of value) {
      console.log(item);
    }
  }
}

Async Iterable Type Checking

Check if a value is async iterable (has Symbol.asyncIterator).

/**
 * Check if value is async iterable
 * @param value - Value to check
 * @returns True if value is async iterable
 */
function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T>;

Usage Examples:

import is from '@sindresorhus/is';

async function* asyncGenerator() {
  yield 1;
  yield 2;
}

is.asyncIterable(asyncGenerator()); // => true
is.asyncIterable([]); // => false (regular arrays are not async iterable)

// Custom async iterable
const customAsyncIterable = {
  async *[Symbol.asyncIterator]() {
    yield 1;
    yield 2;
  }
};
is.asyncIterable(customAsyncIterable); // => true

// Type guard usage
async function processAsyncIterable(value: unknown) {
  if (is.asyncIterable(value)) {
    // value is now typed as AsyncIterable<unknown>
    for await (const item of value) {
      console.log(item);
    }
  }
}

Observable Type Checking

Check if a value is an Observable-like object.

/**
 * Check if value is Observable-like
 * @param value - Value to check
 * @returns True if value is Observable-like
 */
function isObservable(value: unknown): value is ObservableLike;

type ObservableLike = {
  subscribe(observer: (value: unknown) => void): void;
  [Symbol.observable](): ObservableLike;
};

Usage Examples:

import is from '@sindresorhus/is';
import { Observable } from 'rxjs';

const observable = new Observable(subscriber => {
  subscriber.next(1);
  subscriber.complete();
});

is.observable(observable); // => true

// Custom observable-like
const customObservable = {
  subscribe: (observer: Function) => observer(42),
  [Symbol.observable]: function() { return this; }
};
is.observable(customObservable); // => true

is.observable(Promise.resolve(42)); // => false

// Type guard usage
function processObservable(value: unknown) {
  if (is.observable(value)) {
    // value is now typed as ObservableLike
    value.subscribe(result => console.log(result));
  }
}

Usage Patterns

Promise Handling

import is from '@sindresorhus/is';

async function handleAsyncValue(value: unknown) {
  if (is.promise(value)) {
    const result = await value;
    console.log('Promise resolved:', result);
  } else if (is.asyncFunction(value)) {
    const result = await value();
    console.log('Async function result:', result);
  }
}

Generator Processing

import is from '@sindresorhus/is';

function processGeneratorValue(value: unknown) {
  if (is.generator(value)) {
    // Process regular generator
    let result = value.next();
    while (!result.done) {
      console.log(result.value);
      result = value.next();
    }
  } else if (is.asyncGenerator(value)) {
    // Process async generator
    processAsyncGenerator(value);
  }
}

async function processAsyncGenerator(gen: AsyncGenerator) {
  let result = await gen.next();
  while (!result.done) {
    console.log(result.value);
    result = await gen.next();
  }
}

Notes

is.promise() accepts both native Promises and thenable objects (with .then() and .catch())
Use is.nativePromise() when you specifically need native Promise instances
Generators and generator functions are different - one creates the other
Async generators require for await...of loops or manual await gen.next() calls
Observable checking looks for Symbol.observable or @@observable properties
All async type checks work with TypeScript type guards for compile-time type narrowing