0
# ES6 Static Methods
1

2
Standard ES6 Promise static methods for creating resolved/rejected promises and combining multiple promises.
3

4
## Capabilities
5

6
### Promise.resolve
7

8
Creates a promise resolved with the given value, with optimization for common values.
9

10
```javascript { .api }
11
/**
12
 * Creates a resolved promise with the given value
13
 * @param {*} [value] - Value to resolve with (can be a promise or thenable)
14
 * @returns {Promise} Promise resolved with the value
15
 */
16
Promise.resolve(value);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const Promise = require('promise');
23

24
// Resolve with a value
25
const resolved = Promise.resolve(42);
26

27
// Resolve with no value (undefined)
28
const empty = Promise.resolve();
29

30
// Resolve with another promise (returns the same promise)
31
const original = Promise.resolve('hello');
32
const same = Promise.resolve(original); // same === original
33

34
// Resolve with a thenable
35
const thenable = {
36
  then: (resolve, reject) => resolve('from thenable')
37
};
38
const fromThenable = Promise.resolve(thenable);
39
```
40

41
### Promise.reject
42

43
Creates a promise rejected with the given reason.
44

45
```javascript { .api }
46
/**
47
 * Creates a rejected promise with the given reason
48
 * @param {*} reason - Reason for rejection
49
 * @returns {Promise} Promise rejected with the reason
50
 */
51
Promise.reject(reason);
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const Promise = require('promise');
58

59
// Reject with an error
60
const rejected = Promise.reject(new Error('Something failed'));
61

62
// Reject with any value
63
const rejectedWithString = Promise.reject('Operation cancelled');
64

65
// Use in promise chains
66
Promise.resolve(data)
67
  .then(result => {
68
    if (!result.isValid) {
69
      return Promise.reject(new Error('Invalid data'));
70
    }
71
    return result.value;
72
  });
73
```
74

75
### Promise.all
76

77
Returns a promise that resolves when all input promises resolve, or rejects when any input promise rejects.
78

79
```javascript { .api }
80
/**
81
 * Waits for all promises to resolve
82
 * @param {Iterable} iterable - Array or iterable of promises/values
83
 * @returns {Promise} Promise resolving to array of results in same order
84
 */
85
Promise.all(iterable);
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
const Promise = require('promise');
92

93
// Wait for multiple promises
94
const promises = [
95
  Promise.resolve(1),
96
  Promise.resolve(2),
97
  Promise.resolve(3)
98
];
99

100
Promise.all(promises).then(results => {
101
  console.log(results); // [1, 2, 3]
102
});
103

104
// Mix promises and values
105
Promise.all([
106
  fetch('/api/users'),
107
  fetch('/api/posts'), 
108
  42,
109
  'hello'
110
]).then(results => {
111
  const [users, posts, number, string] = results;
112
  // Process results...
113
});
114

115
// Fails fast on first rejection
116
Promise.all([
117
  Promise.resolve(1),
118
  Promise.reject(new Error('Failed')),
119
  Promise.resolve(3)
120
]).catch(error => {
121
  console.log(error.message); // "Failed"
122
});
123
```
124

125
### Promise.allSettled
126

127
Returns a promise that resolves when all input promises settle (resolve or reject), with results indicating the outcome of each.
128

129
```javascript { .api }
130
/**
131
 * Waits for all promises to settle regardless of outcome
132
 * @param {Iterable} iterable - Array or iterable of promises/values
133
 * @returns {Promise} Promise resolving to array of settlement results
134
 */
135
Promise.allSettled(iterable);
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
const Promise = require('promise');
142

143
const promises = [
144
  Promise.resolve('success'),
145
  Promise.reject(new Error('failed')),
146
  Promise.resolve(42)
147
];
148

149
Promise.allSettled(promises).then(results => {
150
  console.log(results);
151
  // [
152
  //   { status: 'fulfilled', value: 'success' },
153
  //   { status: 'rejected', reason: Error('failed') },
154
  //   { status: 'fulfilled', value: 42 }
155
  // ]
156
  
157
  results.forEach((result, index) => {
158
    if (result.status === 'fulfilled') {
159
      console.log(`Promise ${index} succeeded:`, result.value);
160
    } else {
161
      console.log(`Promise ${index} failed:`, result.reason);
162
    }
163
  });
164
});
165
```
166

167
### Promise.race
168

169
Returns a promise that settles as soon as the first input promise settles.
170

171
```javascript { .api }
172
/**
173
 * Returns the result of the first promise to settle
174
 * @param {Iterable} iterable - Array or iterable of promises/values  
175
 * @returns {Promise} Promise settling with first settlement result
176
 */
177
Promise.race(iterable);
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
const Promise = require('promise');
184

185
// Timeout pattern
186
const timeout = new Promise((_, reject) => {
187
  setTimeout(() => reject(new Error('Timeout')), 5000);
188
});
189

190
const operation = fetch('/api/data');
191

192
Promise.race([operation, timeout])
193
  .then(result => console.log('Completed within timeout'))
194
  .catch(error => console.log('Failed or timed out:', error.message));
195

196
// First to complete wins
197
Promise.race([
198
  new Promise(resolve => setTimeout(() => resolve('slow'), 1000)),
199
  new Promise(resolve => setTimeout(() => resolve('fast'), 100))
200
]).then(result => {
201
  console.log(result); // "fast"
202
});
203
```
204

205
### Promise.any
206

207
Returns a promise that fulfills with the first input promise to fulfill, or rejects with an AggregateError if all input promises reject.
208

209
```javascript { .api }
210
/**
211
 * Returns the result of the first promise to fulfill
212
 * @param {Iterable} iterable - Array or iterable of promises/values
213
 * @returns {Promise} Promise fulfilling with first fulfillment or AggregateError
214
 */
215
Promise.any(iterable);
216
```
217

218
**Usage Examples:**
219

220
```javascript
221
const Promise = require('promise');
222

223
// First successful result
224
const mirrors = [
225
  fetch('https://api1.example.com/data'),
226
  fetch('https://api2.example.com/data'),
227
  fetch('https://api3.example.com/data')
228
];
229

230
Promise.any(mirrors)
231
  .then(response => console.log('Got response from fastest server'))
232
  .catch(error => {
233
    // AggregateError if all fail
234
    console.log('All mirrors failed:', error.errors);
235
  });
236

237
// Mixed success and failure
238
Promise.any([
239
  Promise.reject(new Error('Failed 1')),
240
  Promise.resolve('Success!'),
241
  Promise.reject(new Error('Failed 2'))
242
]).then(result => {
243
  console.log(result); // "Success!"
244
});
245

246
// All failures
247
Promise.any([
248
  Promise.reject(new Error('Error 1')),
249
  Promise.reject(new Error('Error 2'))
250
]).catch(error => {
251
  console.log(error.name); // "AggregateError"
252
  console.log(error.errors); // [Error('Error 1'), Error('Error 2')]
253
});
254
```
255

256
## Types
257

258
```javascript { .api }
259
/**
260
 * Settlement result for Promise.allSettled
261
 */
262
interface SettlementResult {
263
  status: 'fulfilled' | 'rejected';
264
  value?: any;     // Present when status is 'fulfilled'
265
  reason?: any;    // Present when status is 'rejected'
266
}
267

268
/**
269
 * Error thrown by Promise.any when all promises reject
270
 */
271
interface AggregateError extends Error {
272
  name: 'AggregateError';
273
  errors: any[];   // Array of rejection reasons
274
}
275
```