0
# Async Operations
1

2
Methods for working with asynchronous patterns including callbacks, events, and promises.
3

4
## Capabilities
5

6
### From Callback
7

8
Creates an observable from a Node.js-style callback function.
9

10
```javascript { .api }
11
/**
12
 * Creates an observable from a function that uses Node.js callback pattern
13
 * @param {function} func - Function that takes arguments and a callback(error, result)
14
 * @param {*} [context] - Context to bind the function to
15
 * @param {function} [selector] - Function to transform the callback result
16
 * @returns {function} Function that returns an observable when called with arguments
17
 */
18
Rx.Observable.fromCallback = function(func, context, selector);
19
```
20

21
**Usage Example:**
22

23
```javascript
24
var fs = require('fs');
25
var readFile = Rx.Observable.fromCallback(fs.readFile);
26

27
var source = readFile('file.txt', 'utf8');
28
source.subscribe(
29
  function(data) { console.log('File contents: ' + data); },
30
  function(err) { console.log('Error: ' + err); }
31
);
32
```
33

34
### From Node Callback
35

36
Creates an observable from a Node.js-style callback with error-first pattern.
37

38
```javascript { .api }
39
/**
40
 * Creates an observable from a Node.js-style callback function
41
 * @param {function} func - Function that takes arguments and a callback(error, ...results)
42
 * @param {*} [context] - Context to bind the function to
43
 * @param {function} [selector] - Function to transform the callback results
44
 * @returns {function} Function that returns an observable when called with arguments
45
 */
46
Rx.Observable.fromNodeCallback = function(func, context, selector);
47
```
48

49
### From Event
50

51
Creates an observable from DOM events or EventEmitter events.
52

53
```javascript { .api }
54
/**
55
 * Creates an observable from DOM events or EventEmitter events
56
 * @param {Element|EventEmitter} element - DOM element or EventEmitter
57
 * @param {string} eventName - Name of the event to listen for
58
 * @param {function} [selector] - Function to transform the event object
59
 * @returns {Observable} Observable sequence of events
60
 */
61
Rx.Observable.fromEvent = function(element, eventName, selector);
62
```
63

64
**Usage Example:**
65

66
```javascript
67
var button = document.getElementById('myButton');
68
var clicks = Rx.Observable.fromEvent(button, 'click');
69

70
clicks.subscribe(function(event) {
71
  console.log('Button clicked!');
72
});
73
```
74

75
### From Event Pattern
76

77
Creates an observable from custom event patterns.
78

79
```javascript { .api }
80
/**
81
 * Creates an observable from a custom event pattern
82
 * @param {function} addHandler - Function to add event handler
83
 * @param {function} removeHandler - Function to remove event handler
84
 * @param {function} [selector] - Function to transform the event arguments
85
 * @returns {Observable} Observable sequence of events
86
 */
87
Rx.Observable.fromEventPattern = function(addHandler, removeHandler, selector);
88
```
89

90
**Usage Example:**
91

92
```javascript
93
var source = Rx.Observable.fromEventPattern(
94
  function(handler) { emitter.addListener('data', handler); },
95
  function(handler) { emitter.removeListener('data', handler); }
96
);
97
```
98

99
### From Promise
100

101
Creates an observable from a Promise.
102

103
```javascript { .api }
104
/**
105
 * Creates an observable from a Promise
106
 * @param {Promise} promise - Promise to convert to observable
107
 * @returns {Observable} Observable sequence that emits promise result
108
 */
109
Rx.Observable.fromPromise = function(promise);
110
```
111

112
**Usage Example:**
113

114
```javascript
115
var promise = fetch('/api/data');
116
var source = Rx.Observable.fromPromise(promise);
117

118
source.subscribe(
119
  function(response) { console.log('Response:', response); },
120
  function(error) { console.log('Error:', error); }
121
);
122
```
123

124
### To Promise
125

126
Converts an observable to a Promise.
127

128
```javascript { .api }
129
/**
130
 * Converts the observable sequence to a Promise
131
 * @param {function} [promiseCtor] - Promise constructor to use
132
 * @returns {Promise} Promise that resolves with the last emitted value
133
 */
134
observable.toPromise = function(promiseCtor);
135
```
136

137
**Usage Example:**
138

139
```javascript
140
var source = Rx.Observable.return(42);
141
var promise = source.toPromise();
142

143
promise.then(function(value) {
144
  console.log('Promise resolved with:', value);
145
});
146
```
147

148
### Spawn
149

150
Creates an observable from a generator function.
151

152
```javascript { .api }
153
/**
154
 * Creates an observable from a generator function using spawn-like behavior
155
 * @param {function} generatorFunction - Generator function to execute
156
 * @returns {Observable} Observable sequence from generator execution
157
 */
158
Rx.Observable.spawn = function(generatorFunction);
159
```
160

161
**Usage Example:**
162

163
```javascript
164
var source = Rx.Observable.spawn(function* () {
165
  var a = yield Rx.Observable.return(1);
166
  var b = yield Rx.Observable.return(2);
167
  return a + b;
168
});
169
```
170

171
### Start
172

173
Invokes a function asynchronously and returns the result as an observable.
174

175
```javascript { .api }
176
/**
177
 * Invokes a function asynchronously and returns the result as an observable
178
 * @param {function} func - Function to execute asynchronously
179
 * @param {*} [context] - Context to bind the function to
180
 * @param {Scheduler} [scheduler] - Scheduler to execute the function on
181
 * @returns {Observable} Observable sequence containing the function result
182
 */
183
Rx.Observable.start = function(func, context, scheduler);
184
```
185

186
### To Async
187

188
Converts a function to return an observable instead of calling a callback.
189

190
```javascript { .api }
191
/**
192
 * Converts a function to return an observable instead of using callbacks
193
 * @param {function} func - Function to convert
194
 * @param {*} [context] - Context to bind the function to
195
 * @param {Scheduler} [scheduler] - Scheduler to execute on
196
 * @returns {function} Function that returns an observable
197
 */
198
Rx.Observable.toAsync = function(func, context, scheduler);
199
```
200

201
### Start Async
202

203
Starts an async function and returns the result as an observable.
204

205
```javascript { .api }
206
/**
207
 * Starts an async function and returns the result as an observable
208
 * @param {function} functionAsync - Async function that returns a Promise
209
 * @returns {Observable} Observable sequence containing the async function result
210
 */
211
Rx.Observable.startAsync = function(functionAsync);
212
```
213

214
### Wrap
215

216
Wraps a function to work with observables.
217

218
```javascript { .api }
219
/**
220
 * Wraps a function to work with observables
221
 * @param {function} fn - Function to wrap
222
 * @returns {function} Wrapped function that works with observables
223
 */
224
Rx.Observable.wrap = function(fn);
225
```
226

227
## Error Handling with Async Operations
228

229
Async operations integrate with RxJS error handling:
230

231
```javascript { .api }
232
/**
233
 * Handles errors from async operations
234
 * @param {function} handler - Error handling function that returns an observable
235
 * @returns {Observable} Observable sequence with error handling
236
 */
237
observable.catch = function(handler);
238

239
/**
240
 * Retries the async operation on error
241
 * @param {number} [retryCount] - Number of retry attempts
242
 * @returns {Observable} Observable sequence with retry logic
243
 */
244
observable.retry = function(retryCount);
245
```
246

247
**Usage Example:**
248

249
```javascript
250
var source = Rx.Observable.fromPromise(fetch('/api/data'))
251
  .retry(3)
252
  .catch(function(error) {
253
    return Rx.Observable.return({error: 'Failed to fetch data'});
254
  });
255
```