Futures and 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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

// Demonstrating promise state transitions
 
// Creating a pending promise
const promise = new Promise((resolve, reject) => {
    console.log("Promise is PENDING");
    
    setTimeout(() => {
        // Transition to FULFILLED
        resolve("Success value");
        // This promise is now permanently fulfilled
        
        // These have NO effect - state cannot change
        resolve("Another value");  // Ignored
        reject("An error");        // Ignored
    }, 1000);
});
 
// Checking state (conceptually - actual state is internal)
// promise is PENDING here
 
promise.then(value => {
    console.log("Promise is FULFILLED with:", value);
    // Output: "Promise is FULFILLED with: Success value"
});
 
// ========================================
// Creating rejected promises
// ========================================
 
const rejected = new Promise((resolve, reject) => {
    reject(new Error("Something failed"));
    
    // Again, subsequent calls are ignored
    resolve("This won't work");
});
 
rejected.catch(error => {
    console.log("Promise is REJECTED with:", error.message);
});
 
// ========================================
// State transition diagram
// ========================================
 
/*
                    ┌─────────────────────────────┐
                    │                             │
    ┌───────┐       │         ┌──────────┐       │
    │PENDING│───────┼────────►│FULFILLED │       │
    └───────┘       │resolve()└──────────┘       │
        │           │              │              │
        │           │         (immutable)        │
        │           │                            │
        │reject()   │                            │
        │           │         ┌──────────┐       │
        └───────────┼────────►│REJECTED  │       │
                    │         └──────────┘       │
                    │              │              │
                    │         (immutable)        │
                    │                            │
                    └─────────────────────────────┘
*/
 
// ========================================
// "Settled" = Fulfilled OR Rejected
// ========================================
 
// A promise is "settled" when it's no longer pending
// Settled promises have a final value/reason
 
Promise.allSettled([
    Promise.resolve(1),
    Promise.reject(new Error("fail")),
    Promise.resolve(3)
]).then(results => {
    // All promises have settled (regardless of fulfill/reject)
    console.log(results);
    // [
    //   { status: "fulfilled", value: 1 },
    //   { status: "rejected", reason: Error },
    //   { status: "fulfilled", value: 3 }
    // ]
});

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

// ========================================
// Pattern 1: Wrapping callback-based APIs
// ========================================
 
// Original callback API
function readFileCallback(path, callback) {
    fs.readFile(path, 'utf8', callback);
}
 
// Promisified version
function readFilePromise(path) {
    return new Promise((resolve, reject) => {
        fs.readFile(path, 'utf8', (err, data) => {
            if (err) {
                reject(err);
            } else {
                resolve(data);
            }
        });
    });
}
 
// Usage
readFilePromise('/path/to/file')
    .then(data => console.log(data))
    .catch(err => console.error(err));
 
 
// ========================================
// Pattern 2: Timer-based promises
// ========================================
 
function delay(ms) {
    return new Promise(resolve => {
        setTimeout(() => resolve(), ms);
    });
}
 
function timeout(ms, message) {
    return new Promise((_, reject) => {
        setTimeout(() => reject(new Error(message)), ms);
    });
}
 
// Usage
delay(1000).then(() => console.log("1 second passed"));
 
 
// ========================================
// Pattern 3: Conditional resolution
// ========================================
 
function fetchWithValidation(url) {
    return new Promise((resolve, reject) => {
        if (!url.startsWith('https://')) {
            reject(new Error('Only HTTPS URLs allowed'));
            return;
        }
        
        fetch(url)
            .then(response => {
                if (!response.ok) {
                    reject(new Error(`HTTP ${response.status}`));
                } else {
                    resolve(response.json());
                }
            })
            .catch(reject);  // Network errors
    });
}
 
 
// ========================================
// Pattern 4: Promise-based event listener
// ========================================
 
function waitForEvent(element, eventName) {
    return new Promise(resolve => {
        function handler(event) {
            element.removeEventListener(eventName, handler);
            resolve(event);
        }
        element.addEventListener(eventName, handler);
    });
}
 
// Usage
const clickEvent = await waitForEvent(button, 'click');
 
 
// ========================================
// Static creation methods
// ========================================
 
// Already fulfilled
const fulfilled = Promise.resolve(42);
 
// Already rejected  
const rejected = Promise.reject(new Error("Failed"));
 
// Resolve with another promise (adopts its state)
const adopted = Promise.resolve(someOtherPromise);

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

// ========================================
// Basic chaining - compare to callback hell
// ========================================
 
// CALLBACK VERSION (pyramid of doom)
getUser(userId, (err, user) => {
    if (err) return handleError(err);
    getOrders(user.id, (err, orders) => {
        if (err) return handleError(err);
        getProducts(orders[0].productId, (err, product) => {
            if (err) return handleError(err);
            console.log(product);
        });
    });
});
 
// PROMISE VERSION (flat chain)
getUser(userId)
    .then(user => getOrders(user.id))
    .then(orders => getProducts(orders[0].productId))
    .then(product => console.log(product))
    .catch(err => handleError(err));  // ONE error handler for all!
 
 
// ========================================
// Understanding the chain mechanics
// ========================================
 
Promise.resolve(1)
    .then(x => {
        console.log("Step 1:", x);  // 1
        return x + 1;  // Return value becomes next value
    })
    .then(x => {
        console.log("Step 2:", x);  // 2
        return x * 2;
    })
    .then(x => {
        console.log("Step 3:", x);  // 4
        // Return a promise - chain waits for it
        return new Promise(resolve => {
            setTimeout(() => resolve(x + 10), 1000);
        });
    })
    .then(x => {
        console.log("Step 4:", x);  // 14 (after 1 second)
    });
 
 
// ========================================
// Each .then() creates a NEW promise
// ========================================
 
const p1 = Promise.resolve(1);
const p2 = p1.then(x => x + 1);
const p3 = p2.then(x => x + 1);
 
console.log(p1 === p2);  // false - different promises!
console.log(p2 === p3);  // false
 
// You can branch from any promise
const base = fetchUser(userId);
 
const branch1 = base.then(user => user.name);
const branch2 = base.then(user => user.email);
const branch3 = base.then(user => fetchOrders(user.id));
 
// All three branches stem from the same base promise
// They execute independently
 
 
// ========================================
// Value transformation vs async operations
// ========================================
 
fetchUser(userId)
    // Sync transformation - just return the value
    .then(user => user.name.toUpperCase())
    
    // Async operation - return a promise
    .then(name => sendNotification(`Hello ${name}`))
    
    // The chain handles both seamlessly
    .then(result => console.log("Notification sent:", result));

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

// ========================================
// Error propagation through the chain
// ========================================
 
fetchUser(userId)
    .then(user => {
        if (!user.active) {
            throw new Error("User is inactive");  // Rejection!
        }
        return fetchOrders(user.id);
    })
    .then(orders => {
        // SKIPPED if previous threw
        return processOrders(orders);
    })
    .then(result => {
        // SKIPPED if any earlier step failed
        return formatResult(result);
    })
    .catch(error => {
        // Catches ANY error from the entire chain
        console.error("Operation failed:", error.message);
    });
 
 
// ========================================
// .catch() is sugar for .then(null, handler)
// ========================================
 
// These are equivalent:
promise.catch(handleError);
promise.then(null, handleError);
 
// But .catch() is clearer and preferred
 
 
// ========================================
// Recovery in catch handlers
// ========================================
 
fetchFromPrimary(id)
    .catch(error => {
        console.log("Primary failed, trying backup...");
        return fetchFromBackup(id);  // Return new promise
    })
    .then(data => {
        // Gets data from whichever succeeded
        console.log("Got data:", data);
    })
    .catch(error => {
        // Only if BOTH failed
        console.error("All sources failed:", error);
    });
 
 
// ========================================
// Error typing and handling
// ========================================
 
fetchResource(url)
    .catch(error => {
        if (error.name === 'NetworkError') {
            return cachedVersion(url);  // Recover
        }
        if (error.status === 404) {
            return null;  // Not found is okay, return null
        }
        throw error;  // Re-throw unknown errors
    })
    .then(resource => {
        if (resource === null) {
            console.log("Resource not found");
        } else {
            processResource(resource);
        }
    });
 
 
// ========================================
// .finally() - cleanup regardless of outcome
// ========================================
 
let connection;
 
connectToDatabase()
    .then(conn => {
        connection = conn;
        return queryDatabase(conn, sql);
    })
    .then(results => {
        return processResults(results);
    })
    .catch(error => {
        console.error("Database operation failed:", error);
        throw error;  // Re-throw after logging
    })
    .finally(() => {
        // Runs whether fulfilled OR rejected
        // Does NOT receive the value/error
        // Return value is ignored (doesn't affect chain)
        if (connection) {
            connection.close();
        }
    });
 
 
// ========================================
// Common mistake: catch placement
// ========================================
 
// WRONG - catch doesn't protect later operations
fetchData()
    .catch(err => handleFetchError(err))
    .then(data => processData(data))  // Might receive undefined!
    .then(result => saveResult(result));  // Error here not caught!
 
// RIGHT - catch at the end catches everything
fetchData()
    .then(data => processData(data))
    .then(result => saveResult(result))
    .catch(err => handleAnyError(err));
 
// OR - multiple catch blocks for different handling
fetchData()
    .catch(err => {
        if (recoverableError(err)) {
            return getDefaultData();
        }
        throw err;
    })
    .then(data => processData(data))
    .catch(err => notifyUser(err));

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

// ========================================
// Promise.all - Wait for ALL to succeed
// ========================================
 
const userPromise = fetchUser(userId);
const ordersPromise = fetchOrders(userId);
const analyticsPromise = fetchAnalytics(userId);
 
// All three requests run CONCURRENTLY
// Promise.all waits for ALL to complete
 
Promise.all([userPromise, ordersPromise, analyticsPromise])
    .then(([user, orders, analytics]) => {
        // ALL succeeded - array of results in order
        console.log("User:", user.name);
        console.log("Orders:", orders.length);
        console.log("Analytics:", analytics.pageViews);
    })
    .catch(error => {
        // ANY failure rejects immediately (fast-fail)
        // Other pending promises continue but results are discarded
        console.error("One request failed:", error);
    });
 
 
// ========================================
// Promise.allSettled - Wait for all to complete
// ========================================
 
// Doesn't short-circuit on failure
Promise.allSettled([
    fetch('/api/primary'),
    fetch('/api/secondary'),
    fetch('/api/tertiary')
]).then(results => {
    results.forEach((result, index) => {
        if (result.status === 'fulfilled') {
            console.log(`Request ${index} succeeded:`, result.value);
        } else {
            console.log(`Request ${index} failed:`, result.reason);
        }
    });
    // Can proceed even if some failed
    const successfulResults = results
        .filter(r => r.status === 'fulfilled')
        .map(r => r.value);
});
 
 
// ========================================
// Promise.race - First to settle wins
// ========================================
 
// Timeout pattern
function fetchWithTimeout(url, ms) {
    return Promise.race([
        fetch(url),
        new Promise((_, reject) => 
            setTimeout(() => reject(new Error('Timeout')), ms)
        )
    ]);
}
 
fetchWithTimeout('/api/slow-endpoint', 5000)
    .then(response => console.log("Got response in time"))
    .catch(error => console.log("Timed out or failed:", error.message));
 
 
// ========================================
// Promise.any - First to SUCCEED wins
// ========================================
 
// Try multiple sources, use first successful
Promise.any([
    fetchFromMirror1(file),
    fetchFromMirror2(file),
    fetchFromMirror3(file)
]).then(data => {
    console.log("Got file from fastest mirror:", data);
}).catch(error => {
    // AggregateError - ALL failed
    console.log("All mirrors failed:", error.errors);
});
 
 
// ========================================
// Comparison table
// ========================================
 
/*
| Combinator       | Resolves when...        | Rejects when...        |
|------------------|-------------------------|------------------------|
| Promise.all      | ALL fulfill             | ANY rejects            |
| Promise.allSettled| ALL settle             | Never (always fulfills)|
| Promise.race     | FIRST settles           | FIRST rejects          |
| Promise.any      | FIRST fulfills          | ALL reject             |
*/
 
 
// ========================================
// Practical pattern: Concurrent with limit
// ========================================
 
async function mapWithConcurrency(items, fn, concurrency) {
    const results = [];
    const executing = new Set();
    
    for (const item of items) {
        const promise = fn(item).then(result => {
            executing.delete(promise);
            return result;
        });
        executing.add(promise);
        results.push(promise);
        
        if (executing.size >= concurrency) {
            await Promise.race(executing);
        }
    }
    
    return Promise.all(results);
}
 
// Process 100 URLs, max 5 concurrent requests
await mapWithConcurrency(urls, fetchUrl, 5);