or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-promise-allsettled

ES Proposal spec-compliant shim for Promise.allSettled

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/promise.allsettled@1.0.x

To install, run

npx @tessl/cli install tessl/npm-promise-allsettled@1.0.0

index.mddocs/

Promise.allSettled

Promise.allSettled is a spec-compliant polyfill/shim for the Promise.allSettled method introduced in ES2020. It provides a consistent implementation across all JavaScript environments that support Promises, allowing developers to wait for all promises in an iterable to settle (either fulfill or reject) and receive detailed information about each promise's outcome.

Package Information

  • Package Name: promise.allsettled
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install promise.allsettled

Core Imports

const allSettled = require("promise.allsettled");

For individual components:

const allSettled = require("promise.allsettled");
const implementation = require("promise.allsettled/implementation");
const getPolyfill = require("promise.allsettled/polyfill");
const shim = require("promise.allsettled/shim");

Auto-shim (automatically patches global Promise if needed):

require("promise.allsettled/auto");

Basic Usage

const allSettled = require("promise.allsettled");

const resolved = Promise.resolve(42);
const rejected = Promise.reject(new Error("failed"));

// Wait for all promises to settle
allSettled([resolved, rejected]).then(function (results) {
  console.log(results);
  // [
  //   { status: 'fulfilled', value: 42 },
  //   { status: 'rejected', reason: Error('failed') }
  // ]
});

// After shimming, use native Promise.allSettled
allSettled.shim();
Promise.allSettled([resolved, rejected]).then(function (results) {
  // Same result format
});

Architecture

Promise.allSettled follows the es-shim API specification:

  • Main Function: Bound implementation that can be used standalone
  • Implementation: Core spec-compliant logic
  • Polyfill: Detection and fallback to native or implementation
  • Shim: Global Promise patching capability
  • Auto-shim: Automatic installation on require

Capabilities

Main Function

The primary export provides Promise.allSettled functionality that works consistently across environments.

/**
 * Returns a promise that resolves after all of the provided promises have settled
 * @param {Iterable} iterable - An iterable of promises or values
 * @returns {Promise<Array<{status: 'fulfilled' | 'rejected', value?: any, reason?: any}>>}
 */
function allSettled(iterable);

Parameters:

  • iterable: Any iterable (array, Set, etc.) containing promises or values

Returns: Promise that resolves to an array of settlement result objects

Result Object Structure:

  • For fulfilled promises: { status: 'fulfilled', value: <resolved-value> }
  • For rejected promises: { status: 'rejected', reason: <rejection-reason> }

Usage Example:

const allSettled = require("promise.allsettled");

const promises = [
  Promise.resolve("success"),
  Promise.reject(new Error("failure")),
  Promise.resolve(123),
  "not a promise" // Non-promise values are treated as resolved
];

allSettled(promises).then(results => {
  results.forEach((result, index) => {
    if (result.status === 'fulfilled') {
      console.log(`Promise ${index} resolved with:`, result.value);
    } else {
      console.log(`Promise ${index} rejected with:`, result.reason);
    }
  });
});

Implementation Function

The core spec-compliant implementation that requires explicit Promise constructor binding.

/**
 * Core implementation of Promise.allSettled
 * @param {Iterable} iterable - An iterable of promises or values
 * @returns {Promise<Array<{status: 'fulfilled' | 'rejected', value?: any, reason?: any}>>}
 */
allSettled.implementation(iterable);

Usage:

const implementation = require("promise.allsettled/implementation");

// Must be called with Promise constructor as 'this'
const result = implementation.call(Promise, [Promise.resolve(1), Promise.reject(2)]);

Polyfill Detection

Returns the appropriate Promise.allSettled function (native if available and compliant, otherwise the implementation).

/**
 * Returns native Promise.allSettled if available and compliant, otherwise returns implementation
 * @returns {Function} The appropriate Promise.allSettled function
 */
allSettled.getPolyfill();

Usage:

const getPolyfill = require("promise.allsettled/polyfill");

const polyfill = getPolyfill();
// Use polyfill.call(Promise, iterable) or as Promise.allSettled replacement

Global Shim

Patches the global Promise.allSettled if it's missing or non-compliant.

/**
 * Installs Promise.allSettled on the global Promise if needed
 * @returns {Function} The polyfill function that was installed
 */
allSettled.shim();

Usage:

const allSettled = require("promise.allsettled");

allSettled.shim(); // Now Promise.allSettled is available globally

// Use native Promise.allSettled
Promise.allSettled([Promise.resolve(1), Promise.reject(2)])
  .then(console.log);

Auto-Shimming

Automatically applies the shim when the module is required.

// Auto-shim module - no exports, side-effects only
require("promise.allsettled/auto");

Usage:

// Simply require to automatically install the shim
require("promise.allsettled/auto");

// Promise.allSettled is now available globally
Promise.allSettled([Promise.resolve(1)])
  .then(console.log); // [{ status: 'fulfilled', value: 1 }]

Error Handling

The library handles various error conditions:

  • Missing Promise Constructor: Throws TypeError if global Promise is not available
  • Invalid This Context: Implementation throws TypeError if this is not an object when called directly
  • Promise Rejections: Individual promise rejections are captured in result objects, not thrown
const allSettled = require("promise.allsettled");

// This will not throw, even though one promise rejects
allSettled([
  Promise.resolve("ok"),
  Promise.reject(new Error("error"))
]).then(results => {
  // Both results are captured in the array
  console.log(results[0]); // { status: 'fulfilled', value: 'ok' }
  console.log(results[1]); // { status: 'rejected', reason: Error('error') }
});

Environment Requirements

  • JavaScript Engine: ES3+ compatible
  • Global Promise: Must have a global Promise constructor available
  • Polyfill Compatibility: Works with Promise polyfills like es6-shim

Spec Compliance

This implementation follows the TC39 Promise.allSettled proposal and is fully spec-compliant with the finalized ES2020 specification.