0
# Promise.allSettled
1

2
Promise.allSettled is a spec-compliant polyfill/shim for the `Promise.allSettled` method introduced in ES2020. It provides a consistent implementation across all JavaScript environments that support Promises, allowing developers to wait for all promises in an iterable to settle (either fulfill or reject) and receive detailed information about each promise's outcome.
3

4
## Package Information
5

6
- **Package Name**: promise.allsettled
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install promise.allsettled`
10

11
## Core Imports
12

13
```javascript
14
const allSettled = require("promise.allsettled");
15
```
16

17
For individual components:
18

19
```javascript
20
const allSettled = require("promise.allsettled");
21
const implementation = require("promise.allsettled/implementation");
22
const getPolyfill = require("promise.allsettled/polyfill");
23
const shim = require("promise.allsettled/shim");
24
```
25

26
Auto-shim (automatically patches global Promise if needed):
27

28
```javascript
29
require("promise.allsettled/auto");
30
```
31

32
## Basic Usage
33

34
```javascript
35
const allSettled = require("promise.allsettled");
36

37
const resolved = Promise.resolve(42);
38
const rejected = Promise.reject(new Error("failed"));
39

40
// Wait for all promises to settle
41
allSettled([resolved, rejected]).then(function (results) {
42
  console.log(results);
43
  // [
44
  //   { status: 'fulfilled', value: 42 },
45
  //   { status: 'rejected', reason: Error('failed') }
46
  // ]
47
});
48

49
// After shimming, use native Promise.allSettled
50
allSettled.shim();
51
Promise.allSettled([resolved, rejected]).then(function (results) {
52
  // Same result format
53
});
54
```
55

56
## Architecture
57

58
Promise.allSettled follows the es-shim API specification:
59

60
- **Main Function**: Bound implementation that can be used standalone
61
- **Implementation**: Core spec-compliant logic
62
- **Polyfill**: Detection and fallback to native or implementation
63
- **Shim**: Global Promise patching capability
64
- **Auto-shim**: Automatic installation on require
65

66
## Capabilities
67

68
### Main Function
69

70
The primary export provides Promise.allSettled functionality that works consistently across environments.
71

72
```javascript { .api }
73
/**
74
 * Returns a promise that resolves after all of the provided promises have settled
75
 * @param {Iterable} iterable - An iterable of promises or values
76
 * @returns {Promise<Array<{status: 'fulfilled' | 'rejected', value?: any, reason?: any}>>}
77
 */
78
function allSettled(iterable);
79
```
80

81
**Parameters:**
82
- `iterable`: Any iterable (array, Set, etc.) containing promises or values
83

84
**Returns:** Promise that resolves to an array of settlement result objects
85

86
**Result Object Structure:**
87
- For fulfilled promises: `{ status: 'fulfilled', value: <resolved-value> }`
88
- For rejected promises: `{ status: 'rejected', reason: <rejection-reason> }`
89

90
**Usage Example:**
91

92
```javascript
93
const allSettled = require("promise.allsettled");
94

95
const promises = [
96
  Promise.resolve("success"),
97
  Promise.reject(new Error("failure")),
98
  Promise.resolve(123),
99
  "not a promise" // Non-promise values are treated as resolved
100
];
101

102
allSettled(promises).then(results => {
103
  results.forEach((result, index) => {
104
    if (result.status === 'fulfilled') {
105
      console.log(`Promise ${index} resolved with:`, result.value);
106
    } else {
107
      console.log(`Promise ${index} rejected with:`, result.reason);
108
    }
109
  });
110
});
111
```
112

113
### Implementation Function
114

115
The core spec-compliant implementation that requires explicit Promise constructor binding.
116

117
```javascript { .api }
118
/**
119
 * Core implementation of Promise.allSettled
120
 * @param {Iterable} iterable - An iterable of promises or values
121
 * @returns {Promise<Array<{status: 'fulfilled' | 'rejected', value?: any, reason?: any}>>}
122
 */
123
allSettled.implementation(iterable);
124
```
125

126
**Usage:**
127

128
```javascript
129
const implementation = require("promise.allsettled/implementation");
130

131
// Must be called with Promise constructor as 'this'
132
const result = implementation.call(Promise, [Promise.resolve(1), Promise.reject(2)]);
133
```
134

135
### Polyfill Detection
136

137
Returns the appropriate Promise.allSettled function (native if available and compliant, otherwise the implementation).
138

139
```javascript { .api }
140
/**
141
 * Returns native Promise.allSettled if available and compliant, otherwise returns implementation
142
 * @returns {Function} The appropriate Promise.allSettled function
143
 */
144
allSettled.getPolyfill();
145
```
146

147
**Usage:**
148

149
```javascript
150
const getPolyfill = require("promise.allsettled/polyfill");
151

152
const polyfill = getPolyfill();
153
// Use polyfill.call(Promise, iterable) or as Promise.allSettled replacement
154
```
155

156
### Global Shim
157

158
Patches the global Promise.allSettled if it's missing or non-compliant.
159

160
```javascript { .api }
161
/**
162
 * Installs Promise.allSettled on the global Promise if needed
163
 * @returns {Function} The polyfill function that was installed
164
 */
165
allSettled.shim();
166
```
167

168
**Usage:**
169

170
```javascript
171
const allSettled = require("promise.allsettled");
172

173
allSettled.shim(); // Now Promise.allSettled is available globally
174

175
// Use native Promise.allSettled
176
Promise.allSettled([Promise.resolve(1), Promise.reject(2)])
177
  .then(console.log);
178
```
179

180
### Auto-Shimming
181

182
Automatically applies the shim when the module is required.
183

184
```javascript { .api }
185
// Auto-shim module - no exports, side-effects only
186
require("promise.allsettled/auto");
187
```
188

189
**Usage:**
190

191
```javascript
192
// Simply require to automatically install the shim
193
require("promise.allsettled/auto");
194

195
// Promise.allSettled is now available globally
196
Promise.allSettled([Promise.resolve(1)])
197
  .then(console.log); // [{ status: 'fulfilled', value: 1 }]
198
```
199

200
## Error Handling
201

202
The library handles various error conditions:
203

204
- **Missing Promise Constructor**: Throws `TypeError` if global `Promise` is not available
205
- **Invalid This Context**: Implementation throws `TypeError` if `this` is not an object when called directly
206
- **Promise Rejections**: Individual promise rejections are captured in result objects, not thrown
207

208
```javascript
209
const allSettled = require("promise.allsettled");
210

211
// This will not throw, even though one promise rejects
212
allSettled([
213
  Promise.resolve("ok"),
214
  Promise.reject(new Error("error"))
215
]).then(results => {
216
  // Both results are captured in the array
217
  console.log(results[0]); // { status: 'fulfilled', value: 'ok' }
218
  console.log(results[1]); // { status: 'rejected', reason: Error('error') }
219
});
220
```
221

222
## Environment Requirements
223

224
- **JavaScript Engine**: ES3+ compatible
225
- **Global Promise**: Must have a global `Promise` constructor available
226
- **Polyfill Compatibility**: Works with Promise polyfills like es6-shim
227

228
## Spec Compliance
229

230
This implementation follows the [TC39 Promise.allSettled proposal](https://github.com/tc39/proposal-promise-allSettled) and is fully spec-compliant with the finalized ES2020 specification.