0
# Core Promise
1

2
Core Promise implementation following the Promises/A+ specification with optimized performance and reliability.
3

4
## Capabilities
5

6
### Promise Constructor
7

8
Creates a new Promise instance with an executor function.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Promise instance
13
 * @param {function} executor - Function called with (resolve, reject) parameters
14
 * @throws {TypeError} If not called with new or executor is not a function
15
 */
16
function Promise(executor);
17
```
18

19
**Usage Examples:**
20

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

24
// Basic promise creation
25
const promise = new Promise((resolve, reject) => {
26
  // Simulate async operation
27
  setTimeout(() => {
28
    if (Math.random() > 0.5) {
29
      resolve('Operation successful');
30
    } else {
31
      reject(new Error('Operation failed'));
32
    }
33
  }, 1000);
34
});
35

36
// Immediate resolution
37
const resolved = new Promise((resolve) => {
38
  resolve(42);
39
});
40

41
// Immediate rejection
42
const rejected = new Promise((resolve, reject) => {
43
  reject(new Error('Something went wrong'));
44
});
45
```
46

47
### Then Method
48

49
Attaches callbacks for promise resolution and/or rejection, returning a new promise.
50

51
```javascript { .api }
52
/**
53
 * Attaches fulfillment and/or rejection handlers
54
 * @param {function} [onFulfilled] - Called when promise is fulfilled
55
 * @param {function} [onRejected] - Called when promise is rejected
56
 * @returns {Promise} New promise for the result
57
 */
58
Promise.prototype.then(onFulfilled, onRejected);
59
```
60

61
**Usage Examples:**
62

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

66
// Basic chaining
67
promise
68
  .then(result => {
69
    console.log('Success:', result);
70
    return result * 2;
71
  })
72
  .then(doubled => {
73
    console.log('Doubled:', doubled);
74
  });
75

76
// Error handling with then
77
promise.then(
78
  result => console.log('Success:', result),
79
  error => console.error('Error:', error)
80
);
81

82
// Transformation
83
promise
84
  .then(data => JSON.parse(data))
85
  .then(parsed => parsed.users)
86
  .then(users => users.filter(u => u.active));
87
```
88

89
## Internal Properties
90

91
```javascript { .api }
92
/**
93
 * Internal static properties (do not use directly)
94
 */
95
Promise._onHandle;    // Internal handler for promise events
96
Promise._onReject;    // Internal handler for rejection events  
97
Promise._noop;        // Internal no-operation function
98
```
99

100
## Error Handling
101

102
The core Promise implementation includes sophisticated error handling:
103

104
- **Synchronous errors** in the executor are automatically caught and convert the promise to rejected
105
- **Type checking** ensures proper usage of constructor and methods
106
- **State immutability** prevents multiple resolution/rejection of the same promise
107
- **Exception isolation** prevents errors from escaping the promise chain
108

109
**Example:**
110

111
```javascript
112
// Synchronous errors are caught automatically
113
const promise = new Promise((resolve, reject) => {
114
  throw new Error('Synchronous error'); // Automatically becomes rejection
115
});
116

117
promise.catch(error => {
118
  console.log('Caught:', error.message); // "Synchronous error"
119
});
120
```