0
# Array Promise Utilities
1

2
Functions for working with arrays of promises including parallel execution, racing, transformation, and filtering operations.
3

4
## Capabilities
5

6
### all
7

8
Wait for all promises in an array to fulfill, or fail fast on first rejection.
9

10
```javascript { .api }
11
/**
12
 * Wait for all promises to fulfill or any to reject (fail-fast)
13
 * @param array - Array of promises or values
14
 * @param label - Optional string for debugging/tooling
15
 * @returns Promise that fulfills with array of results in same order
16
 */
17
function all(array: Array, label?: string): Promise;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { all, resolve } from "rsvp";
24

25
// Basic usage with promises
26
all([
27
  fetchUser(1),
28
  fetchUser(2),
29
  fetchUser(3)
30
]).then(function(users) {
31
  console.log("All users loaded:", users);
32
}).catch(function(error) {
33
  console.error("At least one user failed to load:", error);
34
});
35

36
// Mixed promises and values
37
all([
38
  resolve("immediate"),
39
  Promise.resolve("also immediate"),
40
  fetchAsync()
41
]).then(function(results) {
42
  // results[0] === "immediate"
43
  // results[1] === "also immediate"  
44
  // results[2] === result from fetchAsync()
45
});
46
```
47

48
### allSettled
49

50
Wait for all promises to settle (fulfill or reject), collecting all results.
51

52
```javascript { .api }
53
/**
54
 * Wait for all promises to settle regardless of outcome
55
 * @param entries - Array of promises or values
56
 * @param label - Optional string for debugging/tooling
57
 * @returns Promise with array of {state, value/reason} objects
58
 */
59
function allSettled(entries: Array, label?: string): Promise;
60
```
61

62
**Usage Examples:**
63

64
```javascript
65
import { allSettled, resolve, reject } from "rsvp";
66

67
allSettled([
68
  resolve(1),
69
  reject(new Error("failed")),
70
  resolve(3)
71
]).then(function(results) {
72
  // results[0] === { state: 'fulfilled', value: 1 }
73
  // results[1] === { state: 'rejected', reason: Error }
74
  // results[2] === { state: 'fulfilled', value: 3 }
75
  
76
  const successful = results.filter(r => r.state === 'fulfilled');
77
  const failed = results.filter(r => r.state === 'rejected');
78
});
79
```
80

81
### race
82

83
Race multiple promises, settling with the first to settle.
84

85
```javascript { .api }
86
/**
87
 * Race promises, settling with the first to settle
88
 * @param array - Array of promises or values
89
 * @param label - Optional string for debugging/tooling
90
 * @returns Promise that settles with first settled value/reason
91
 */
92
function race(array: Array, label?: string): Promise;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
import { race, Promise } from "rsvp";
99

100
// Timeout pattern
101
race([
102
  fetchData(),
103
  new Promise((_, reject) => 
104
    setTimeout(() => reject(new Error("Timeout")), 5000)
105
  )
106
]).then(function(result) {
107
  console.log("Got result within timeout:", result);
108
}).catch(function(error) {
109
  console.error("Failed or timed out:", error);
110
});
111

112
// First successful response from multiple endpoints
113
race([
114
  fetch("/api/v1/data"),
115
  fetch("/api/v2/data"),
116
  fetch("/backup-api/data")
117
]).then(response => response.json());
118
```
119

120
### map
121

122
Transform an array of promises/values using a mapping function, with full async support.
123

124
```javascript { .api }
125
/**
126
 * Transform array of promises/values using mapping function
127
 * @param promises - Array of promises or values to transform
128
 * @param mapFn - Function to transform each resolved value
129
 * @param label - Optional string for debugging/tooling
130
 * @returns Promise with array of transformed values
131
 */
132
function map(promises: Array, mapFn: Function, label?: string): Promise;
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
import { map, resolve } from "rsvp";
139

140
// Transform resolved values
141
map([
142
  resolve(1),
143
  resolve(2), 
144
  resolve(3)
145
], function(value) {
146
  return value * 2;
147
}).then(function(results) {
148
  console.log(results); // [2, 4, 6]
149
});
150

151
// Async mapping function
152
map([
153
  "user1",
154
  "user2", 
155
  "user3"
156
], function(username) {
157
  return fetchUserProfile(username); // returns a promise
158
}).then(function(profiles) {
159
  console.log("All user profiles:", profiles);
160
});
161

162
// Error handling - fails on first rejection
163
map([
164
  resolve(1),
165
  reject(new Error("failed")),
166
  resolve(3)
167
], x => x * 2).catch(function(error) {
168
  console.error("Mapping failed:", error);
169
});
170
```
171

172
### filter
173

174
Filter an array of promises/values using a predicate function, with full async support.
175

176
```javascript { .api }
177
/**
178
 * Filter array of promises/values using predicate function
179
 * @param promises - Array of promises or values to filter
180
 * @param filterFn - Function to test each resolved value
181
 * @param label - Optional string for debugging/tooling
182
 * @returns Promise with array of values that pass the test
183
 */
184
function filter(promises: Array, filterFn: Function, label?: string): Promise;
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
import { filter, resolve } from "rsvp";
191

192
// Filter resolved values
193
filter([
194
  resolve(1),
195
  resolve(2),
196
  resolve(3),
197
  resolve(4)
198
], function(value) {
199
  return value > 2;
200
}).then(function(results) {
201
  console.log(results); // [3, 4]
202
});
203

204
// Async filter function
205
filter([
206
  "user1",
207
  "user2",
208
  "user3"
209
], function(username) {
210
  return checkUserPermissions(username).then(function(permissions) {
211
    return permissions.canAccess;
212
  });
213
}).then(function(allowedUsers) {
214
  console.log("Users with access:", allowedUsers);
215
});
216

217
// Error handling - fails on first rejection
218
filter([
219
  resolve(1),
220
  reject(new Error("failed")),
221
  resolve(3)
222
], x => x > 0).catch(function(error) {
223
  console.error("Filtering failed:", error);
224
});
225
```
226

227
## Error Handling Patterns
228

229
All array utilities follow these error handling patterns:
230

231
- **Fail-fast**: `all`, `map`, `filter`, `race` reject immediately on first rejection
232
- **Settle-all**: `allSettled` waits for all promises and provides state information
233

234
```javascript
235
import { all, allSettled } from "rsvp";
236

237
// This will reject as soon as any promise rejects
238
all([promise1, promise2, promise3])
239
  .catch(error => console.log("First error:", error));
240

241
// This will wait for all to complete
242
allSettled([promise1, promise2, promise3])
243
  .then(results => {
244
    const errors = results
245
      .filter(r => r.state === 'rejected')
246
      .map(r => r.reason);
247
    console.log("All errors:", errors);
248
  });
249
```