promise-fun

One install for the promise-fun universe: 53 promise utility packages as named ESM exports with full TypeScript types.

• Pure ESM, Node.js >= 22
• Tree-shakeable: import the barrel or a single helper via subpaths
• Typed: upstream types re-exported, never rewritten (attw clean)

Install

npm install promise-fun

Usage

import { pMap, pRetry, pRetryAbortError } from 'promise-fun';

const results = await pMap(urls, fetchWithLimit, { concurrency: 4 });

Prefer a single helper without the barrel? Every package has a subpath that mirrors its upstream API exactly (including the original export names):

import pLimit, { limitFunction } from 'promise-fun/p-limit';
import { promiseStateSync } from 'promise-fun/p-state';

Migrating from v1

// v1 (CommonJS)
// const {pMap} = require('promise-fun');

// v2 (ESM)
import { pMap } from 'promise-fun';

Breaking changes: ESM-only (require() no longer works), Node.js >= 22, the top level has no default export, p-finally was dropped (use native Promise.prototype.finally), and every dependency moved to its current major — see CHANGELOG.md for the full list.

Exports

Top-level keys are the camelCased package names (stable since v1). When an upstream package has named exports, they are forwarded under <camel><Name> (e.g. p-retry's AbortError → pRetryAbortError); a few redundant stems are shortened (p-limit's limitFunction → pLimitFunction) and names that already contain the stem are kept verbatim (pMapSkip). Every upstream type is forwarded the same way (pMapOptions, pRetryOptions, …). The subpath always carries the canonical upstream names.

Main list

| Package | Key | Notes | | -------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | delay | delay | + delayCreate, delayClear, delayRange | | make-synchronous | makeSynchronous | New in v2. Runs async functions synchronously via worker threads; check platform support | | p-all | pAll | Run promise-returning functions concurrently | | p-any | pAny | + pAnyAggregateError | | p-cancelable | pCancelable | + pCancelableCancelError | | p-debounce | pDebounce | Debounce async functions | | p-defer | pDefer | Deferred promise | | p-do-whilst | pDoWhilst | Do…while for promises | | p-each-series | pEachSeries | Iterate promises serially | | p-event | pEvent | Upstream is named-exports-only; + pEventIterator, pEventMultiple, pEventTimeoutError | | p-filter | pFilter | + pFilterIterable | | p-forever | pForever | Run repeatedly until ended | | p-immediate | pImmediate | Resolve on the next tick | | p-is-promise | pIsPromise | Check whether a value is a promise | | p-lazy | pLazy | Lazy promise | | p-limit | pLimit | Concurrency limiter + pLimitFunction | | p-locate | pLocate | First promise satisfying a tester | | p-map | pMap | Map concurrently + pMapIterable, pMapSkip | | p-map-series | pMapSeries | Map serially | | p-memoize | pMemoize | + pMemoizeClear, pMemoizeDecorator | | p-min-delay | pMinDelay | Delay a promise a minimum amount of time | | p-mutex | pMutex | New in v2. Mutual exclusion for async functions | | p-pipe | pPipe | Compose functions into a pipeline | | p-progress | pProgress | New in v2 (it was already listed in the v1 readme but never wired up). + PProgress class | | p-props | pProps | Promise.all for objects and maps + pPropsAllSettled | | p-queue | pQueue | Promise queue + pQueuePriorityQueue, pQueueTimeoutError | | p-race | pRace | A better Promise.race | | p-reduce | pReduce | Reduce with promises | | p-reflect | pReflect | + pReflectIsFulfilled, pReflectIsRejected | | p-retry | pRetry | Retry + pRetryAbortError, pRetryMakeRetriable. Note: the forever option was removed upstream | | p-series | pSeries | Run promise-returning functions in series | | p-settle | pSettle | + pSettleIsFulfilled, pSettleIsRejected | | p-some | pSome | + pSomeFilterError, pSomePEvery | | p-state | pState | New in v2. Named-exports-only upstream: pState is a namespace (pState.promiseStateAsync) + pStateAsync, pStateSync | | p-throttle | pThrottle | Throttle async functions | | p-time | pTime | Measure how long a promise takes | | p-timeout | pTimeout | Timeout with AbortSignal + pTimeoutError | | p-times | pTimes | Run N times concurrently | | p-try | pTry | Promise.try ponyfill | | p-wait-for | pWaitFor | Wait for a condition + pWaitForTimeoutError | | p-waterfall | pWaterfall | Series, each passing its result to the next | | p-whilst | pWhilst | While-loop for promises | | pify | pify | Promisify callback-style functions | | yoctodelay | yoctodelay | New in v2. Tiny delay alternative |

.then/.catch-based packages (generally avoid)

Upstream groups these separately — prefer async/await over chaining helpers:

| Package | Key | | -------------------------------------------------------- | ---------- | | p-break | pBreak | | p-catch-if | pCatchIf | | p-if | pIf | | p-log | pLog | | p-tap | pTap |

Legacy (kept for back-compat)

No longer listed upstream, still shipped here so v1 imports keep working:

| Package | Key | | ---------------------------------------------------------------- | --------------- | | hard-rejection | hardRejection | | loud-rejection | loudRejection | | p-every | pEvery | | p-one | pOne |

Removed in v2: p-finally (deprecated on npm — use native Promise.prototype.finally).

TypeScript

Types come straight from the upstream packages:

import { pMap, type pMapOptions } from 'promise-fun';

const options: pMapOptions = { concurrency: 2 };
await pMap(urls, fetchOne, options);

One exception: p-break@2 ships no types, so this package declares its surface (src/p-break.ts, exported as pBreak / pBreakFunction) from the upstream readme and source.

Requirements

• Node.js >= 22
• ESM (import). CommonJS require() is not supported — a CJS wrapper is impossible since every dependency is ESM-only.

Development

npm install
npm test        # build + vitest (smoke + parity) + type tests
npm run lint    # eslint + prettier
npx publint && npx attw --pack . # attw runs under the esm-only profile (see .attw.json)

The re-export layer is generated: after any dependency bump, run npm run generate:exports and review the diff to src/ and scripts/expected-exports.json. The parity test fails when node_modules drift from the snapshot — that is the signal to regenerate.

License

MIT — see LICENSE.