Creating a Promise, Chaining & Error Handling

In modern asynchronous JavaScript, Promises serve as the foundational architecture for managing non-blocking operations without descending into callback hell. While consuming promises via APIs like fetch() is common, building robust systems requires understanding how to produce custom promises, chain sequential asynchronous tasks cleanly, and strategically handle runtime exceptions.

1. The Producer-Consumer Architecture in Promises

Asynchronous programming with Promises is divided into two distinct responsibilities: producing the asynchronous task and consuming its eventual resolution or failure.

The E-Commerce Workflow Model

To understand this lifecycle, consider a standard e-commerce purchase flow:

1. createOrder(cart) takes cart items and produces an orderId asynchronously.
2. proceedToPayment(orderId) accepts the orderId and conducts the transaction.
3. showOrderSummary(paymentInfo) renders transaction details.
4. updateWalletBalance(paymentInfo) reconciles customer balances.

The consumer invokes these operations, while the producer encapsulates the underlying database interactions, network requests, validation logic, and state mutations.

2. Anatomy of the Promise Constructor (new Promise)

A Promise is instantiated using the built-in Promise constructor, which accepts an executor function. JavaScript immediately invokes this executor function synchronously, passing two built-in engine-level callbacks: resolve and reject.

const promise = new Promise(function (resolve, reject) {
  // Asynchronous or synchronous execution logic
});

Key Guarantees of the Executor Function:

• resolve(data): Invoked when the operation succeeds. It transitions the promise's internal state from pending to fulfilled and sets its internal PromiseResult to data.
• reject(error): Invoked when the operation fails or encounters invalid state. It transitions the promise from pending to rejected and sets its PromiseResult to the provided error.
• Immutability Guarantee: A promise can resolve or reject only once. Subsequent invocations of resolve or reject within the same executor are silently ignored.

Note: The resolve and reject functions are provided directly by the JavaScript runtime environment. Developers do not implement them; they only invoke them to dictate the lifecycle of the Promise.

3. Building a Custom Promise Producer (createOrder)

When developing custom asynchronous services, the producer function must instantiate a Promise, perform necessary validations and asynchronous business logic, and return that promise object to the caller.

// Producer: createOrder API
function createOrder(cart) {
  const pr = new Promise(function (resolve, reject) {
    // 1. Validate the cart payload
    if (!validateCart(cart)) {
      const err = new Error("Cart is not valid");
      reject(err);
      return;
    }

    // 2. Mocking DB Call / Asynchronous Order Creation
    const orderId = "ORD_12345";
    if (orderId) {
      // Simulate network/database latency of 5000ms
      setTimeout(function () {
        resolve(orderId);
      }, 5000);
    }
  });

  return pr;
}

// Mock validation helper
function validateCart(cart) {
  return cart && cart.length > 0;
}

Step-by-Step Producer Execution Flow:

4. Consuming Custom Promises & Graceful Error Handling (.catch())

When a promise is returned to the consumer, callback functions are attached to it using .then() for fulfillment and .catch() for rejection.

Naive Handling (Uncaught Exceptions)

If a promise rejects and the consumer fails to attach a rejection handler, the JavaScript runtime emits an uncaught promise rejection error in the browser console:

const cart = ["shoes", "pants", "kurta"];

// If validateCart returns false, this causes an Uncaught Exception in the console
createOrder(cart)
  .then(function (orderId) {
    console.log("Order created successfully with ID:", orderId);
  });

Graceful Error Handling

To prevent application crashes and maintain control over the user experience, always attach a .catch() block to capture rejected promises:

const cart = ["shoes", "pants", "kurta"];

createOrder(cart)
  .then(function (orderId) {
    console.log("Order created successfully with ID:", orderId);
  })
  .catch(function (err) {
    // Gracefully logs: "Cart is not valid" without throwing uncaught console errors
    console.log(err.message);
  });

Important Terminology: In traditional asynchronous patterns, callbacks are passed in as arguments to other functions (inversion of control). With promises, handlers are attached to the returned promise object (promise.then(callback)), keeping execution control within the calling scope.

5. Simulating Asynchronous Delays and Lifecycle States

A Promise exists in one of three mutually exclusive states:

1. pending: Initial state; the operation is still executing.
2. fulfilled: The operation completed successfully (resolve() was called).
3. rejected: The operation failed (reject() was called).

Visualizing the State Transition in Real Time

const cart = ["shoes", "pants", "kurta"];

const userPromise = createOrder(cart);

// Synchronously logged immediately after creation
console.log(userPromise); // Output: Promise { <pending> }

userPromise
  .then(function (orderId) {
    console.log("Resolved Order ID:", orderId);
    console.log(userPromise); // Output: Promise { <fulfilled>: "ORD_12345" }
  })
  .catch(function (err) {
    console.log("Rejected Error:", err.message);
    console.log(userPromise); // Output: Promise { <rejected>: Error }
  });

Lifecycle Timeline (5-Second Asynchronous Operation):

6. Promise Chaining Mechanics: Linearizing Async Sequences

When multiple asynchronous operations must execute sequentially (e.g., creating an order, then processing payment, then summarizing), nested callbacks cause code to grow horizontally (the "Pyramid of Doom"). Promise Chaining flattens this structure into a vertical pipeline.

Implementing Sequential Producers

function createOrder(cart) {
  return new Promise(function (resolve, reject) {
    if (!validateCart(cart)) {
      reject(new Error("Cart is not valid"));
      return;
    }
    const orderId = "ORD_12345";
    setTimeout(() => resolve(orderId), 2000);
  });
}

function proceedToPayment(orderId) {
  return new Promise(function (resolve, reject) {
    if (!orderId) {
      reject(new Error("Invalid Order ID"));
      return;
    }
    // Simulate payment processing
    setTimeout(() => resolve("Payment Successful for " + orderId), 2000);
  });
}

The Chained Consumer Pipeline

const cart = ["shoes", "pants", "kurta"];

createOrder(cart)
  .then(function (orderId) {
    console.log("Step 1 Complete:", orderId);
    return orderId;
  })
  .then(function (orderId) {
    return proceedToPayment(orderId); // Returning a new Promise into the chain
  })
  .then(function (paymentInfo) {
    console.log("Step 2 Complete:", paymentInfo);
  })
  .catch(function (err) {
    console.error("Pipeline Failed:", err.message);
  });

7. The Critical Rule of Promise Chaining: The return Keyword

The most common bug in promise chaining is forgetting to return a value or promise from inside a .then() handler.

The Pitfall Illustrated

// INCORRECT: Missing return keyword
createOrder(cart)
  .then(function (orderId) {
    proceedToPayment(orderId); // Promise created but NOT returned
  })
  .then(function (paymentInfo) {
    // paymentInfo will be undefined because nothing was returned above!
    console.log(paymentInfo); // Logs: undefined
  });

// CORRECT: Explicit return
createOrder(cart)
  .then(function (orderId) {
    return proceedToPayment(orderId); // Handed off down the chain
  })
  .then(function (paymentInfo) {
    console.log(paymentInfo); // Logs: "Payment Successful for ORD_12345"
  });

What Can Be Returned from a .then() Callback?

1. A Primitive / Object Value: Automatically wrapped in a resolved promise and forwarded to the next .then(val).
2. A New Promise: The chain pauses until this promise resolves or rejects, forwarding its resolved payload to the next .then(data).
3. Nothing (omitted return): Implicitly returns undefined, which becomes the argument for the next .then(undefined).

8. Error Propagation and Strategic .catch() Placement

In a Promise chain, errors bubble down until they encounter the first available .catch() block. By shifting where .catch() is placed, you control whether an error halts the entire pipeline or is recovered from locally.

Scenario A: Generic Catch at the End of the Chain

A .catch() at the bottom handles failures from any step above it. If step 1 fails, all subsequent .then() steps are skipped.

createOrder(cart)
  .then(orderId => proceedToPayment(orderId))
  .then(paymentInfo => showOrderSummary(paymentInfo))
  .then(summary => updateWalletBalance(summary))
  .catch(err => console.log("Handles any error across all 4 steps:", err.message));

Scenario B: Inline Catch for Intermediate Recovery

A .catch() block catches errors occurring only in the steps above it. Any .then() attached after the .catch() will execute regardless of earlier errors.

createOrder(cart)
  .then(function (orderId) {
    console.log("Order Created:", orderId);
    return proceedToPayment(orderId);
  })
  .catch(function (err) {
    // Catches errors ONLY from createOrder or proceedToPayment
    console.log("Early Step Failed:", err.message);
    return "Fallback_Payment_Info"; // Recovers and continues chain
  })
  .then(function (paymentInfo) {
    // This step WILL ALWAYS RUN, even if createOrder failed above
    console.log("Continuation Step:", paymentInfo);
  })
  .catch(function (err) {
    console.log("Generic catch for errors occurring in continuation step");
  });

9. Comprehensive Comparison: Promise Handling Strategies

10. End-to-End Workflow & Homework Implementation Guide

Here is the complete reference implementation demonstrating the 4-step e-commerce pipeline with custom promise producers, flattened chaining, return statements, and error handling.

The 4 Asynchronous Producers

const cart = ["shoes", "pants", "kurta"];

function createOrder(cart) {
  return new Promise((resolve, reject) => {
    if (!cart || cart.length === 0) {
      reject(new Error("Cart is empty or invalid"));
      return;
    }
    const orderId = "ORD_998877";
    setTimeout(() => resolve(orderId), 1000);
  });
}

function proceedToPayment(orderId) {
  return new Promise((resolve, reject) => {
    if (!orderId) {
      reject(new Error("No valid Order ID provided"));
      return;
    }
    const paymentInfo = { status: "SUCCESS", txnId: "TXN_554433", orderId: orderId };
    setTimeout(() => resolve(paymentInfo), 1000);
  });
}

function showOrderSummary(paymentInfo) {
  return new Promise((resolve, reject) => {
    if (!paymentInfo || paymentInfo.status !== "SUCCESS") {
      reject(new Error("Payment validation failed"));
      return;
    }
    const summary = { orderId: paymentInfo.orderId, totalAmount: 4500 };
    setTimeout(() => resolve(summary), 1000);
  });
}

function updateWalletBalance(summary) {
  return new Promise((resolve, reject) => {
    if (!summary || !summary.totalAmount) {
      reject(new Error("Cannot calculate wallet deduction"));
      return;
    }
    const balance = { previousBalance: 10000, newBalance: 10000 - summary.totalAmount };
    setTimeout(() => resolve(balance), 1000);
  });
}

The Unified Consumer Chain

createOrder(cart)
  .then(function (orderId) {
    console.log("Step 1: Order Created ->", orderId);
    return proceedToPayment(orderId);
  })
  .then(function (paymentInfo) {
    console.log("Step 2: Payment Processed ->", paymentInfo.txnId);
    return showOrderSummary(paymentInfo);
  })
  .then(function (summary) {
    console.log("Step 3: Summary Generated -> Total:", summary.totalAmount);
    return updateWalletBalance(summary);
  })
  .then(function (balance) {
    console.log("Step 4: Wallet Updated -> New Balance:", balance.newBalance);
  })
  .catch(function (err) {
    console.error("Order Processing Pipeline Terminated:", err.message);
  });

Summary and Key Takeaways

• Producer vs. Consumer: The producer instantiates and returns a new Promise((resolve, reject) => ...), while the consumer attaches reactions using .then() and .catch().
• Constructor Mechanism: The Promise constructor takes an executor function that receives runtime-injected resolve and reject functions.
• State Immutability: A promise can resolve or reject only once. Once transitioned from pending to fulfilled or rejected, its state cannot change.
• Graceful Error Handling: Always attach a .catch() block to promise consumers to prevent uncaught promise rejection errors in production environments.
• The Chaining Rule: Always use the return statement inside .then() callbacks to pass values or nested promises down the chain. Omitting return results in undefined values in subsequent steps.
• Flattening Async Pipelines: Returning a promise from inside a .then() handler flattens the execution flow and prevents Promise Hell / Pyramids of Doom.
• Error Bubbling: Errors bubble down to the nearest .catch(). Any .then() handlers placed after a .catch() will still execute, allowing for targeted error recovery in long chains.