is-promise

library4.0.0jsnpmunverified

is-promise is a minimalist utility that determines if an object adheres to the Promises/A+ specification by duck-typing, specifically checking for the presence and function type of a `then` method. The package is currently at version 4.0.0, which primarily introduced a breaking change for TypeScript users regarding `PromiseLike` inference. While it doesn't follow a strict, rapid release cadence, major versions address significant compatibility updates, particularly concerning module resolution in Node.js environments and TypeScript definitions. Its key differentiator is its small footprint and focused API, providing a reliable and agnostic way to identify promise-like objects, useful in contexts where various promise implementations or thenables might be encountered, without relying on a global `Promise` constructor.

testing

npm install is-promise

github ↗package ↗

INSTALL

IMPORT

SIG · IS-PROMISE

is-promise

testingjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

isPromise

✓ import isPromise from 'is-promise';

✗ import { isPromise } from 'is-promise';

Since v3.0.0, is-promise uses default exports in ES Modules environments. Attempting to use named imports will result in `isPromise is not a function`.

isPromise

✓ const isPromise = require('is-promise');

This is the correct CommonJS `require` pattern, supported across all recent versions.

Demonstrates how to use `isPromise` to check various values, including actual promises, custom thenables, and non-promise types, and correctly handle their resolution.

import isPromise from 'is-promise'; async function processValue(value: unknown): Promise<string> { if (isPromise(value)) { console.log('Value is a promise, awaiting...'); const result = await value; return `Resolved from promise: ${result}`; } else if (typeof value === 'string') { console.log('Value is a string.'); return `Direct string: ${value}`; } else if (typeof value === 'object' && value !== null && 'then' in value && typeof (value as any).then === 'function') { console.log('Value is promise-like (has a then method), awaiting...'); const result = await (value as PromiseLike<any>); return `Resolved from promise-like: ${result}`; } else { console.log('Value is neither a promise nor a string.'); return 'Unknown value type.'; } } (async () => { console.log(await processValue(Promise.resolve('Hello from a real promise'))); console.log(await processValue({ then: (resolve: (arg0: string) => void) => setTimeout(() => resolve('Hello from a custom thenable'), 100) })); console.log(await processValue('Hello from a string')); console.log(await processValue(null)); console.log(await processValue({ then: true })); // 'then' is not a function, so not a promise. })();

Debug

Known issues

breakingFor TypeScript users, `is-promise` v4.0.0 changed its internal type inference from `Promise` to `PromiseLike`. This change correctly reflects that the library checks for any object with a `.then()` method, not strictly instances of the global `Promise` constructor. Type inference in user code might behave differently.

fix

Review TypeScript code that uses `isPromise` to ensure correct type handling, especially in function return types or conditional branches, adjusting types from `Promise<T>` to `PromiseLike<T>` where appropriate.

affects: >=4.0.0

breakingVersion 3.0.0 introduced restricted "exports" in `package.json` for Node 14+ environments. This means that only the public API (the main `isPromise` function) is accessible. Directly requiring or importing internal files, such as the `package.json` file of the package itself, is no longer supported and will result in module not found errors.

fix

Avoid importing or requiring any paths other than the main package entry point (`is-promise`). If you were relying on internal package files, find alternative ways to access that information (e.g., read the main `package.json` of your *own* project).

affects: >=3.0.0

breakingSince v3.0.0, `is-promise` uses default exports in ES Modules environments. If you were previously using named imports (e.g., `import { isPromise } from 'is-promise'`) with earlier ESM-enabled versions, this pattern will no longer work and will cause runtime errors.

fix

Update all ES Module imports to use the default import syntax: `import isPromise from 'is-promise';`.

affects: >=3.0.0

breakingVersions 2.2.0 and 2.2.1 of `is-promise` were officially marked as broken due to issues with their initial attempts at adding ES Module support, which led to incorrect module resolution and other problems. These versions should be avoided.

fix

Do not use `is-promise` versions 2.2.0 or 2.2.1. Upgrade to 2.2.2 or any subsequent stable version (e.g., 3.x or 4.x).

affects: 2.2.0 - 2.2.1

Errors

Common errors & fixes

TypeError: isPromise is not a function

Attempting to use `isPromise` as a named import (e.g., `import { isPromise } from 'is-promise';`) in an ES Module environment.

fix

Change the import statement to use the default export: `import isPromise from 'is-promise';` (applicable for v3.0.0 and above).

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './package.json' is not exported from package 'is-promise'

Trying to `require` or `import` a subpath (like the package's `package.json` file) directly from `is-promise` after v3.0.0, which restricted exports.

fix

Access to internal package files is no longer supported. If you need information from `is-promise`'s `package.json`, consider hardcoding it or finding another way to obtain it that doesn't involve directly accessing its internal file structure.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/then/is-promise ↗

packagehttps://www.npmjs.com/package/is-promise ↗