or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-promise-prototype-finally

ES specification-compliant polyfill for Promise.prototype.finally method

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/promise.prototype.finally@3.1.x

To install, run

npx @tessl/cli install tessl/npm-promise-prototype-finally@3.1.0

index.mddocs/

Promise.prototype.finally

Promise.prototype.finally provides an ES specification-compliant polyfill/shim for the Promise.prototype.finally method. It enables developers to use the finally method on Promise instances even in environments where it's not natively supported or is noncompliant with the specification.

Package Information

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

Core Imports

const promiseFinally = require('promise.prototype.finally');

Basic Usage

const promiseFinally = require('promise.prototype.finally');

// Use as a standalone function
const resolved = Promise.resolve(42);
const rejected = Promise.reject(-1);

promiseFinally(resolved, function () {
  console.log('This always runs, regardless of promise state');
  // Return value doesn't affect the original promise's value
  return Promise.resolve(true);
}).then(function (x) {
  console.log(x); // 42 - original value preserved
});

// Enable shimming to use as a method
promiseFinally.shim();

resolved.finally(function () {
  console.log('Now you can use .finally() as a method');
});

Architecture

Promise.prototype.finally follows the es-shim API interface pattern:

  • Standalone Function: Can be called directly as promiseFinally(promise, onFinally)
  • Polyfill Detection: Automatically uses native implementation if available and compliant
  • Shimming: Can modify Promise.prototype to add .finally() method
  • Auto-shimming: Optional automatic installation via separate entry point
  • Spec Compliance: Implements the full TC39 Promise.finally proposal specification

Capabilities

Direct Function Call

Call the polyfill directly without modifying Promise.prototype.

/**
 * Execute a handler when a promise settles, regardless of its outcome
 * @param promise - The promise to attach the finally handler to
 * @param onFinally - Function to execute when promise settles (receives no arguments)
 * @returns New promise that preserves the original value or reason
 */
function promiseFinally(promise, onFinally);

Usage Example:

const promiseFinally = require('promise.prototype.finally');

promiseFinally(Promise.resolve(42), function () {
  console.log('Cleanup logic here');
}).then(function (value) {
  console.log(value); // 42
});

Polyfill Detection

Get the appropriate implementation (native or polyfill).

/**
 * Returns native Promise.prototype.finally if available and compliant, otherwise returns implementation
 * @returns The finally function to use
 */
function getPolyfill();

Usage Example:

const promiseFinally = require('promise.prototype.finally');
const finallyFn = promiseFinally.getPolyfill();

Shimming

Install the polyfill on Promise.prototype if needed.

/**
 * Installs the polyfill on Promise.prototype.finally if not present or non-compliant
 * @returns The polyfill function that was installed
 */
function shim();

Usage Example:

const promiseFinally = require('promise.prototype.finally');
promiseFinally.shim(); // Now Promise.prototype.finally is available

Promise.resolve(42).finally(function () {
  console.log('Using as a method now');
});

Auto-shimming

Automatically install the shim when the module is required.

// Auto-shimming module - no exports, just side effects
require('promise.prototype.finally/auto');

Usage Example:

// Just require the auto module
require('promise.prototype.finally/auto');

// Now .finally() is automatically available
Promise.resolve(42).finally(function () {
  console.log('Auto-shimmed!');
});

Core Implementation

The spec-compliant implementation function.

/**
 * The core implementation of Promise.prototype.finally
 * Must be called with a promise as 'this' context
 * @param onFinally - Function to execute when promise settles
 * @returns New promise preserving original value/reason
 */
function implementation(onFinally);

Types

Function Signatures

/**
 * Main export properties - the default export is a function with additional properties
 * @type {Function & {getPolyfill: Function, implementation: Function, shim: Function}}
 */
// promiseFinally(promise, onFinally) - main function
// promiseFinally.getPolyfill() - get polyfill function
// promiseFinally.implementation(onFinally) - core implementation  
// promiseFinally.shim() - install shim function

Behavior Specifications

  • onFinally handler: Called with no arguments regardless of promise state
  • Return value handling: If onFinally returns a promise, waits for it to settle before continuing
  • Value preservation: Original promise's fulfillment value or rejection reason is preserved
  • Error propagation: If onFinally throws or returns a rejected promise, that becomes the new rejection reason
  • Chaining: Returns a new promise that can be further chained

Error Handling

The implementation throws TypeError in these cases:

// When Promise is not available globally (during module loading)
// TypeError: `Promise.prototype.finally` requires a global `Promise` be available.

// When the implementation is called directly on non-object receiver
// TypeError: receiver is not an Object

Environment Requirements

  • ES3+ environment with global Promise constructor available
  • Node.js: >= 0.4
  • Browser: Any modern browser with Promise support
  • Polyfill compatibility: Works with es6-shim and other Promise polyfills