Skip to content
ECMAScript Proposal, specs, and reference implementation for Promise.prototype.finally
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test [Tests]: Fix “from resolved, rejected-after-a-second” case Jan 28, 2018
.gitattributes Treat spec build output as binary Oct 27, 2017
.gitignore
.npmrc
.travis.yml
LICENSE
README.md Promise.prototype.finally is now stage 4! Jan 24, 2018
index.html Promise.prototype.finally is now stage 4! Jan 24, 2018
package.json [Dev Deps] update `js-beautify` Jan 2, 2018
polyfill.js Tweak spec from "not true" to "false", for clarity. Fixes #44 Jan 2, 2018
spec.css [Dev Deps] update `ecmarkup`, `mocha` Aug 25, 2017
spec.emu
spec.js
spec.md Tweak spec from "not true" to "false", for clarity. Fixes #44 Jan 2, 2018

README.md

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.

You can’t perform that action at this time.