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