Promise.prototype.then()

The then() method of a Promise object takes up to two arguments: callback functions for the fulfilled and rejected cases of the Promise. It immediately returns an equivalent Promise object, allowing you to chain calls to other promise methods.

Syntax

then(onFulfilled)
then(onFulfilled, onRejected)

then(
  (value) => { /* fulfillment handler */ },
  (reason) => { /* rejection handler */ },
)

Parameters

• onFulfilled optional
  • : A Function asynchronously called if the Promise is fulfilled. This function has one parameter, the fulfillment value. If it is not a function, it is internally replaced with an identity function ((x) => x) which simply passes the fulfillment value forward.
• onRejected optional
  • : A Function asynchronously called if the Promise is rejected. This function has one parameter, the rejection reason. If it is not a function, it is internally replaced with a thrower function ((x) => { throw x; }) which throws the rejection reason it received.

Return value

Returns a new Promise immediately. This new promise is always pending when returned, regardless of the current promise's status.

One of the onFulfilled and onRejected handlers will be executed to handle the current promise's fulfillment or rejection. The call always happens asynchronously, even when the current promise is already settled. The behavior of the returned promise (call it p) depends on the handler's execution result, following a specific set of rules. If the handler function:

• returns a value: p gets fulfilled with the returned value as its value.
• doesn't return anything: p gets fulfilled with undefined.
• throws an error: p gets rejected with the thrown error as its value.
• returns an already fulfilled promise: p gets fulfilled with that promise's value as its value.
• returns an already rejected promise: p gets rejected with that promise's value as its value.
• returns another pending promise: the fulfillment/rejection of the promise returned by then will be subsequent to the resolution/rejection of the promise returned by the handler. Also, the resolved value of the promise returned by then will be the same as the resolved value of the promise returned by the handler.

Description

The then() method schedules callback functions for the eventual completion of a Promise — either fulfillment or rejection. It is the primitive method of promises: the thenable protocol expects all promise-like objects to expose a then() method, and the Promise.prototype.catch and Promise.prototype.finally methods both work by invoking the object's then() method.

For more information about the onRejected handler, see the Promise.prototype.catch reference.

then() returns a new promise object. If you call the then() method twice on the same promise object (instead of chaining), then this promise object will have two pairs of settlement handlers. All handlers attached to the same promise object are always called in the order they were added. Moreover, the two promises returned by each call of then() start separate chains and do not wait for each other's settlement.

Thenable objects that arise along the then() chain are always resolved — the onFulfilled handler never receives a thenable object, and any thenable returned by either handler are always resolved before being passed to the next handler. This is because when constructing the new promise, the resolve and reject functions passed by the executor are saved, and when the current promise settles, the respective function will be called with the fulfillment value or rejection reason. The resolving logic comes from the resolver function passed by the Promise() constructor.

then() supports subclassing, which means it can be called on instances of subclasses of Promise, and the result will be a promise of the subclass type. You can customize the type of the return value through the [Symbol.species] property.