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
```