0
# Extension Methods
1

2
Additional instance methods that extend the core Promise functionality beyond the Promises/A+ specification.
3

4
## Capabilities
5

6
### Promise.prototype.catch
7

8
Shorthand for attaching only a rejection handler to the promise.
9

10
```javascript { .api }
11
/**
12
 * Attaches a rejection handler to the promise
13
 * @param {function} [onRejected] - Function to handle rejection
14
 * @returns {Promise} New promise for chaining
15
 */
16
Promise.prototype.catch(onRejected);
17
```
18

19
**Usage Examples:**
20

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

24
// Basic error handling
25
promise
26
  .then(result => processResult(result))
27
  .catch(error => {
28
    console.error('Error occurred:', error.message);
29
    return 'default value'; // Recovery
30
  });
31

32
// Equivalent to .then(null, onRejected)
33
promise.catch(error => handleError(error));
34

35
// Error recovery chain  
36
promise
37
  .catch(error => {
38
    if (error.code === 'NETWORK_ERROR') {
39
      return retryOperation();
40
    }
41
    throw error; // Re-throw if can't handle
42
  })
43
  .then(result => console.log('Final result:', result));
44
```
45

46
### Promise.prototype.done
47

48
Terminal handler that doesn't return a new promise and throws unhandled rejections globally.
49

50
```javascript { .api }
51
/**
52
 * Terminal promise handler without returning new promise
53
 * @param {function} [onFulfilled] - Success handler
54
 * @param {function} [onRejected] - Error handler  
55
 * @returns {void} Does not return a promise
56
 */
57
Promise.prototype.done(onFulfilled, onRejected);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const Promise = require('promise');
64

65
// Terminal handling - no further chaining
66
promise.done(
67
  result => console.log('Success:', result),
68
  error => console.error('Error:', error)
69
);
70

71
// Just success handler
72
promise.done(result => {
73
  updateUI(result);
74
  // Any unhandled errors will be thrown globally
75
});
76

77
// No handlers - unhandled rejections throw globally
78
promise.done(); // Ensures rejection throws if not handled elsewhere
79

80
// Comparison with .then()
81
promise.then(handler);     // Returns new promise, can chain
82
promise.done(handler);     // Returns void, terminates chain
83
```
84

85
### Promise.prototype.finally
86

87
Executes cleanup code regardless of promise outcome, without affecting the promise value.
88

89
```javascript { .api }
90
/**
91
 * Executes cleanup code regardless of promise outcome
92
 * @param {function} onFinally - Cleanup function (receives no arguments)
93
 * @returns {Promise} Promise with same settlement as original
94
 */
95
Promise.prototype.finally(onFinally);
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
const Promise = require('promise');
102

103
// Basic cleanup
104
let isLoading = true;
105

106
fetchData()
107
  .then(data => processData(data))
108
  .catch(error => handleError(error))
109
  .finally(() => {
110
    isLoading = false;  // Always executed
111
    hideSpinner();
112
  });
113

114
// Resource cleanup
115
function performOperation() {
116
  const resource = acquireResource();
117
  
118
  return processWithResource(resource)
119
    .finally(() => {
120
      releaseResource(resource); // Always cleanup
121
    });
122
}
123

124
// Cleanup doesn't affect promise value
125
Promise.resolve('original value')
126
  .finally(() => {
127
    console.log('Cleanup');
128
    return 'cleanup value'; // Ignored
129
  })
130
  .then(value => {
131
    console.log(value); // "original value"
132
  });
133

134
// Cleanup can introduce delay
135
Promise.resolve('result')
136
  .finally(() => {
137
    return new Promise(resolve => setTimeout(resolve, 1000));
138
  })
139
  .then(value => {
140
    console.log(value); // "result" (after 1 second delay)
141
  });
142
```
143

144
## Method Behavior Details
145

146
### Error Propagation
147

148
- **catch()**: Catches errors and allows recovery or re-throwing
149
- **done()**: Unhandled errors are thrown globally (not caught by outer try/catch)
150
- **finally()**: Errors in finally handler reject the returned promise
151

152
### Return Values
153

154
- **catch()**: Returns new promise, enables chaining
155
- **done()**: Returns void, terminates promise chain
156
- **finally()**: Returns promise with original value (unless finally handler rejects)
157

158
### Timing
159

160
- **catch()**: Executes when promise rejects
161
- **done()**: Executes when promise settles, then terminates chain
162
- **finally()**: Always executes after settlement, preserves original timing
163

164
**Example comparing all three:**
165

166
```javascript
167
const Promise = require('promise');
168

169
promise
170
  .then(result => processResult(result))
171
  .catch(error => {
172
    console.log('Caught error:', error);
173
    return 'recovered'; // Continue chain with new value
174
  })
175
  .finally(() => {
176
    console.log('Cleanup'); // Always runs
177
  })
178
  .done(finalResult => {
179
    console.log('Final result:', finalResult);
180
    // Chain terminates here - no return value
181
  });
182
```