0
# Configuration and Events
1

2
Global configuration system and event handling for instrumentation, debugging, and custom event management in RSVP.js.
3

4
## Capabilities
5

6
### Configuration System
7

8
#### configure
9

10
Set or get global configuration options for RSVP.js behavior.
11

12
```javascript { .api }
13
/**
14
 * Set or get configuration values
15
 * @param name - Configuration property name
16
 * @param value - Value to set (omit to get current value)
17
 * @returns Current value when getting, undefined when setting
18
 */
19
function configure(name: string, value?: any): any;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
import { configure } from "rsvp";
26

27
// Enable instrumentation for debugging
28
configure('instrument', true);
29

30
// Set custom async scheduler
31
configure('async', function(callback, arg) {
32
  setTimeout(callback, 0, arg);
33
});
34

35
// Set after callback for cleanup
36
configure('after', function(callback) {
37
  process.nextTick(callback);
38
});
39

40
// Get current configuration values
41
const isInstrumented = configure('instrument'); // true/false
42
const asyncFn = configure('async'); // current async function
43
```
44

45
### Global Event System
46

47
#### on
48

49
Register global event listeners for promise lifecycle events.
50

51
```javascript { .api }
52
/**
53
 * Register global event listener
54
 * @param eventName - Name of event to listen for
55
 * @param callback - Function to call when event occurs
56
 */
57
function on(eventName: string, callback: Function): void;
58
```
59

60
#### off
61

62
Remove global event listeners.
63

64
```javascript { .api }
65
/**
66
 * Remove global event listener
67
 * @param eventName - Name of event to stop listening for
68
 * @param callback - Specific callback to remove (optional)
69
 */
70
function off(eventName: string, callback?: Function): void;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
import { on, off, configure } from "rsvp";
77

78
// Enable instrumentation first
79
configure('instrument', true);
80

81
// Listen for promise creation
82
on('created', function(event) {
83
  console.log('Promise created:', event);
84
});
85

86
// Listen for promise fulfillment
87
on('fulfilled', function(event) {
88
  console.log('Promise fulfilled:', event);
89
});
90

91
// Listen for promise rejection
92
on('rejected', function(event) {
93
  console.error('Promise rejected:', event);
94
});
95

96
// Listen for errors
97
on('error', function(reason, label) {
98
  console.error('Unhandled promise error:', reason, label);
99
});
100

101
// Remove specific listener
102
function myHandler(event) { /* ... */ }
103
on('created', myHandler);
104
off('created', myHandler);
105

106
// Remove all listeners for an event
107
off('created');
108
```
109

110
### EventTarget System
111

112
#### EventTarget Object
113

114
Provides mixin capabilities and direct event handling for custom objects.
115

116
```javascript { .api }
117
/**
118
 * EventTarget object with mixin and direct event methods
119
 */
120
const EventTarget: {
121
  /**
122
   * Add EventTarget methods to an object
123
   * @param object - Object to extend with event methods
124
   * @returns The extended object
125
   */
126
  mixin(object: Object): Object;
127
  
128
  /**
129
   * Register event listener
130
   * @param eventName - Name of event to listen for
131
   * @param callback - Function to call when event occurs
132
   */
133
  on(eventName: string, callback: Function): void;
134
  
135
  /**
136
   * Remove event listener
137
   * @param eventName - Name of event to stop listening for
138
   * @param callback - Specific callback to remove (optional)
139
   */
140
  off(eventName: string, callback?: Function): void;
141
  
142
  /**
143
   * Trigger event with optional data
144
   * @param eventName - Name of event to trigger
145
   * @param options - Data to pass to event listeners
146
   * @param label - Optional label for debugging
147
   */
148
  trigger(eventName: string, options?: any, label?: string): void;
149
};
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
import { EventTarget } from "rsvp";
156

157
// Add event capabilities to an object
158
const myObject = {};
159
EventTarget.mixin(myObject);
160

161
myObject.on('customEvent', function(data) {
162
  console.log('Custom event received:', data);
163
});
164

165
myObject.trigger('customEvent', { message: 'Hello World' });
166

167
// Add event capabilities to a prototype
168
function MyClass() {}
169
EventTarget.mixin(MyClass.prototype);
170

171
const instance1 = new MyClass();
172
const instance2 = new MyClass();
173

174
instance1.on('update', function(data) {
175
  console.log('Instance 1 updated:', data);
176
});
177

178
instance2.on('update', function(data) {
179
  console.log('Instance 2 updated:', data);
180
});
181

182
instance1.trigger('update', { value: 42 });
183
instance2.trigger('update', { value: 99 });
184
```
185

186
## Instrumentation and Debugging
187

188
### Browser Instrumentation
189

190
RSVP.js automatically sets up instrumentation if `window.__PROMISE_INSTRUMENTATION__` exists:
191

192
```html
193
<script>
194
  // Set up instrumentation before loading RSVP
195
  window.__PROMISE_INSTRUMENTATION__ = {
196
    created: function(event) {
197
      console.log('Promise created:', event);
198
    },
199
    fulfilled: function(event) {
200
      console.log('Promise fulfilled:', event);
201
    },
202
    rejected: function(event) {
203
      console.error('Promise rejected:', event);
204
    }
205
  };
206
</script>
207
<script src="rsvp.js"></script>
208
```
209

210
### Custom Instrumentation
211

212
```javascript
213
import { configure, on } from "rsvp";
214

215
// Enable instrumentation
216
configure('instrument', true);
217

218
// Track promise statistics
219
const promiseStats = {
220
  created: 0,
221
  fulfilled: 0,
222
  rejected: 0
223
};
224

225
on('created', () => promiseStats.created++);
226
on('fulfilled', () => promiseStats.fulfilled++);
227
on('rejected', () => promiseStats.rejected++);
228

229
// Log stats periodically
230
setInterval(() => {
231
  console.log('Promise stats:', promiseStats);
232
}, 5000);
233
```
234

235
### Error Tracking
236

237
```javascript
238
import { on, configure } from "rsvp";
239

240
configure('instrument', true);
241

242
// Global error handler for unhandled promise rejections
243
on('error', function(reason, label) {
244
  // Send to error tracking service
245
  errorTracker.captureException(reason, {
246
    tags: { source: 'rsvp-promise' },
247
    extra: { label: label }
248
  });
249
});
250

251
// Track specific error patterns
252
on('rejected', function(event) {
253
  if (event.detail && event.detail.reason) {
254
    const error = event.detail.reason;
255
    if (error.name === 'TimeoutError') {
256
      metrics.increment('promise.timeout');
257
    }
258
  }
259
});
260
```
261

262
## Configuration Options
263

264
### Available Configuration Keys
265

266
- **`instrument`** (boolean): Enable/disable promise instrumentation
267
- **`async`** (function): Custom function for scheduling async callbacks
268
- **`after`** (function): Custom function for scheduling after-callbacks
269

270
### Default Configuration
271

272
```javascript
273
// RSVP.js default configuration
274
configure('instrument', false);
275
configure('async', asapFunction); // Platform-specific async scheduling
276
configure('after', function(callback) {
277
  setTimeout(callback, 0);
278
});
279
```
280

281
### Custom Async Scheduling
282

283
```javascript
284
import { configure } from "rsvp";
285

286
// Use setImmediate in Node.js
287
if (typeof setImmediate !== 'undefined') {
288
  configure('async', function(callback, arg) {
289
    setImmediate(callback, arg);
290
  });
291
}
292

293
// Use MessageChannel in web workers
294
if (typeof MessageChannel !== 'undefined') {
295
  const channel = new MessageChannel();
296
  const callbacks = [];
297
  
298
  channel.port1.onmessage = function() {
299
    const callback = callbacks.shift();
300
    if (callback) callback();
301
  };
302
  
303
  configure('async', function(callback, arg) {
304
    callbacks.push(() => callback(arg));
305
    channel.port2.postMessage(null);
306
  });
307
}
308
```
309

310
## Event Types
311

312
### Promise Lifecycle Events
313

314
- **`created`**: Fired when a new promise is created
315
- **`fulfilled`**: Fired when a promise is fulfilled
316
- **`rejected`**: Fired when a promise is rejected
317
- **`error`**: Fired for unhandled promise errors
318

319
### Event Data Structure
320

321
Events typically include:
322
- `detail`: Object with promise information
323
- `label`: Optional debugging label
324
- `reason`: Error reason (for rejection/error events)
325
- `value`: Fulfillment value (for fulfilled events)