0
# Promise.prototype.finally
1

2
Promise.prototype.finally provides an ES specification-compliant polyfill/shim for the Promise.prototype.finally method. It enables developers to use the finally method on Promise instances even in environments where it's not natively supported or is noncompliant with the specification.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const promiseFinally = require('promise.prototype.finally');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const promiseFinally = require('promise.prototype.finally');
21

22
// Use as a standalone function
23
const resolved = Promise.resolve(42);
24
const rejected = Promise.reject(-1);
25

26
promiseFinally(resolved, function () {
27
  console.log('This always runs, regardless of promise state');
28
  // Return value doesn't affect the original promise's value
29
  return Promise.resolve(true);
30
}).then(function (x) {
31
  console.log(x); // 42 - original value preserved
32
});
33

34
// Enable shimming to use as a method
35
promiseFinally.shim();
36

37
resolved.finally(function () {
38
  console.log('Now you can use .finally() as a method');
39
});
40
```
41

42
## Architecture
43

44
Promise.prototype.finally follows the es-shim API interface pattern:
45

46
- **Standalone Function**: Can be called directly as `promiseFinally(promise, onFinally)`
47
- **Polyfill Detection**: Automatically uses native implementation if available and compliant
48
- **Shimming**: Can modify `Promise.prototype` to add `.finally()` method
49
- **Auto-shimming**: Optional automatic installation via separate entry point
50
- **Spec Compliance**: Implements the full TC39 Promise.finally proposal specification
51

52
## Capabilities
53

54
### Direct Function Call
55

56
Call the polyfill directly without modifying Promise.prototype.
57

58
```javascript { .api }
59
/**
60
 * Execute a handler when a promise settles, regardless of its outcome
61
 * @param promise - The promise to attach the finally handler to
62
 * @param onFinally - Function to execute when promise settles (receives no arguments)
63
 * @returns New promise that preserves the original value or reason
64
 */
65
function promiseFinally(promise, onFinally);
66
```
67

68
**Usage Example:**
69

70
```javascript
71
const promiseFinally = require('promise.prototype.finally');
72

73
promiseFinally(Promise.resolve(42), function () {
74
  console.log('Cleanup logic here');
75
}).then(function (value) {
76
  console.log(value); // 42
77
});
78
```
79

80
### Polyfill Detection
81

82
Get the appropriate implementation (native or polyfill).
83

84
```javascript { .api }
85
/**
86
 * Returns native Promise.prototype.finally if available and compliant, otherwise returns implementation
87
 * @returns The finally function to use
88
 */
89
function getPolyfill();
90
```
91

92
**Usage Example:**
93

94
```javascript
95
const promiseFinally = require('promise.prototype.finally');
96
const finallyFn = promiseFinally.getPolyfill();
97
```
98

99
### Shimming
100

101
Install the polyfill on Promise.prototype if needed.
102

103
```javascript { .api }
104
/**
105
 * Installs the polyfill on Promise.prototype.finally if not present or non-compliant
106
 * @returns The polyfill function that was installed
107
 */
108
function shim();
109
```
110

111
**Usage Example:**
112

113
```javascript
114
const promiseFinally = require('promise.prototype.finally');
115
promiseFinally.shim(); // Now Promise.prototype.finally is available
116

117
Promise.resolve(42).finally(function () {
118
  console.log('Using as a method now');
119
});
120
```
121

122
### Auto-shimming
123

124
Automatically install the shim when the module is required.
125

126
```javascript { .api }
127
// Auto-shimming module - no exports, just side effects
128
require('promise.prototype.finally/auto');
129
```
130

131
**Usage Example:**
132

133
```javascript
134
// Just require the auto module
135
require('promise.prototype.finally/auto');
136

137
// Now .finally() is automatically available
138
Promise.resolve(42).finally(function () {
139
  console.log('Auto-shimmed!');
140
});
141
```
142

143
### Core Implementation
144

145
The spec-compliant implementation function.
146

147
```javascript { .api }
148
/**
149
 * The core implementation of Promise.prototype.finally
150
 * Must be called with a promise as 'this' context
151
 * @param onFinally - Function to execute when promise settles
152
 * @returns New promise preserving original value/reason
153
 */
154
function implementation(onFinally);
155
```
156

157
## Types
158

159
### Function Signatures
160

161
```javascript { .api }
162
/**
163
 * Main export properties - the default export is a function with additional properties
164
 * @type {Function & {getPolyfill: Function, implementation: Function, shim: Function}}
165
 */
166
// promiseFinally(promise, onFinally) - main function
167
// promiseFinally.getPolyfill() - get polyfill function
168
// promiseFinally.implementation(onFinally) - core implementation  
169
// promiseFinally.shim() - install shim function
170
```
171

172
### Behavior Specifications
173

174
- **onFinally handler**: Called with no arguments regardless of promise state
175
- **Return value handling**: If onFinally returns a promise, waits for it to settle before continuing
176
- **Value preservation**: Original promise's fulfillment value or rejection reason is preserved
177
- **Error propagation**: If onFinally throws or returns a rejected promise, that becomes the new rejection reason
178
- **Chaining**: Returns a new promise that can be further chained
179

180
## Error Handling
181

182
The implementation throws `TypeError` in these cases:
183

184
```javascript { .api }
185
// When Promise is not available globally (during module loading)
186
// TypeError: `Promise.prototype.finally` requires a global `Promise` be available.
187

188
// When the implementation is called directly on non-object receiver
189
// TypeError: receiver is not an Object
190
```
191

192
## Environment Requirements
193

194
- **ES3+ environment** with global `Promise` constructor available
195
- **Node.js**: >= 0.4
196
- **Browser**: Any modern browser with Promise support
197
- **Polyfill compatibility**: Works with es6-shim and other Promise polyfills