0
# RSVP.js
1

2
RSVP.js provides simple tools for organizing asynchronous code. It is a lightweight implementation of Promises/A+ specification that works in both Node.js and browsers (IE9+), bringing additional utilities beyond the standard ES6 Promise API.
3

4
## Package Information
5

6
- **Package Name**: rsvp
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES5 compatible)
9
- **Installation**: `npm install rsvp`
10

11
## Core Imports
12

13
```javascript
14
import RSVP from "rsvp";
15
import { Promise, all, hash, resolve, reject } from "rsvp";
16
```
17

18
For CommonJS:
19

20
```javascript
21
var RSVP = require("rsvp");
22
var Promise = RSVP.Promise;
23
```
24

25
For browsers via CDN:
26

27
```html
28
<script src="https://cdn.jsdelivr.net/npm/rsvp@4/dist/rsvp.min.js"></script>
29
```
30

31
## Basic Usage
32

33
```javascript
34
import { Promise, all, hash, resolve } from "rsvp";
35

36
// Create a promise
37
const promise = new Promise(function(resolve, reject) {
38
  // async operation
39
  setTimeout(() => resolve("Success!"), 1000);
40
});
41

42
promise.then(function(value) {
43
  console.log(value); // "Success!"
44
}).catch(function(error) {
45
  console.error(error);
46
});
47

48
// Wait for multiple promises
49
all([
50
  resolve(1),
51
  resolve(2),
52
  resolve(3)
53
]).then(function(values) {
54
  console.log(values); // [1, 2, 3]
55
});
56

57
// Work with object of promises
58
hash({
59
  users: fetchUsers(),
60
  posts: fetchPosts()
61
}).then(function(results) {
62
  console.log(results.users);
63
  console.log(results.posts);
64
});
65
```
66

67
## Architecture
68

69
RSVP.js is built around several key components:
70

71
- **Promise Class**: ES6-compliant Promise implementation with additional methods
72
- **Array Utilities**: Functions for working with arrays of promises (`all`, `allSettled`, `race`, `map`, `filter`)
73
- **Object Utilities**: Functions for working with objects containing promises (`hash`, `hashSettled`)
74
- **Node.js Integration**: Utilities for converting callback-based functions to promises (`denodeify`)
75
- **Configuration System**: Global configuration and instrumentation capabilities
76
- **Event System**: EventTarget implementation for custom events and promise instrumentation
77
- **Async Scheduling**: Cross-platform async scheduling using the best available method
78

79
## Capabilities
80

81
### Promise Class
82

83
Core Promise implementation following Promises/A+ specification with additional methods like `finally`.
84

85
```javascript { .api }
86
class Promise {
87
  constructor(resolver: Function, label?: string);
88
  then(onFulfillment?: Function, onRejection?: Function, label?: string): Promise;
89
  catch(onRejection: Function, label?: string): Promise;
90
  finally(callback: Function, label?: string): Promise;
91
  
92
  static all(array: Array, label?: string): Promise;
93
  static race(array: Array, label?: string): Promise;
94
  static resolve(value?: any, label?: string): Promise;
95
  static reject(reason?: any, label?: string): Promise;
96
}
97
```
98

99
[Promise Class](./promise.md)
100

101
### Array Promise Utilities
102

103
Functions for working with arrays of promises including parallel execution, racing, transformation, and filtering.
104

105
```javascript { .api }
106
function all(array: Array, label?: string): Promise;
107
function allSettled(entries: Array, label?: string): Promise;
108
function race(array: Array, label?: string): Promise;
109
function map(promises: Array, mapFn: Function, label?: string): Promise;
110
function filter(promises: Array, filterFn: Function, label?: string): Promise;
111
```
112

113
[Array Utilities](./array-utilities.md)
114

115
### Object Promise Utilities
116

117
Functions for working with objects containing promises, useful for handling named async operations.
118

119
```javascript { .api }
120
function hash(object: Object, label?: string): Promise;
121
function hashSettled(object: Object, label?: string): Promise;
122
```
123

124
[Object Utilities](./object-utilities.md)
125

126
### Node.js Integration
127

128
Convert Node.js callback-style functions to promise-returning functions for better async composition.
129

130
```javascript { .api }
131
function denodeify(nodeFunc: Function, options?: boolean | Array): Function;
132
```
133

134
[Node.js Integration](./node-integration.md)
135

136
### Configuration and Events
137

138
Global configuration system and event handling for instrumentation and debugging.
139

140
```javascript { .api }
141
function configure(name: string, value?: any): any;
142
function on(...arguments): void;
143
function off(...arguments): void;
144

145
const EventTarget: {
146
  mixin(object: Object): Object;
147
  on(eventName: string, callback: Function): void;
148
  off(eventName: string, callback?: Function): void;
149
  trigger(eventName: string, options?: any, label?: string): void;
150
};
151
```
152

153
[Configuration and Events](./configuration.md)
154

155
### Utility Functions
156

157
Additional utility functions for promise creation, error handling, and async scheduling.
158

159
```javascript { .api }
160
function resolve(value?: any, label?: string): Promise;
161
function reject(reason?: any, label?: string): Promise;
162
function defer(label?: string): Object;
163
function rethrow(reason: any): void;
164
function asap(callback: Function, arg?: any): void;
165
function async(callback: Function, arg?: any): void;
166
```
167

168
[Utility Functions](./utilities.md)
169

170
## Types
171

172
```javascript { .api }
173
interface PromiseState {
174
  state: 'fulfilled' | 'rejected';
175
  value?: any;
176
  reason?: any;
177
}
178

179
interface DeferredObject {
180
  promise: Promise;
181
  resolve: Function;
182
  reject: Function;
183
}
184
```