Core Architectural Concepts

The constructor accepts an executor function where the asynchronous operation is defined. State transitions—fulfillment or rejection—are triggered via the resolve or reject callbacks provided by the environment. Crucially, invoking these callbacks does not immediately terminate the surrounding synchronous code; execution continues until the function scope completes.

const taskA = new Promise((fulfill, deny) => {
  setTimeout(() => deny(new Error('completion failure')), 3000);
});

const taskB = new Promise((fulfill, deny) => {
  setTimeout(() => fulfill(taskA), 1000);
});

taskB
  .then(result => console.log(result))
  .catch(error => console.error(error));

Propagation Rules

When passing another promise instance to resolve, the outer promise inherits its state. If the nested promise eventually rejects, the chain reflects that error. Synchronous errors within the executor are treated as immediate rejections unless wrapped in try-catch which would catch them before rejection happens.

createSyncTask()
  .then(value => console.log(value))
  .catch(err => console.warn(err.message));

const syncDemo = new Promise((res) => {
  res(42);
  console.log('Post-resolve action');
});

Chain Execution Mechanics

The then() method registers observers for successful resolution. Each call returns a distinct promise object, enabling fluent method chaining. Because every invocation creates a new promise, a network of dependencies forms where sibling branches execute concurrently relative to their parent.

const base = new Promise((done) => { done(); })
  .then(() => { console.log('Branch A Start'); })
    .then(() => { console.log('Branch A Sub 1'); });

const alt = new Promise((done) => { done(); })
  .then(() => { console.log('Branch B Start'); });

Order matters when dealing with dependent chains versus parallel ones built off a common ancestor.

Error Handling Strategies

Errors can be caught using the second arguement of then() or the dedicated catch() method. The latter provides syntactic sugar for the rejection callback. To continue processing after a rejection, the handler must explicitly return a value or another fulfilled promise; simply ignoring the error implicitly treats the returned promise as resolved with undefined.

fetchResource()
  .then(data => process(data))
  .catch(exception => {
    console.log('Recovery attempted', exception);
    throw exception;
  });

Exceptions thrown inside asynchronous functions are captured by the resulting promise and do not bubble up to standard try-catch blocks wrapping the promise creation, unless the promise execution was scheduled synchronously.

Cleanup with Finally

Introduced in ES2018, finally() executes regardless of whether the promise settled successfully or failed. It receives no arguments regarding the state and cannot alter the result of the promise chain, primarily serving resource cleanup tasks.

const worker = new WorkerTask();
worker
  .execute()
  .catch(err => console.log(err))
  .finally(() => releaseResources());

Aggregation Patterns

Several static methods facilitate managing multiple promises simultaneously.

All Method

Requires every input promise to settle successfully before the agggregate promise resolves. Failure in any single item causes immediate rejection with the first error encountered.

const results = await Promise.all([
  apiCall('/users'),
  apiCall('/settings')
]);

To capture both successes and failures in an array, individual catches can transform rejections into resolved objects before aggregation.

const safeCalls = [
  p1.catch(err => ({ type: 'error', data: err })),
  p2.catch(err => ({ type: 'error', data: err }))
];

Promise.all(safeCalls).then(console.log);

Race Condition

Returns a promise determined by whichever input settles first, either fulfilling or rejecting. Useful for timeouts or competing requests.

const deadline = Promise.race([
  fetchData(),
  new Promise((_, reject) => setTimeout(() => reject('Timeout'), 5000))
]);

Any Method

Resolves upon the first successful fulfillment. Only rejects if all inputs reject, returning an aggregated list of errors. Distinct from race because it waits for a success condition rather than just any state change.

All Settled Method

Waits for all promises to complete, regardless of status. The output is an array of objects describing status (fulfilled or rejected) and associated values or reasons.

Utility Wrappers

Resolve

Converts existing values into a fulfilled promise state. Passing a promise passes through immediately. Non-promise objects become fulfileld instances instantly.

const immediateValue = Promise.resolve(100);

Reject

Mirrors resolve but initiates a rejection state immediately.

Promise.reject('System halt').catch(e => e);