For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/proposal-promise-finally.md.
TC39 Atlas
  • English

      • Promise.prototype.finally S4

      Proposal details
      Proposal overview

      This proposal adds a finally method to Promise.prototype, allowing a callback to be executed when a promise settles, regardless of fulfillment or rejection. It addresses the need for cleanup operations like hiding spinners or closing handles. The callback receives no arguments and does not alter the resolution value unless it throws or returns a rejected promise.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Promise.prototype.finally

      ECMAScript Proposal, specs, and reference implementation for Promise.prototype.finally

      Spec drafted by @ljharb, following the lead from the cancelable promise proposal.

      Get the polyfill/shim on npm.

      This proposal is currently stage 4 of the process.

      Rationale

      Many promise libraries have a "finally" method, for registering a callback to be invoked when a promise is settled (either fulfilled, or rejected). The essential use case here is cleanup - I want to hide the "loading" spinner on my AJAX request, or I want to close any file handles I’ve opened, or I want to log that an operation has completed regardless of whether it succeeded or not.

      Why not .then(f, f)?

      promise.finally(func) is similar to promise.then(func, func), but is different in a few critical ways:

      • When creating a function inline, you can pass it once, instead of being forced to either declare it twice, or create a variable for it
      • A finally callback will not receive any argument, since there's no reliable means of determining if the promise was fulfilled or rejected. This use case is for precisely when you do not care about the rejection reason, or the fulfillment value, and so there's no need to provide it.
      • Unlike Promise.resolve(2).then(() => {}, () => {}) (which will be resolved with undefined), Promise.resolve(2).finally(() => {}) will be resolved with 2.
      • Similarly, unlike Promise.reject(3).then(() => {}, () => {}) (which will be resolved with undefined), Promise.reject(3).finally(() => {}) will be rejected with 3.

      However, please note: a throw (or returning a rejected promise) in the finally callback will reject the new promise with that rejection reason.

      Naming

      The reasons to stick with finally are straightforward: just like catch, finally would be an analog to the similarly-named syntactic forms from try/catch/finally (try, of course, not really having an analog any closer than Promise.resolve().then). Syntactic finally can only modify the return value with an “abrupt completion”: either throwing an exception, or returning a value early. Promise#finally will not be able to modify the return value, except by creating an abrupt completion by throwing an exception (ie, rejecting the promise) - since there is no way to distinguish between a “normal completion” and an early return undefined, the parallel with syntactic finally must have a slight consistency gap.

      I’d briefly considered always as an alternative, since that wouldn’t imply ordering, but I think the parallels to the syntactic variation are compelling.

      Implementations

      Spec

      You can view the spec in markdown format or rendered as HTML.