Mastering JavaScript Promises: Concepts, Usage, and Common Pitfalls

What is a Promise?

A Promise is an ES6 class that represents the eventual result of an asynchronous operation. It is natively supported in modern browsers (e.g., Safari 10+, Edge 14+).

Typical Use Cases

Perform asynchronous calculations.

Queue asynchronous operations so they execute in a defined order and produce predictable results.

Pass and manipulate promises between objects to coordinate complex workflows.

Key Characteristics

Immutable State

A promise can be in one of three mutually exclusive states, and external code cannot alter the state directly: pending – initial state, neither fulfilled nor rejected. fulfilled – the operation completed successfully. rejected – the operation failed.

When a promise transitions from pending to either fulfilled or rejected, the state is permanent. Any callbacks attached after settlement are invoked immediately with the settled value.

In this summary the term resolved is used synonymously with fulfilled and does not include the rejected state.

Benefits

Promises enable asynchronous code to be written in a linear, synchronous‑like style, eliminating deeply nested callbacks (the “callback hell”) and providing a unified API for chaining and error handling.

Drawbacks

Promises cannot be cancelled; the executor runs as soon as the promise is created.

Errors thrown inside the executor are not automatically propagated unless caught.

While pending, there is no built‑in way to observe progress.

Why Use Promises?

Consider three sequential AJAX calls: first retrieve an ID, then fetch a username using that ID, and finally obtain an email address using the username. Writing this with nested callbacks quickly becomes unreadable. Promises flatten the flow and make error handling straightforward.

Basic Syntax

new Promise((resolve, reject) => {
  // asynchronous work
});

The constructor receives a function with two callbacks: resolve – called when the operation succeeds. reject – called when the operation fails.

Instance Properties

state

– current status ( pending, fulfilled, rejected). result – the value associated with fulfilled or the error associated with rejected.

State Transition Examples

Fulfilled:

const p = new Promise((resolve, reject) => {
  resolve(); // → fulfilled
});
console.dir(p); // shows state: fulfilled

Rejected:

const p = new Promise((resolve, reject) => {
  reject(); // → rejected
});
console.dir(p); // shows state: rejected

then Method

then(onFulfilled, onRejected)

registers callbacks for the two possible outcomes and returns a new promise.

Handling both outcomes:

const p = new Promise((resolve, reject) => {
  reject('failure');
});

p.then(
  () => console.log('success callback'),
  () => console.log('failure callback')
);
console.dir(p);

Accessing the settled value:

p.then(
  value => console.log('success', value),
  err => console.log('failure', err)
);

Returning a value from onFulfilled resolves the promise returned by then to fulfilled. Throwing an error or returning a rejected promise causes the returned promise to become rejected:

const p = new Promise((resolve, reject) => {});
const t = p.then(
  value => {
    console.log('success', value);
    return 123; // t becomes fulfilled with 123
  },
  reason => console.log('failure', reason)
);

t.then(v => console.log('success2', v), r => console.log('failure2'));

catch Method

catch(onRejected)

is shorthand for then(undefined, onRejected). It runs when the promise is rejected or when an error is thrown inside the executor.

const p = new Promise((resolve, reject) => {
  throw new Error('something went wrong');
});

p.catch(reason => {
  console.log('failure', reason);
});
console.dir(p);