0
# Promise Class
1

2
Core Promise implementation following Promises/A+ specification with additional utility methods and ES6 compliance.
3

4
## Capabilities
5

6
### Promise Constructor
7

8
Creates a new Promise instance with a resolver function.
9

10
```javascript { .api }
11
/**
12
 * Promise constructor following Promises/A+ specification
13
 * @param resolver - Function with (resolve, reject) parameters
14
 * @param label - Optional string for debugging/tooling
15
 */
16
class Promise {
17
  constructor(resolver: Function, label?: string);
18
}
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import { Promise } from "rsvp";
25

26
// Basic promise creation
27
const promise = new Promise(function(resolve, reject) {
28
  setTimeout(() => resolve("Hello World"), 1000);
29
});
30

31
// Promise with error handling
32
const riskyPromise = new Promise(function(resolve, reject) {
33
  if (Math.random() > 0.5) {
34
    resolve("Success!");
35
  } else {
36
    reject(new Error("Something went wrong"));
37
  }
38
});
39
```
40

41
### Instance Methods
42

43
#### then
44

45
The primary way of interacting with a promise through callback registration.
46

47
```javascript { .api }
48
/**
49
 * Register callbacks for promise fulfillment and rejection
50
 * @param onFulfillment - Called when promise fulfills
51
 * @param onRejection - Called when promise rejects
52
 * @param label - Optional string for debugging/tooling
53
 * @returns New promise for chaining
54
 */
55
then(onFulfillment?: Function, onRejection?: Function, label?: string): Promise;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
promise.then(function(value) {
62
  console.log("Fulfilled:", value);
63
}, function(reason) {
64
  console.log("Rejected:", reason);
65
});
66

67
// Chaining
68
promise
69
  .then(value => value.toUpperCase())
70
  .then(upperValue => upperValue + "!")
71
  .then(result => console.log(result));
72
```
73

74
#### catch
75

76
Sugar for handling promise rejections.
77

78
```javascript { .api }
79
/**
80
 * Register callback for promise rejection only
81
 * @param onRejection - Called when promise rejects
82
 * @param label - Optional string for debugging/tooling
83
 * @returns New promise for chaining
84
 */
85
catch(onRejection: Function, label?: string): Promise;
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
promise
92
  .then(value => processValue(value))
93
  .catch(error => {
94
    console.error("Error occurred:", error);
95
    return "Default value";
96
  });
97
```
98

99
#### finally
100

101
Execute callback regardless of promise outcome.
102

103
```javascript { .api }
104
/**
105
 * Execute callback when promise settles (fulfills or rejects)
106
 * @param callback - Function to execute regardless of outcome
107
 * @param label - Optional string for debugging/tooling
108
 * @returns New promise maintaining original value/reason
109
 */
110
finally(callback: Function, label?: string): Promise;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
fetchData()
117
  .then(data => processData(data))
118
  .catch(error => handleError(error))
119
  .finally(() => {
120
    console.log("Operation completed");
121
    hideLoadingSpinner();
122
  });
123
```
124

125
### Static Methods
126

127
#### Promise.all
128

129
Wait for all promises to fulfill or any to reject.
130

131
```javascript { .api }
132
/**
133
 * Wait for all promises in array to fulfill
134
 * @param array - Array of promises or values
135
 * @param label - Optional string for debugging/tooling
136
 * @returns Promise that fulfills with array of results
137
 */
138
static all(array: Array, label?: string): Promise;
139
```
140

141
#### Promise.race
142

143
Race multiple promises, settling with the first to settle.
144

145
```javascript { .api }
146
/**
147
 * Race promises, settling with first to settle
148
 * @param array - Array of promises or values
149
 * @param label - Optional string for debugging/tooling
150
 * @returns Promise that settles with first settled value/reason
151
 */
152
static race(array: Array, label?: string): Promise;
153
```
154

155
#### Promise.resolve
156

157
Create a fulfilled promise with the given value.
158

159
```javascript { .api }
160
/**
161
 * Create promise resolved with given value
162
 * @param value - Value to resolve promise with
163
 * @param label - Optional string for debugging/tooling
164
 * @returns Promise resolved with value
165
 */
166
static resolve(value?: any, label?: string): Promise;
167
```
168

169
#### Promise.reject
170

171
Create a rejected promise with the given reason.
172

173
```javascript { .api }
174
/**
175
 * Create promise rejected with given reason
176
 * @param reason - Reason for rejection
177
 * @param label - Optional string for debugging/tooling
178
 * @returns Promise rejected with reason
179
 */
180
static reject(reason?: any, label?: string): Promise;
181
```
182

183
#### Promise.cast
184

185
Deprecated alias for `Promise.resolve`, maintained for backwards compatibility.
186

187
```javascript { .api }
188
/**
189
 * @deprecated Use Promise.resolve() instead
190
 * Create promise resolved with given value
191
 * @param value - Value to resolve promise with
192
 * @param label - Optional string for debugging/tooling
193
 * @returns Promise resolved with value
194
 */
195
static cast(value?: any, label?: string): Promise;
196
```
197

198
**Usage Examples for Static Methods:**
199

200
```javascript
201
import { Promise } from "rsvp";
202

203
// Promise.all
204
Promise.all([
205
  fetchUser(1),
206
  fetchUser(2),
207
  fetchUser(3)
208
]).then(users => {
209
  console.log("All users:", users);
210
});
211

212
// Promise.race with timeout
213
Promise.race([
214
  fetchData(),
215
  new Promise((_, reject) => 
216
    setTimeout(() => reject(new Error("Timeout")), 5000)
217
  )
218
]).then(result => {
219
  console.log("Got result:", result);
220
});
221

222
// Promise.resolve for immediate values
223
Promise.resolve("immediate value")
224
  .then(value => console.log(value));
225

226
// Promise.reject for immediate errors
227
Promise.reject(new Error("Something failed"))
228
  .catch(error => console.error(error));
229

230
// Promise.cast (deprecated - use Promise.resolve instead)
231
Promise.cast("immediate value")
232
  .then(value => console.log(value)); // Not recommended for new code
233
```
234

235
## Promise States
236

237
- **Pending**: Initial state, neither fulfilled nor rejected
238
- **Fulfilled**: Operation completed successfully with a value
239
- **Rejected**: Operation failed with a reason
240
- **Settled**: Either fulfilled or rejected (final state)