System Design (LLD)Concurrency Patterns

Future and Promise Pattern

LevelIntermediate

Duration60 mins

TopicConcurrency Patterns

2 / 4

Solution: Future/Promise Abstraction

The Elegant Abstraction

In the previous page, we dissected the painful reality of asynchronous result handling: blocking wastes threads, polling wastes cycles, and callbacks create unmaintainable spaghetti code. Now we introduce an abstraction so elegant that it has been independently invented in dozens of programming languages and has become the foundational model for async programming in modern systems.

The core insight is deceptively simple:

An asynchronous computation produces a value that doesn't exist yet, but will exist. Instead of waiting for that value or providing callbacks, we represent the pending value itself as an object.

This object—called a Future, Promise, Task, or Deferred depending on the language—is a container for a value that will be computed in the future. You can pass this container around, chain operations on it, handle its potential failure, and compose multiple containers together—all before the value actually exists.

What You Will Learn

By the end of this page, you will understand the Future/Promise abstraction at a deep level: the distinction between Future and Promise, the three states of a Promise, the mental model of 'eventual values', and how this single abstraction elegantly addresses every problem we identified—thread waste, polling overhead, callback hell, error fragmentation, and composition difficulty.

The Conceptual Model: Eventual Values

To understand Future/Promise, we need to shift our mental model of computation. In synchronous programming, a function call produces a value immediately:

value = computeResult()  // value exists now
process(value)            // use it now

In asynchronous programming with Future/Promise, a function call produces a container for a value that will be filled in later:

futureValue = computeResultAsync()  // container exists now, value inside: pending
// The container will eventually hold the result OR an error
process(futureValue)                 // chain operations on the container

The key shift: Instead of thinking 'this function will eventually give me a value,' think 'this function immediately gives me a box that will contain a value.'

Converting Mermaid diagram...

The Three States of a Promise:

Every Promise/Future exists in exactly one of three states:

Pending: The async operation is still in progress. The eventual value is unknown.
Fulfilled (Resolved): The operation completed successfully. The value is available.
Rejected: The operation failed. An error is available.

State transitions are one-way and irreversible:

A Promise can transition from Pending → Fulfilled (exactly once)
A Promise can transition from Pending → Rejected (exactly once)
Once Fulfilled or Rejected, a Promise never changes state again

This immutability is crucial: once a Promise settles, its value or error is locked in forever. Any code that receives that Promise will always see the same result, enabling safe sharing and caching.

The Container Metaphor

Think of a Promise as a gift box at a birthday party. The box exists immediately (Pending). Eventually, it will be opened to reveal either a gift (Fulfilled) or an embarrassing empty box (Rejected). Anyone who receives the box can plan what to do with the gift before knowing what's inside—they just describe their intentions, and those intentions execute when the box is opened.

Future vs Promise: The Dual Object Model

In many implementations, the 'async result container' concept is split into two related objects with distinct roles:

Promise (or Deferred, CompletableFuture, TaskCompletionSource):

The write side of the async result
Has methods to complete the result: resolve(value) or reject(error)
Typically held privately by the code that performs the async operation

Future (or Promise in JS, Task in C#):

The read side of the async result
Has methods to observe the result: then(), catch(), await
Returned to callers who want to use the result

This separation enforces a crucial invariant: only the producer can set the result; consumers can only observe it.

dual-object-model
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
import java.util.concurrent.CompletableFuture;
 
public class FuturePromiseExample {
    
    // The producer: creates and controls the CompletableFuture
    public CompletableFuture<String> fetchUserNameAsync(long userId) {
        // CompletableFuture is both Future (read) and Promise (write)
        CompletableFuture<String> future = new CompletableFuture<>();
        
        // Simulate async work in a background thread
        new Thread(() -> {
            try {
                // Simulate network latency
                Thread.sleep(500);
                
                // Producer completes the future with a value
                String userName = database.getUserName(userId);
                future.complete(userName);  // WRITE SIDE: resolve with value
                
            } catch (Exception e) {
                // Producer completes the future with an error
                future.completeExceptionally(e);  // WRITE SIDE: reject with error
            }
        }).start();
        
        // Return the future immediately - caller doesn't wait
        return future;
    }
    
    // The consumer: only has read access via CompletableFuture<T>
    public void displayUserName(long userId) {
        CompletableFuture<String> userNameFuture = fetchUserNameAsync(userId);
        
        // Consumer chains operations - READ SIDE only
        userNameFuture
            .thenAccept(name -> System.out.println("User: " + name))  // on success
            .exceptionally(error -> {
                System.err.println("Error: " + error.getMessage());
                return null;
            });
        
        // Consumer cannot call .complete() or .completeExceptionally()
        // The separation ensures only the producer controls the result
        
        System.out.println("Request initiated, continuing other work...");
    }
}

Future vs Promise Terminology Across Languages
Language	Read Side (Consumer)	Write Side (Producer)	Common Pattern
Java	CompletableFuture<T>	CompletableFuture<T>	Same object, but convention separates usage
JavaScript/TypeScript	Promise<T>	resolve/reject in executor	Write side only in constructor
C#	Task<T>	TaskCompletionSource<T>	Explicit separation
Python	asyncio.Future	loop.create_future()	Future is writable; wrapped for safety
Scala	Future[T]	Promise[T]	Explicit: Promise produces Future
Rust	impl Future	Pin<Box<...>>	Compiler enforces via ownership

Why Separation Matters

The producer/consumer separation prevents bugs where consumer code accidentally (or maliciously) resolves a Future before the actual async operation completes. It's an example of the principle of least privilege: give each piece of code only the capabilities it needs.

How Future/Promise Solves Each Problem

In our problem analysis, we identified seven requirements for an ideal async result handling solution. Let's see how Future/Promise addresses each one systematically.

Requirements Satisfied by Future/Promise
Requirement	How Future/Promise Addresses It
Non-blocking	Futures return immediately. The calling thread continues executing other code while the async operation runs. No thread is blocked waiting for results.
Push-based notification	Callbacks registered via `.then()` are invoked immediately when the Future resolves—no polling, no wasted checks, instant notification.
First-class representation	A Future IS a value. It can be stored in variables, passed to functions, returned from functions, stored in collections, and serialized.
Composable	`.then()` chains sequential operations. `Promise.all()` handles parallel operations. `Promise.race()` handles competition. Composition is built-in.
Unified error handling	Errors propagate through chains automatically. A single `.catch()` at the end handles errors from any step in the chain.
Readable, linear code	With `async/await` syntax, code reads top-to-bottom like synchronous code while remaining non-blocking underneath.
Cancelable	AbortController, CancellationToken, or similar patterns integrate with Futures to cancel pending operations.
Testable	Futures can be pre-resolved in tests. No complex async setup—just `Promise.resolve(mockValue)` or `CompletableFuture.completedFuture(mock)`.

Let's see this transformation in action. Remember our order processing example with horrific callback nesting? Here's the same logic with Futures:

callback-to-promise
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// BEFORE: Callback Hell (from previous page)
/*
function processOrder(order, onComplete, onError) {
    paymentGateway.processPayment(order.paymentInfo, 
        (paymentError, paymentResult) => {
            if (paymentError) { onError(...); return; }
            inventoryService.reserveItems(order.items,
                (inventoryError, inventoryResult) => {
                    if (inventoryError) { 
                        paymentGateway.refund(..., () => { onError(...); }); 
                        return; 
                    }
                    shippingService.scheduleDelivery(...,
                        (shippingError, shippingResult) => {
                            // ... even more nesting
                        }
                    );
                }
            );
        }
    );
}
*/
 
// AFTER: Promise-based (linear, composable, readable)
async function processOrder(order: Order): Promise<OrderResult> {
    // Sequential operations read top-to-bottom
    const payment = await paymentGateway.processPayment(order.paymentInfo);
    
    try {
        const inventory = await inventoryService.reserveItems(order.items);
        
        try {
            const shipping = await shippingService.scheduleDelivery(
                order.shippingAddress,
                order.items
            );
            
            // Notification failure shouldn't fail the order
            await notificationService
                .sendConfirmation(order.customerEmail, shipping.trackingNumber)
                .catch(err => logger.warn('Notification failed', err));
            
            return OrderResult.success(shipping.trackingNumber);
            
        } catch (shippingError) {
            // Rollback inventory on shipping failure
            await inventoryService.releaseItems(inventory.reservationId);
            throw shippingError;
        }
        
    } catch (inventoryOrShippingError) {
        // Rollback payment on any downstream failure
        await paymentGateway.refund(payment.transactionId);
        throw inventoryOrShippingError;
    }
}
 
// Compare: 60 lines of nested callbacks → 30 lines of linear code
// Error handling is clear and scoped
// Control flow matches mental model

The Transformation

The Promise-based version isn't just shorter—it's fundamentally more maintainable. Error handling is explicit and scoped. The flow reads linearly. You can trace execution by reading top-to-bottom. Testing requires no callback mocking—just mock the service methods to return pre-resolved Promises.

The Core API: then, catch, finally

Every Future/Promise implementation provides a core set of operations for transforming and handling async results. Understanding these operations deeply is essential for effective async programming.

The fundamental operations:

Purpose: Transform the resolved value of a Promise.

Semantics: Takes a function that receives the resolved value and returns either:

A new value (Promise auto-wraps it)
A new Promise (Promise chains/unwraps it)

Key insight: .then() always returns a new Promise, never mutates the original. This immutability enables safe sharing and composition.

then-examples
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// .then() transforms the resolved value
const userPromise = fetchUser(userId);
 
// Transform to just the name (value → value)
const namePromise: Promise<string> = userPromise.then(user => user.name);
 
// Transform to another async operation (value → Promise)
const ordersPromise: Promise<Order[]> = userPromise
    .then(user => fetchOrders(user.id));  // Returns Promise<Order[]>
    // Promise automatically "unwraps" - no Promise<Promise<Order[]>>
 
// Chaining multiple transformations
const totalSpent: Promise<number> = fetchUser(userId)
    .then(user => fetchOrders(user.id))           // User → Order[]
    .then(orders => orders.map(o => o.total))     // Order[] → number[]
    .then(totals => totals.reduce((a, b) => a + b, 0)); // number[] → number
 
// Each .then() returns a NEW Promise
const p1 = fetchUser(userId);
const p2 = p1.then(u => u.name);
const p3 = p1.then(u => u.email);
// p1, p2, p3 are three independent Promises
// p1 can have multiple handlers - fan out

The Promise Chain as a Pipeline:

Think of a Promise chain as a data pipeline:

async operation → .then(transform) → .then(transform) → .catch(handle) → .finally(cleanup)
     Source         Transform 1        Transform 2        Error Handler      Cleanup

Values flow left-to-right through successful transformations
Errors skip transformations and flow directly to the next .catch()
.finally() always runs, then passes through the original result/error

This mental model—values and errors flowing through a pipeline—is the key to understanding Promise composition in the next page.

Immutability Enables Composition

Every Promise method returns a NEW Promise. The original is never mutated. This means you can attach multiple handlers to the same Promise, share Promises safely across code boundaries, and cache Promises for reuse. Immutability is what makes the pattern compositional.

async/await: Syntactic Sugar for Promises

While .then() chains are powerful, they can still feel different from sequential code. Most modern languages provide async/await syntax—syntactic sugar that makes async code look synchronous while remaining non-blocking underneath.

The key insight: await pauses the async function (not the thread!) until the Promise resolves, then returns the value. The function continues executing where it left off.

async-await-deep-dive
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// async/await is syntactic sugar for Promise chains
 
// These two functions are semantically identical:
 
// Using .then() chains
function processOrderChained(order: Order): Promise<OrderResult> {
    return paymentGateway.processPayment(order.paymentInfo)
        .then(payment => inventoryService.reserveItems(order.items)
            .then(inventory => ({ payment, inventory })))
        .then(({ payment, inventory }) => 
            shippingService.scheduleDelivery(order.shippingAddress, order.items)
                .then(shipping => ({ payment, inventory, shipping })))
        .then(({ shipping }) => OrderResult.success(shipping.trackingNumber))
        .catch(error => OrderResult.failed(error.message));
}
 
// Using async/await
async function processOrderAsync(order: Order): Promise<OrderResult> {
    try {
        const payment = await paymentGateway.processPayment(order.paymentInfo);
        const inventory = await inventoryService.reserveItems(order.items);
        const shipping = await shippingService.scheduleDelivery(
            order.shippingAddress, 
            order.items
        );
        return OrderResult.success(shipping.trackingNumber);
    } catch (error) {
        return OrderResult.failed(error.message);
    }
}
 
// The async/await version:
// - Reads top-to-bottom like synchronous code
// - Uses familiar try/catch for errors
// - Variables stay in scope (no nested closures)
// - Debugging is easier (stack traces make sense)
 
// IMPORTANT: async functions ALWAYS return Promises
async function getValue(): Promise<number> {
    return 42;  // Automatically wrapped: Promise.resolve(42)
}
 
async function getValueExplicit(): Promise<number> {
    return Promise.resolve(42);  // Same result
}
 
// await can only be used inside async functions (in most contexts)
async function example() {
    const a = await Promise.resolve(1);  // ✓ Works
    const b = await fetch('/api/data');   // ✓ Works
    const c = await 42;                   // ✓ Works (non-Promise is wrapped)
}

What Happens Under the Hood:

When the runtime encounters await, it:

Checks if the Promise is already settled
- If yes: continues immediately with the value/error
- If no: proceeds to step 2
Suspends the async function (saves its state)
Returns control to the event loop / scheduler
When the Promise settles, resumes the function from where it paused

The crucial point: The function pauses, not the thread. While one async function awaits, the thread can execute other async functions. This is how await achieves the readability of blocking code without the resource waste.

Common Mistake: Sequential When Parallel Would Work

// SLOW: Waits for each request sequentially
const user = await fetchUser();
const orders = await fetchOrders();
const reviews = await fetchReviews();
// Total time: sum of all three

// FAST: Runs all requests in parallel
const [user, orders, reviews] = await Promise.all([
  fetchUser(),
  fetchOrders(),
  fetchReviews()
]);
// Total time: max of the three

Use await for sequential dependencies. Use Promise.all() for independent operations.

Creating Promises: The Producer Side

So far we've focused on consuming Promises. But how do you create them? This is essential when wrapping callback-based APIs or implementing your own async operations.

The Promise constructor pattern:

Most Promise implementations provide a constructor that takes an 'executor' function. This executor receives resolve and reject functions—the write side of the Promise.

creating-promises
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// Creating Promises: wrapping async operations
 
// Basic Promise creation
function delay(ms: number): Promise<void> {
    return new Promise((resolve) => {
        setTimeout(() => resolve(), ms);
    });
}
 
// Wrapping a callback-based API
function readFileAsync(path: string): Promise<string> {
    return new Promise((resolve, reject) => {
        fs.readFile(path, 'utf-8', (error, data) => {
            if (error) {
                reject(error);  // Reject on error
            } else {
                resolve(data);  // Resolve on success
            }
        });
    });
}
 
// Wrapping XMLHttpRequest (classic callback API)
function httpGet(url: string): Promise<string> {
    return new Promise((resolve, reject) => {
        const xhr = new XMLHttpRequest();
        xhr.open('GET', url);
        
        xhr.onload = () => {
            if (xhr.status >= 200 && xhr.status < 300) {
                resolve(xhr.responseText);
            } else {
                reject(new Error(`HTTP ${xhr.status}: ${xhr.statusText}`));
            }
        };
        
        xhr.onerror = () => reject(new Error('Network error'));
        xhr.ontimeout = () => reject(new Error('Request timeout'));
        
        xhr.send();
    });
}
 
// Creating already-settled Promises
const instant = Promise.resolve(42);         // Already resolved
const failed = Promise.reject(new Error()); // Already rejected
 
// Useful for testing and default values
function fetchOrDefault<T>(
    fetchFn: () => Promise<T>, 
    defaultValue: T
): Promise<T> {
    return fetchFn().catch(() => defaultValue);
}

The Promisification Pattern

Wrapping callback-based APIs in Promises is so common that many languages/libraries provide utilities: Node.js has util.promisify(), Bluebird has Promise.promisifyAll(). The pattern is always the same: create a Promise, call the callback API, resolve/reject based on the callback result.

Summary: The Future/Promise Solution

We've now fully understood the Future/Promise abstraction—the solution to every problem we identified with blocking, polling, and callbacks. Let's consolidate the key concepts:

Key Takeaways

•A Promise is a container for an eventual value — It represents a computation that will complete in the future, either with a value (fulfilled) or an error (rejected).
•Promises are immutable and first-class — Once settled, a Promise never changes. Promises can be stored, passed, returned, and composed like any other value.
•The producer/consumer separation — Producers have the write side (resolve/reject); consumers only see the read side (then/catch). This prevents result tampering.
•Chain operations with .then(), .catch(), .finally() — Transformations chain linearly. Errors propagate until caught. Cleanup runs regardless of outcome.
•async/await is syntactic sugar — It makes Promise chains look like synchronous code. The runtime suspends the function (not the thread) at await, resuming when the Promise settles.
•Create Promises by wrapping async operations — The executor function receives resolve/reject to control when the Promise settles.

What's Next:

We now understand individual Promises. But real-world async programming requires composing multiple Promises—running them in parallel, racing them, handling partial successes, and building complex async workflows. The next page dives deep into Promise composition patterns: Promise.all(), Promise.race(), Promise.allSettled(), and more.

Page Complete

You now understand the Future/Promise abstraction at a fundamental level: the three states, the producer/consumer model, the core API, and how async/await provides syntactic elegance. This foundation is essential for the composition patterns we'll explore next.

2 / 4

Loading learning content...

System Design (LLD)Concurrency Patterns

Future and Promise Pattern

LevelIntermediate

Duration60 mins

TopicConcurrency Patterns

2 / 4

Solution: Future/Promise Abstraction

The Elegant Abstraction

The core insight is deceptively simple:

An asynchronous computation produces a value that doesn't exist yet, but will exist. Instead of waiting for that value or providing callbacks, we represent the pending value itself as an object.

What You Will Learn

The Conceptual Model: Eventual Values

To understand Future/Promise, we need to shift our mental model of computation. In synchronous programming, a function call produces a value immediately:

value = computeResult()  // value exists now
process(value)            // use it now

In asynchronous programming with Future/Promise, a function call produces a container for a value that will be filled in later:

futureValue = computeResultAsync()  // container exists now, value inside: pending
// The container will eventually hold the result OR an error
process(futureValue)                 // chain operations on the container

The key shift: Instead of thinking 'this function will eventually give me a value,' think 'this function immediately gives me a box that will contain a value.'

Converting Mermaid diagram...

The Three States of a Promise:

Every Promise/Future exists in exactly one of three states:

Pending: The async operation is still in progress. The eventual value is unknown.
Fulfilled (Resolved): The operation completed successfully. The value is available.
Rejected: The operation failed. An error is available.

State transitions are one-way and irreversible:

A Promise can transition from Pending → Fulfilled (exactly once)
A Promise can transition from Pending → Rejected (exactly once)
Once Fulfilled or Rejected, a Promise never changes state again

This immutability is crucial: once a Promise settles, its value or error is locked in forever. Any code that receives that Promise will always see the same result, enabling safe sharing and caching.

The Container Metaphor

Future vs Promise: The Dual Object Model

In many implementations, the 'async result container' concept is split into two related objects with distinct roles:

Promise (or Deferred, CompletableFuture, TaskCompletionSource):

The write side of the async result
Has methods to complete the result: resolve(value) or reject(error)
Typically held privately by the code that performs the async operation

Future (or Promise in JS, Task in C#):

The read side of the async result
Has methods to observe the result: then(), catch(), await
Returned to callers who want to use the result

This separation enforces a crucial invariant: only the producer can set the result; consumers can only observe it.

dual-object-model
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
import java.util.concurrent.CompletableFuture;
 
public class FuturePromiseExample {
    
    // The producer: creates and controls the CompletableFuture
    public CompletableFuture<String> fetchUserNameAsync(long userId) {
        // CompletableFuture is both Future (read) and Promise (write)
        CompletableFuture<String> future = new CompletableFuture<>();
        
        // Simulate async work in a background thread
        new Thread(() -> {
            try {
                // Simulate network latency
                Thread.sleep(500);
                
                // Producer completes the future with a value
                String userName = database.getUserName(userId);
                future.complete(userName);  // WRITE SIDE: resolve with value
                
            } catch (Exception e) {
                // Producer completes the future with an error
                future.completeExceptionally(e);  // WRITE SIDE: reject with error
            }
        }).start();
        
        // Return the future immediately - caller doesn't wait
        return future;
    }
    
    // The consumer: only has read access via CompletableFuture<T>
    public void displayUserName(long userId) {
        CompletableFuture<String> userNameFuture = fetchUserNameAsync(userId);
        
        // Consumer chains operations - READ SIDE only
        userNameFuture
            .thenAccept(name -> System.out.println("User: " + name))  // on success
            .exceptionally(error -> {
                System.err.println("Error: " + error.getMessage());
                return null;
            });
        
        // Consumer cannot call .complete() or .completeExceptionally()
        // The separation ensures only the producer controls the result
        
        System.out.println("Request initiated, continuing other work...");
    }
}

Future vs Promise Terminology Across Languages
Language	Read Side (Consumer)	Write Side (Producer)	Common Pattern
Java	CompletableFuture<T>	CompletableFuture<T>	Same object, but convention separates usage
JavaScript/TypeScript	Promise<T>	resolve/reject in executor	Write side only in constructor
C#	Task<T>	TaskCompletionSource<T>	Explicit separation
Python	asyncio.Future	loop.create_future()	Future is writable; wrapped for safety
Scala	Future[T]	Promise[T]	Explicit: Promise produces Future
Rust	impl Future	Pin<Box<...>>	Compiler enforces via ownership

Why Separation Matters

How Future/Promise Solves Each Problem

In our problem analysis, we identified seven requirements for an ideal async result handling solution. Let's see how Future/Promise addresses each one systematically.

Requirements Satisfied by Future/Promise
Requirement	How Future/Promise Addresses It
Non-blocking	Futures return immediately. The calling thread continues executing other code while the async operation runs. No thread is blocked waiting for results.
Push-based notification	Callbacks registered via `.then()` are invoked immediately when the Future resolves—no polling, no wasted checks, instant notification.
First-class representation	A Future IS a value. It can be stored in variables, passed to functions, returned from functions, stored in collections, and serialized.
Composable	`.then()` chains sequential operations. `Promise.all()` handles parallel operations. `Promise.race()` handles competition. Composition is built-in.
Unified error handling	Errors propagate through chains automatically. A single `.catch()` at the end handles errors from any step in the chain.
Readable, linear code	With `async/await` syntax, code reads top-to-bottom like synchronous code while remaining non-blocking underneath.
Cancelable	AbortController, CancellationToken, or similar patterns integrate with Futures to cancel pending operations.
Testable	Futures can be pre-resolved in tests. No complex async setup—just `Promise.resolve(mockValue)` or `CompletableFuture.completedFuture(mock)`.

Let's see this transformation in action. Remember our order processing example with horrific callback nesting? Here's the same logic with Futures:

callback-to-promise
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// BEFORE: Callback Hell (from previous page)
/*
function processOrder(order, onComplete, onError) {
    paymentGateway.processPayment(order.paymentInfo, 
        (paymentError, paymentResult) => {
            if (paymentError) { onError(...); return; }
            inventoryService.reserveItems(order.items,
                (inventoryError, inventoryResult) => {
                    if (inventoryError) { 
                        paymentGateway.refund(..., () => { onError(...); }); 
                        return; 
                    }
                    shippingService.scheduleDelivery(...,
                        (shippingError, shippingResult) => {
                            // ... even more nesting
                        }
                    );
                }
            );
        }
    );
}
*/
 
// AFTER: Promise-based (linear, composable, readable)
async function processOrder(order: Order): Promise<OrderResult> {
    // Sequential operations read top-to-bottom
    const payment = await paymentGateway.processPayment(order.paymentInfo);
    
    try {
        const inventory = await inventoryService.reserveItems(order.items);
        
        try {
            const shipping = await shippingService.scheduleDelivery(
                order.shippingAddress,
                order.items
            );
            
            // Notification failure shouldn't fail the order
            await notificationService
                .sendConfirmation(order.customerEmail, shipping.trackingNumber)
                .catch(err => logger.warn('Notification failed', err));
            
            return OrderResult.success(shipping.trackingNumber);
            
        } catch (shippingError) {
            // Rollback inventory on shipping failure
            await inventoryService.releaseItems(inventory.reservationId);
            throw shippingError;
        }
        
    } catch (inventoryOrShippingError) {
        // Rollback payment on any downstream failure
        await paymentGateway.refund(payment.transactionId);
        throw inventoryOrShippingError;
    }
}
 
// Compare: 60 lines of nested callbacks → 30 lines of linear code
// Error handling is clear and scoped
// Control flow matches mental model

The Transformation

The Core API: then, catch, finally

Every Future/Promise implementation provides a core set of operations for transforming and handling async results. Understanding these operations deeply is essential for effective async programming.

The fundamental operations:

Purpose: Transform the resolved value of a Promise.

Semantics: Takes a function that receives the resolved value and returns either:

A new value (Promise auto-wraps it)
A new Promise (Promise chains/unwraps it)

Key insight: .then() always returns a new Promise, never mutates the original. This immutability enables safe sharing and composition.

then-examples
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// .then() transforms the resolved value
const userPromise = fetchUser(userId);
 
// Transform to just the name (value → value)
const namePromise: Promise<string> = userPromise.then(user => user.name);
 
// Transform to another async operation (value → Promise)
const ordersPromise: Promise<Order[]> = userPromise
    .then(user => fetchOrders(user.id));  // Returns Promise<Order[]>
    // Promise automatically "unwraps" - no Promise<Promise<Order[]>>
 
// Chaining multiple transformations
const totalSpent: Promise<number> = fetchUser(userId)
    .then(user => fetchOrders(user.id))           // User → Order[]
    .then(orders => orders.map(o => o.total))     // Order[] → number[]
    .then(totals => totals.reduce((a, b) => a + b, 0)); // number[] → number
 
// Each .then() returns a NEW Promise
const p1 = fetchUser(userId);
const p2 = p1.then(u => u.name);
const p3 = p1.then(u => u.email);
// p1, p2, p3 are three independent Promises
// p1 can have multiple handlers - fan out

The Promise Chain as a Pipeline:

Think of a Promise chain as a data pipeline:

async operation → .then(transform) → .then(transform) → .catch(handle) → .finally(cleanup)
     Source         Transform 1        Transform 2        Error Handler      Cleanup

Values flow left-to-right through successful transformations
Errors skip transformations and flow directly to the next .catch()
.finally() always runs, then passes through the original result/error

This mental model—values and errors flowing through a pipeline—is the key to understanding Promise composition in the next page.

Immutability Enables Composition

async/await: Syntactic Sugar for Promises

The key insight: await pauses the async function (not the thread!) until the Promise resolves, then returns the value. The function continues executing where it left off.

async-await-deep-dive
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// async/await is syntactic sugar for Promise chains
 
// These two functions are semantically identical:
 
// Using .then() chains
function processOrderChained(order: Order): Promise<OrderResult> {
    return paymentGateway.processPayment(order.paymentInfo)
        .then(payment => inventoryService.reserveItems(order.items)
            .then(inventory => ({ payment, inventory })))
        .then(({ payment, inventory }) => 
            shippingService.scheduleDelivery(order.shippingAddress, order.items)
                .then(shipping => ({ payment, inventory, shipping })))
        .then(({ shipping }) => OrderResult.success(shipping.trackingNumber))
        .catch(error => OrderResult.failed(error.message));
}
 
// Using async/await
async function processOrderAsync(order: Order): Promise<OrderResult> {
    try {
        const payment = await paymentGateway.processPayment(order.paymentInfo);
        const inventory = await inventoryService.reserveItems(order.items);
        const shipping = await shippingService.scheduleDelivery(
            order.shippingAddress, 
            order.items
        );
        return OrderResult.success(shipping.trackingNumber);
    } catch (error) {
        return OrderResult.failed(error.message);
    }
}
 
// The async/await version:
// - Reads top-to-bottom like synchronous code
// - Uses familiar try/catch for errors
// - Variables stay in scope (no nested closures)
// - Debugging is easier (stack traces make sense)
 
// IMPORTANT: async functions ALWAYS return Promises
async function getValue(): Promise<number> {
    return 42;  // Automatically wrapped: Promise.resolve(42)
}
 
async function getValueExplicit(): Promise<number> {
    return Promise.resolve(42);  // Same result
}
 
// await can only be used inside async functions (in most contexts)
async function example() {
    const a = await Promise.resolve(1);  // ✓ Works
    const b = await fetch('/api/data');   // ✓ Works
    const c = await 42;                   // ✓ Works (non-Promise is wrapped)
}

What Happens Under the Hood:

When the runtime encounters await, it:

Checks if the Promise is already settled
- If yes: continues immediately with the value/error
- If no: proceeds to step 2
Suspends the async function (saves its state)
Returns control to the event loop / scheduler
When the Promise settles, resumes the function from where it paused

Common Mistake: Sequential When Parallel Would Work

// SLOW: Waits for each request sequentially
const user = await fetchUser();
const orders = await fetchOrders();
const reviews = await fetchReviews();
// Total time: sum of all three

// FAST: Runs all requests in parallel
const [user, orders, reviews] = await Promise.all([
  fetchUser(),
  fetchOrders(),
  fetchReviews()
]);
// Total time: max of the three

Use await for sequential dependencies. Use Promise.all() for independent operations.

Creating Promises: The Producer Side

So far we've focused on consuming Promises. But how do you create them? This is essential when wrapping callback-based APIs or implementing your own async operations.

The Promise constructor pattern:

Most Promise implementations provide a constructor that takes an 'executor' function. This executor receives resolve and reject functions—the write side of the Promise.

creating-promises
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// Creating Promises: wrapping async operations
 
// Basic Promise creation
function delay(ms: number): Promise<void> {
    return new Promise((resolve) => {
        setTimeout(() => resolve(), ms);
    });
}
 
// Wrapping a callback-based API
function readFileAsync(path: string): Promise<string> {
    return new Promise((resolve, reject) => {
        fs.readFile(path, 'utf-8', (error, data) => {
            if (error) {
                reject(error);  // Reject on error
            } else {
                resolve(data);  // Resolve on success
            }
        });
    });
}
 
// Wrapping XMLHttpRequest (classic callback API)
function httpGet(url: string): Promise<string> {
    return new Promise((resolve, reject) => {
        const xhr = new XMLHttpRequest();
        xhr.open('GET', url);
        
        xhr.onload = () => {
            if (xhr.status >= 200 && xhr.status < 300) {
                resolve(xhr.responseText);
            } else {
                reject(new Error(`HTTP ${xhr.status}: ${xhr.statusText}`));
            }
        };
        
        xhr.onerror = () => reject(new Error('Network error'));
        xhr.ontimeout = () => reject(new Error('Request timeout'));
        
        xhr.send();
    });
}
 
// Creating already-settled Promises
const instant = Promise.resolve(42);         // Already resolved
const failed = Promise.reject(new Error()); // Already rejected
 
// Useful for testing and default values
function fetchOrDefault<T>(
    fetchFn: () => Promise<T>, 
    defaultValue: T
): Promise<T> {
    return fetchFn().catch(() => defaultValue);
}

The Promisification Pattern

Summary: The Future/Promise Solution

We've now fully understood the Future/Promise abstraction—the solution to every problem we identified with blocking, polling, and callbacks. Let's consolidate the key concepts:

Key Takeaways

•A Promise is a container for an eventual value — It represents a computation that will complete in the future, either with a value (fulfilled) or an error (rejected).
•Promises are immutable and first-class — Once settled, a Promise never changes. Promises can be stored, passed, returned, and composed like any other value.
•The producer/consumer separation — Producers have the write side (resolve/reject); consumers only see the read side (then/catch). This prevents result tampering.
•Chain operations with .then(), .catch(), .finally() — Transformations chain linearly. Errors propagate until caught. Cleanup runs regardless of outcome.
•async/await is syntactic sugar — It makes Promise chains look like synchronous code. The runtime suspends the function (not the thread) at await, resuming when the Promise settles.
•Create Promises by wrapping async operations — The executor function receives resolve/reject to control when the Promise settles.

What's Next:

Page Complete

2 / 4