Please support this book: buy it or donate

11. Promise.prototype.finally()

This chapter explains the proposal “Promise.prototype.finally” by Jordan Harband.

11.1. How does it work?

.finally() works as follows:

  1. promise
  2. .then(result => {···})
  3. .catch(error => {···})
  4. .finally(() => {···});

finally’s callback is always executed. Compare:

  • then’s callback is only executed if promise is fulfilled.
  • catch’s callback is only executed if promise is rejected. Or if then’s callback throws an exception or returns a rejected Promise. In other words: Take the following piece of code.
  1. promise
  2. .finally(() => {
  3.     «statements»
  4. });

This piece of code is equivalent to:

  1. promise
  2. .then(
  3.     result => {
  4.         «statements»
  5.         return result;
  6.     },
  7.     error => {
  8.         «statements»
  9.         throw error;
  10.     }
  11. );

11.2. Use case

The most common use case is similar to the most common use case of the synchronous finally clause: cleaning up after you are done with a resource. That should always happen, regardless of whether everything went smoothly or there was an error.

For example:

  1. let connection;
  2. db.open()
  3. .then(conn => {
  4.     connection = conn;
  5.     return connection.select({ name: 'Jane' });
  6. })
  7. .then(result => {
  8.     // Process result
  9.     // Use `connection` to make more queries
  10. })
  11. ···
  12. .catch(error => {
  13.     // handle errors
  14. })
  15. .finally(() => {
  16.     connection.close();
  17. });

11.3. .finally() is similar to finally {} in synchronous code

In synchronous code, the try statement has three parts: The try clause, the catch clause and the finally clause.

In Promises:

  • The try clause very loosely corresponds to invoking a Promise-based function or calling .then().
  • The catch clause corresponds to the .catch() method of Promises.
  • The finally clause corresponds to the new Promise method .finally() introduced by the proposal. However, where finally {} can return and throw, returning has no effect inside the callback .finally(), only throwing. That’s because the method can’t distinguish between the callback returning explicitly and it finishing without doing so.

11.4. Availability

11.5. Further reading