0
# Observable Transformation
1

2
Operators for transforming observable sequences including map, flatMap, scan, and buffer operations.
3

4
## Capabilities
5

6
### Map/Select
7

8
Transforms each element of an observable sequence.
9

10
```javascript { .api }
11
/**
12
 * Projects each element of an observable sequence into a new form
13
 * @param {function} selector - Transform function to apply to each element
14
 * @param {*} [thisArg] - Object to use as this when executing selector
15
 * @returns {Observable} Observable sequence with transformed elements
16
 */
17
observable.map = function(selector, thisArg);
18
observable.select = function(selector, thisArg); // Alias for map
19
```
20

21
**Usage Example:**
22

23
```javascript
24
var source = Rx.Observable.range(1, 5);
25
var doubled = source.map(function(x) { return x * 2; });
26
// Emits: 2, 4, 6, 8, 10
27
```
28

29
### FlatMap/SelectMany
30

31
Projects each element to an observable and flattens the result.
32

33
```javascript { .api }
34
/**
35
 * Projects each element to an observable and flattens the resulting sequences
36
 * @param {function} selector - Function that transforms each element into an observable
37
 * @param {function} [resultSelector] - Function to combine source and projected elements
38
 * @param {*} [thisArg] - Object to use as this when executing selector
39
 * @returns {Observable} Flattened observable sequence
40
 */
41
observable.flatMap = function(selector, resultSelector, thisArg);
42
observable.selectMany = function(selector, resultSelector, thisArg); // Alias
43
observable.mergeMap = function(selector, resultSelector, thisArg); // Alias
44
```
45

46
**Usage Example:**
47

48
```javascript
49
var source = Rx.Observable.range(1, 3);
50
var flattened = source.flatMap(function(x) {
51
  return Rx.Observable.range(x, 2);
52
});
53
// Emits: 1, 1, 2, 2, 3, 3
54
```
55

56
### FlatMapLatest/SwitchMap
57

58
Projects to observables and switches to the latest one.
59

60
```javascript { .api }
61
/**
62
 * Projects each element to an observable and switches to the latest observable
63
 * @param {function} selector - Function that transforms each element into an observable
64
 * @param {function} [resultSelector] - Function to combine source and projected elements
65
 * @param {*} [thisArg] - Object to use as this when executing selector
66
 * @returns {Observable} Observable sequence switching to latest projection
67
 */
68
observable.flatMapLatest = function(selector, resultSelector, thisArg);
69
observable.switchMap = function(selector, resultSelector, thisArg); // Alias
70
```
71

72
### FlatMapConcat/ConcatMap
73

74
Projects to observables and concatenates them sequentially.
75

76
```javascript { .api }
77
/**
78
 * Projects each element to an observable and concatenates sequences sequentially
79
 * @param {function} selector - Function that transforms each element into an observable
80
 * @param {function} [resultSelector] - Function to combine source and projected elements
81
 * @param {*} [thisArg] - Object to use as this when executing selector
82
 * @returns {Observable} Concatenated observable sequence
83
 */
84
observable.flatMapConcat = function(selector, resultSelector, thisArg);
85
observable.concatMap = function(selector, resultSelector, thisArg); // Alias
86
```
87

88
### FlatMapFirst/ExhaustMap
89

90
Projects to observables and ignores new projections while current is active.
91

92
```javascript { .api }
93
/**
94
 * Projects to observables, ignoring new ones while current observable is active
95
 * @param {function} selector - Function that transforms each element into an observable
96
 * @param {function} [resultSelector] - Function to combine source and projected elements
97
 * @param {*} [thisArg] - Object to use as this when executing selector
98
 * @returns {Observable} Observable sequence exhausting projections
99
 */
100
observable.flatMapFirst = function(selector, resultSelector, thisArg);
101
observable.exhaustMap = function(selector, resultSelector, thisArg); // Alias
102
```
103

104
### Scan
105

106
Applies an accumulator function over the sequence and returns each intermediate result.
107

108
```javascript { .api }
109
/**
110
 * Applies an accumulator function and emits each intermediate result
111
 * @param {function} accumulator - Accumulator function taking current accumulation and next value
112
 * @param {*} [seed] - Initial accumulator value
113
 * @returns {Observable} Observable sequence of accumulated values
114
 */
115
observable.scan = function(accumulator, seed);
116
```
117

118
**Usage Example:**
119

120
```javascript
121
var source = Rx.Observable.range(1, 5);
122
var accumulated = source.scan(function(acc, x) { return acc + x; }, 0);
123
// Emits: 0, 1, 3, 6, 10, 15
124
```
125

126
### StartWith
127

128
Prepends values to the beginning of the sequence.
129

130
```javascript { .api }
131
/**
132
 * Prepends a sequence of values to an observable sequence
133
 * @param {...*} values - Values to prepend to the sequence
134
 * @returns {Observable} Observable sequence with prepended values
135
 */
136
observable.startWith = function(...values);
137
```
138

139
**Usage Example:**
140

141
```javascript
142
var source = Rx.Observable.range(3, 3);
143
var withStart = source.startWith(1, 2);
144
// Emits: 1, 2, 3, 4, 5
145
```
146

147
### Pluck
148

149
Retrieves the value of a specified property from each element.
150

151
```javascript { .api }
152
/**
153
 * Retrieves the value of a specified property from all elements
154
 * @param {...(string|number)} properties - Property path to pluck
155
 * @returns {Observable} Observable sequence of plucked values
156
 */
157
observable.pluck = function(...properties);
158
```
159

160
**Usage Example:**
161

162
```javascript
163
var source = Rx.Observable.fromArray([
164
  {name: 'Alice', age: 25},
165
  {name: 'Bob', age: 30}
166
]);
167
var names = source.pluck('name');
168
// Emits: 'Alice', 'Bob'
169
```
170

171
### Buffer With Count
172

173
Buffers elements into arrays of specified size.
174

175
```javascript { .api }
176
/**
177
 * Buffers the source observable sequence elements into arrays of specified size
178
 * @param {number} count - Maximum element count of a buffer
179
 * @param {number} [skip] - Number of elements to skip between creation of consecutive buffers
180
 * @returns {Observable} Observable sequence of arrays
181
 */
182
observable.bufferWithCount = function(count, skip);
183
observable.bufferCount = function(count, skip); // Alias
184
```
185

186
**Usage Example:**
187

188
```javascript
189
var source = Rx.Observable.range(1, 10);
190
var buffered = source.bufferWithCount(3);
191
// Emits: [1,2,3], [4,5,6], [7,8,9], [10]
192
```
193

194
### Window With Count
195

196
Windows elements into observables of specified size.
197

198
```javascript { .api }
199
/**
200
 * Projects elements into zero or more windows of specified size
201
 * @param {number} count - Maximum element count of a window
202
 * @param {number} [skip] - Number of elements to skip between creation of consecutive windows
203
 * @returns {Observable} Observable sequence of observable windows
204
 */
205
observable.windowWithCount = function(count, skip);
206
observable.windowCount = function(count, skip); // Alias
207
```
208

209
### FlatMapObserver
210

211
Projects elements using separate functions for onNext, onError, and onCompleted.
212

213
```javascript { .api }
214
/**
215
 * Projects elements using observer method handlers
216
 * @param {function} onNext - Function to project next values
217
 * @param {function} onError - Function to project error values
218
 * @param {function} onCompleted - Function to project completion
219
 * @param {*} [thisArg] - Object to use as this when executing functions
220
 * @returns {Observable} Projected observable sequence
221
 */
222
observable.flatMapObserver = function(onNext, onError, onCompleted, thisArg);
223
```
224

225
### Concat All
226

227
Concatenates all inner observable sequences.
228

229
```javascript { .api }
230
/**
231
 * Concatenates all inner observable sequences sequentially
232
 * @returns {Observable} Observable sequence containing concatenated elements
233
 */
234
observable.concatAll = function();
235
```
236

237
### Merge All
238

239
Merges all inner observable sequences.
240

241
```javascript { .api }
242
/**
243
 * Merges all inner observable sequences into one sequence
244
 * @returns {Observable} Observable sequence containing merged elements
245
 */
246
observable.mergeAll = function();
247
```
248

249
### Switch/SwitchLatest
250

251
Switches to the latest inner observable sequence.
252

253
```javascript { .api }
254
/**
255
 * Transforms an observable of observables by switching to the latest observable
256
 * @returns {Observable} Observable sequence that switches to latest inner observable
257
 */
258
observable.switch = function();
259
observable.switchLatest = function(); // Alias
260
```
261

262
### Transduce
263

264
Applies a transducer to transform the observable sequence.
265

266
```javascript { .api }
267
/**
268
 * Applies a transducer to transform the observable sequence
269
 * @param {Object} transducer - Transducer object with @@transducer/step method
270
 * @returns {Observable} Transformed observable sequence
271
 */
272
observable.transduce = function(transducer);
273
```
274

275
### Catch/CatchError
276

277
Continues the observable sequence with another sequence on error.
278

279
```javascript { .api }
280
/**
281
 * Continues the observable sequence with another sequence on error
282
 * @param {function|Observable} handlerOrSecond - Error handler function or fallback observable
283
 * @returns {Observable} Observable sequence continuing on error
284
 */
285
observable.catch = function(handlerOrSecond);
286
observable.catchError = function(handlerOrSecond); // Alias
287
```
288

289
**Usage Example:**
290

291
```javascript
292
var source = Rx.Observable.throw(new Error('Oops!'));
293
var withCatch = source.catch(function(err) {
294
  return Rx.Observable.just('Recovered');
295
});
296
// Emits: 'Recovered'
297
```
298

299
### Retry
300

301
Repeats the observable sequence on error up to specified retry count.
302

303
```javascript { .api }
304
/**
305
 * Repeats the observable sequence on error up to specified retry count
306
 * @param {number} [retryCount] - Number of retries, infinite if not specified
307
 * @returns {Observable} Observable sequence that retries on error
308
 */
309
observable.retry = function(retryCount);
310
```
311

312
**Usage Example:**
313

314
```javascript
315
var source = someFailingObservable();
316
var withRetry = source.retry(3);
317
// Will retry up to 3 times before giving up
318
```
319

320
### RetryWhen
321

322
Repeats the observable sequence on error when the notifier emits a value.
323

324
```javascript { .api }
325
/**
326
 * Repeats the observable sequence on error when the notifier emits
327
 * @param {function} notificationHandler - Function that receives error notifications and returns an observable
328
 * @returns {Observable} Observable sequence that retries conditionally
329
 */
330
observable.retryWhen = function(notificationHandler);
331
```
332

333
**Usage Example:**
334

335
```javascript
336
var source = someFailingObservable();
337
var withRetryWhen = source.retryWhen(function(errors) {
338
  return errors.delay(1000); // Retry after 1 second delay
339
});
340
```
341

342
### OnErrorResumeNext
343

344
Continues with the next observable sequence on error.
345

346
```javascript { .api }
347
/**
348
 * Continues with the next observable sequence on error without propagating the error
349
 * @param {Observable} second - Observable sequence to continue with on error
350
 * @returns {Observable} Observable sequence that continues on error
351
 */
352
observable.onErrorResumeNext = function(second);
353
```
354

355
### Materialize
356

357
Wraps notifications in Notification objects.
358

359
```javascript { .api }
360
/**
361
 * Materializes the implicit notifications of an observable sequence as explicit notifications
362
 * @returns {Observable} Observable sequence of Notification objects
363
 */
364
observable.materialize = function();
365
```
366

367
### Dematerialize
368

369
Unwraps Notification objects back to notifications.
370

371
```javascript { .api }
372
/**
373
 * Dematerializes the explicit notifications of an observable sequence as implicit notifications
374
 * @returns {Observable} Observable sequence with dematerialized notifications
375
 */
376
observable.dematerialize = function();
377
```
378

379
### Do/Tap/DoAction
380

381
Performs side effects for each element without modifying the sequence.
382

383
```javascript { .api }
384
/**
385
 * Performs side effects for each element without modifying the sequence
386
 * @param {function|Observer} observerOrOnNext - Observer or onNext callback
387
 * @param {function} [onError] - OnError callback
388
 * @param {function} [onCompleted] - OnCompleted callback
389
 * @returns {Observable} Original observable sequence
390
 */
391
observable.do = function(observerOrOnNext, onError, onCompleted);
392
observable.tap = function(observerOrOnNext, onError, onCompleted); // Alias
393
observable.doAction = function(observerOrOnNext, onError, onCompleted); // Alias
394
```
395

396
**Usage Example:**
397

398
```javascript
399
var source = Rx.Observable.range(1, 3);
400
var withSideEffect = source
401
  .do(function(x) { console.log('Processing: ' + x); })
402
  .map(function(x) { return x * 2; });
403
// Logs: 'Processing: 1', 'Processing: 2', 'Processing: 3'
404
// Emits: 2, 4, 6
405
```
406

407
### DoOnNext/TapOnNext
408

409
Performs side effects for each next element.
410

411
```javascript { .api }
412
/**
413
 * Performs side effects for each next element
414
 * @param {function} onNext - Callback for next values
415
 * @param {*} [thisArg] - Object to use as this when executing callback
416
 * @returns {Observable} Original observable sequence
417
 */
418
observable.doOnNext = function(onNext, thisArg);
419
observable.tapOnNext = function(onNext, thisArg); // Alias
420
```
421

422
### DoOnError/TapOnError
423

424
Performs side effects for each error.
425

426
```javascript { .api }
427
/**
428
 * Performs side effects for each error
429
 * @param {function} onError - Callback for errors
430
 * @param {*} [thisArg] - Object to use as this when executing callback
431
 * @returns {Observable} Original observable sequence
432
 */
433
observable.doOnError = function(onError, thisArg);
434
observable.tapOnError = function(onError, thisArg); // Alias
435
```
436

437
### DoOnCompleted/TapOnCompleted
438

439
Performs side effects on sequence completion.
440

441
```javascript { .api }
442
/**
443
 * Performs side effects on sequence completion
444
 * @param {function} onCompleted - Callback for completion
445
 * @param {*} [thisArg] - Object to use as this when executing callback
446
 * @returns {Observable} Original observable sequence
447
 */
448
observable.doOnCompleted = function(onCompleted, thisArg);
449
observable.tapOnCompleted = function(onCompleted, thisArg); // Alias
450
```