0
# Promise
1
2
Promise is a bare bones implementation of the Promises/A+ specification designed for readable, performant code with minimal but essential extensions. It provides foundational promise functionality for JavaScript applications requiring reliable asynchronous operation handling with maximum compatibility and performance.
3
4
## Package Information
5
6
- **Package Name**: promise
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install promise`
10
11
## Core Imports
12
13
```javascript
14
const Promise = require('promise');
15
```
16
17
For specific execution environments:
18
19
```javascript
20
// For Node.js domains support
21
const Promise = require('promise/domains');
22
23
// For setImmediate optimization
24
const Promise = require('promise/setimmediate');
25
26
// ES6-only features
27
const Promise = require('promise/lib/es6-extensions');
28
// or require('promise/domains/es6-extensions');
29
// or require('promise/setimmediate/es6-extensions');
30
31
// Core only (deprecated entry point)
32
const Promise = require('promise/core'); // Use promise/lib/core instead
33
```
34
35
Browser polyfill:
36
37
```html
38
<script src="https://www.promisejs.org/polyfills/promise-6.1.0.js"></script>
39
```
40
41
## Basic Usage
42
43
```javascript
44
const Promise = require('promise');
45
46
// Create a new promise
47
const promise = new Promise(function (resolve, reject) {
48
// Async operation
49
setTimeout(() => {
50
if (Math.random() > 0.5) {
51
resolve('Success!');
52
} else {
53
reject(new Error('Failed'));
54
}
55
}, 1000);
56
});
57
58
// Handle the promise
59
promise
60
.then(result => console.log(result))
61
.catch(error => console.error(error));
62
```
63
64
## Architecture
65
66
Promise implements the complete Promises/A+ specification with several key architectural decisions:
67
68
- **Performance Optimized**: Uses `asap` library for optimal async scheduling
69
- **Standards Compliant**: Full Promises/A+ specification implementation
70
- **Extensible**: Modular design allowing selective feature inclusion
71
- **Environment Aware**: Support for domains, setImmediate, and browser environments
72
- **Type Safe**: Comprehensive TypeScript definitions included
73
74
## Capabilities
75
76
### Core Promise Implementation
77
78
Foundational Promise constructor and chaining methods following the Promises/A+ specification.
79
80
```javascript { .api }
81
function Promise(executor);
82
Promise.prototype.then(onFulfilled, onRejected);
83
```
84
85
[Core Promise](./core-promise.md)
86
87
### ES6 Static Methods
88
89
Standard ES6 Promise static methods for creating and combining promises.
90
91
```javascript { .api }
92
Promise.resolve(value);
93
Promise.reject(reason);
94
Promise.all(iterable);
95
Promise.allSettled(iterable);
96
Promise.race(iterable);
97
Promise.any(iterable);
98
```
99
100
[ES6 Static Methods](./es6-static-methods.md)
101
102
### Extension Methods
103
104
Additional instance methods that extend the core Promise functionality.
105
106
```javascript { .api }
107
Promise.prototype.catch(onRejected);
108
Promise.prototype.done(onFulfilled, onRejected);
109
Promise.prototype.finally(onFinally);
110
```
111
112
[Extension Methods](./extension-methods.md)
113
114
### Node.js Integration
115
116
Utilities for bridging callback-based APIs with promises in Node.js environments.
117
118
```javascript { .api }
119
Promise.denodeify(fn, argumentCount);
120
Promise.nodeify(fn);
121
Promise.prototype.nodeify(callback, ctx);
122
```
123
124
[Node.js Integration](./nodejs-integration.md)
125
126
### Synchronous Inspection
127
128
Optional methods for synchronously inspecting promise state (disabled by default).
129
130
```javascript { .api }
131
Promise.enableSynchronous();
132
Promise.disableSynchronous();
133
```
134
135
[Synchronous Inspection](./synchronous-inspection.md)
136
137
### Rejection Tracking
138
139
Development utilities for tracking and debugging unhandled promise rejections.
140
141
```javascript { .api }
142
const rejectionTracking = require('promise/lib/rejection-tracking');
143
rejectionTracking.enable(options);
144
rejectionTracking.disable();
145
```
146
147
[Rejection Tracking](./rejection-tracking.md)
148
149
## Types
150
151
```javascript { .api }
152
/**
153
* Promise constructor following Promises/A+ specification
154
* @param {function} executor - Function with resolve and reject parameters
155
*/
156
function Promise(executor);
157
158
/**
159
* Promise state values (internal)
160
* 0 - pending
161
* 1 - fulfilled
162
* 2 - rejected
163
* 3 - adopted (follows another promise)
164
*/
165
166
/**
167
* Result interface for fulfilled promises in allSettled
168
* @typedef {Object} PromiseFulfilledResult
169
* @property {"fulfilled"} status - Status indicator
170
* @property {*} value - The fulfillment value
171
*/
172
173
/**
174
* Result interface for rejected promises in allSettled
175
* @typedef {Object} PromiseRejectedResult
176
* @property {"rejected"} status - Status indicator
177
* @property {*} reason - The rejection reason
178
*/
179
180
/**
181
* Union type for promise settlement results
182
* @typedef {PromiseFulfilledResult|PromiseRejectedResult} PromiseSettledResult
183
*/
184
```