Mirror: 🎩 A tiny but capable push & pull stream library for TypeScript and Flow
Document all wonka operators. (#24)
authored by
Parker Ziegler
and committed by
Phil Plückthun
d5bd69aa
857b41c4
+195
-97
+195
-97
docs/api/operators.md
+195
-97
docs/api/operators.md
···
10
10
`combine` two sources together to a single source. The emitted value will be a combination of the two sources, with all values from the first source being emitted with the first value of the second source _before_ values of the second source are emitted.
11
11
12
12
```reason
13
-
open Wonka;
14
-
open Wonka_sources;
15
-
open Wonka_operators;
16
-
open Wonka_sinks;
13
+
let sourceOne = Wonka.fromArray([|1, 2, 3|]);
14
+
let sourceTwo = Wonka.fromArray([|4, 5, 6|]);
17
15
18
-
let sourceOne = fromArray([|1, 2, 3|]);
19
-
let sourceTwo = fromArray([|4, 5, 6|]);
20
-
21
-
combine(sourceOne, sourceTwo)
22
-
|> subscribe((. (_valOne, _valTwo)) => print_int(_valOne + _valTwo));
16
+
Wonka.combine(sourceOne, sourceTwo)
17
+
|> Wonka.subscribe((. (_valOne, _valTwo)) => print_int(_valOne + _valTwo));
23
18
24
19
/* Prints 56789 (1+4, 2+4, 3+4, 3+5, 3+6) to the console. */
25
20
```
···
45
40
`concat` will combine two sources together, subscribing to the next source after the previous source completes.
46
41
47
42
```reason
48
-
open Wonka;
49
-
open Wonka_sources;
50
-
open Wonka_operators;
51
-
open Wonka_sinks;
43
+
let sourceOne = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
44
+
let sourceTwo = Wonka.fromArray([|6, 5, 4, 3, 2, 1|]);
52
45
53
-
let sourceOne = fromArray([|1, 2, 3, 4, 5, 6|]);
54
-
let sourceTwo = fromArray([|6, 5, 4, 3, 2, 1|]);
55
-
56
-
concat([|sourceOne, sourceTwo|]) |> subscribe((. _val) => print_int(_val));
46
+
Wonka.concat([|sourceOne, sourceTwo|]) |> Wonka.subscribe((. _val) => print_int(_val));
57
47
58
48
/* Prints 1 2 3 4 5 6 6 5 4 3 2 1 to the console. */
59
49
```
···
74
64
// Prints 1 2 3 4 5 6 6 5 4 3 2 1 to the console.
75
65
```
76
66
67
+
## concatMap
68
+
69
+
`concatMap` allows you to map values of an outer source to an inner source. The sink will not dispatch the `Pull` signal until the previous value has been emitted. This is in contrast to `mergeMap`, which will dispatch the `Pull` signal for new values even if the previous value has not yet been emitted.
70
+
71
+
```reason
72
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
73
+
74
+
source
75
+
|> Wonka.concatMap((. _val) =>
76
+
Wonka.delay(_val * 1000, Wonka.fromValue(_val))
77
+
)
78
+
|> Wonka.subscribe((. _val) => print_int(_val));
79
+
80
+
/* After 1s, 1 will be emitted. After an additional 2s, 2 will be emitted.
81
+
After an additional 3s, 3 will be emitted. After an additional 4s, 4 will be emitted.
82
+
After an additional 5s, 5 will be emitted. After an additional 6s, 6 will be emitted. */
83
+
```
84
+
85
+
```typescript
86
+
import { fromArray, pipe, concatMap, delay, fromValue, subscribe } from 'wonka';
87
+
88
+
const source = fromArray([1, 2, 3, 4, 5, 6]);
89
+
90
+
pipe(
91
+
source,
92
+
concatMap(val => {
93
+
return pipe(
94
+
fromValue(val),
95
+
delay(val * 1000)
96
+
);
97
+
}),
98
+
subscribe(val => {
99
+
console.log(val);
100
+
})
101
+
);
102
+
```
103
+
77
104
## filter
78
105
79
106
`filter` will remove values from a source by passing them through an iteratee that returns a `bool`.
80
107
81
108
```reason
82
-
open Wonka;
83
-
open Wonka_sources;
84
-
open Wonka_operators;
85
-
open Wonka_sinks;
86
-
87
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
109
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
88
110
let isEven = (. n) => n mod 2 === 0;
89
111
90
-
source |> filter(isEven) |> subscribe((. _val) => print_int(_val));
112
+
source |> Wonka.filter(isEven) |> Wonka.subscribe((. _val) => print_int(_val));
91
113
92
114
/* Prints 246 to the console. */
93
115
```
···
114
136
`map` will transform values from a source by passing them through an iteratee that returns a new value.
115
137
116
138
```reason
117
-
open Wonka;
118
-
open Wonka_sources;
119
-
open Wonka_operators;
120
-
open Wonka_sinks;
121
-
122
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
139
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
123
140
let square = (. n) => n * n;
124
141
125
-
source |> map(square) |> subscribe((. _val) => print_int(_val));
142
+
source |> Wonka.map(square) |> Wonka.subscribe((. _val) => print_int(_val));
126
143
127
144
/* Prints 1 4 9 16 25 36 to the console. */
128
145
```
···
149
166
`merge` two sources together into a single source.
150
167
151
168
```reason
152
-
open Wonka;
153
-
open Wonka_sources;
154
-
open Wonka_operators;
155
-
open Wonka_sinks;
169
+
let sourceA = Wonka.fromArray([|1, 2, 3|]);
170
+
let sourceB = Wonka.fromArray([|4, 5, 6|]);
156
171
157
-
let sourceA = fromArray([|1, 2, 3|]);
158
-
let sourceB = fromArray([|4, 5, 6|]);
159
-
160
-
merge([|sourceA, sourceB|]) |> subscribe((. _val) => print_int(_val));
172
+
Wonka.merge([|sourceA, sourceB|]) |> Wonka.subscribe((. _val) => print_int(_val));
161
173
162
174
/* Prints 1 2 3 4 5 6 to the console.
163
175
```
···
183
195
Run a callback when the `End` signal has been sent to the sink by the source, whether by way of the talkback passing the `End` signal or the source being exhausted of values.
184
196
185
197
```reason
186
-
open Wonka;
187
-
open Wonka_operators;
188
-
open Wonka_sinks;
189
-
open WonkaJs;
190
-
191
198
let promiseOne =
192
199
Js.Promise.make((~resolve, ~reject as _) =>
193
200
Js.Global.setTimeout(() => resolve(. "ResolveOne"), 1000) |> ignore
···
198
205
Js.Global.setTimeout(() => resolve(. "ResolveTwo"), 2000) |> ignore
199
206
);
200
207
201
-
let sourceOne = fromPromise(promiseOne);
202
-
let sourceTwo = fromPromise(promiseTwo);
203
-
let source = concat([|sourceOne, sourceTwo|]);
208
+
let sourceOne = Wonka.fromPromise(promiseOne);
209
+
let sourceTwo = Wonka.fromPromise(promiseTwo);
210
+
let source = Wonka.concat([|sourceOne, sourceTwo|]);
204
211
205
212
source
206
-
|> onEnd((.) => print_endline("onEnd"))
207
-
|> subscribe((. _val) => print_endline(_val));
213
+
|> Wonka.onEnd((.) => print_endline("onEnd"))
214
+
|> Wonka.subscribe((. _val) => print_endline(_val));
215
+
208
216
/* Logs ResolveOne after one second, then ResolveTwo after an additional second, then onEnd immediately. */
209
217
```
210
218
···
244
252
Run a callback on each `Push` signal sent to the sink by the source.
245
253
246
254
```reason
247
-
open Wonka;
248
-
open Wonka_sources;
249
-
open Wonka_operators;
250
-
open Wonka_sinks;
255
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
251
256
252
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
253
-
254
-
source
255
-
|> onPush((. _val) => print_string({j|Push $_val|j}))
256
-
|> subscribe((. _val) => print_int(_val));
257
+
Wonka.source
258
+
|> Wonka.onPush((. _val) => print_string({j|Push $_val|j}))
259
+
|> Wonka.subscribe((. _val) => print_int(_val));
257
260
258
261
/* Prints Push 1 1 Push 2 2 Push 3 3 Push 4 4 Push 5 5 Push 6 6 to the console. */
259
262
```
···
281
284
Run a callback when the `Start` signal is sent to the sink by the source.
282
285
283
286
```reason
284
-
open Wonka;
285
-
open Wonka_operators;
286
-
open Wonka_sinks;
287
-
open WonkaJs;
288
-
289
287
let promise =
290
288
Js.Promise.make((~resolve, ~reject as _) =>
291
289
Js.Global.setTimeout(() => resolve(. "Resolve"), 1000) |> ignore
292
290
);
293
291
294
-
let source = fromPromise(promise);
292
+
let source = Wonka.fromPromise(promise);
295
293
296
294
source
297
-
|> onStart((.) => print_endline("onStart"))
298
-
|> subscribe((. _val) => print_endline(_val));
295
+
|> Wonka.onStart((.) => print_endline("onStart"))
296
+
|> Wonka.subscribe((. _val) => print_endline(_val));
299
297
300
298
/* Logs onStart to the console, pauses for one second to allow the timeout to finish,
301
299
then logs "Resolve" to the console. */
···
331
329
Accumulate emitted values of a source in a accumulator, similar to JavaScript `reduce`.
332
330
333
331
```reason
334
-
open Wonka;
335
-
open Wonka_sources;
336
-
open Wonka_operators;
337
-
open Wonka_sinks;
338
-
339
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
332
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
340
333
341
334
source
342
-
|> scan((. acc, x) => acc + x, 0)
343
-
|> subscribe((. _val) => print_int(_val));
335
+
|> Wonka.scan((. acc, x) => acc + x, 0)
336
+
|> Wonka.subscribe((. _val) => print_int(_val));
344
337
/* Prints 1 3 6 10 15 21 to the console. */
345
338
```
346
339
···
365
358
`skip` the specified number of emissions from the source.
366
359
367
360
```reason
368
-
open Wonka;
369
-
open Wonka_sources;
370
-
open Wonka_operators;
371
-
open Wonka_sinks;
372
-
373
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
361
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
374
362
375
-
source |> skip(2) |> subscribe((. _val) => print_int(_val));
363
+
source |> Wonka.skip(2) |> Wonka.subscribe((. _val) => print_int(_val));
376
364
377
365
/* Prints 3 4 5 6 to the console, since the first two emissions from the source were skipped.
378
366
```
···
396
384
Skip emissions from an outer source until an inner source (notifier) emits.
397
385
398
386
```reason
399
-
open Wonka;
400
-
open Wonka_operators;
401
-
open Wonka_sinks;
402
-
open WonkaJs;
387
+
let source = Wonka.interval(100);
388
+
let notifier = Wonka.interval(500);
403
389
404
-
let source = interval(100);
405
-
let notifier = interval(500);
406
-
407
-
source |> skipUntil(notifier) |> subscribe((. _val) => print_int(_val));
390
+
source |> Wonka.skipUntil(notifier) |> Wonka.subscribe((. _val) => print_int(_val));
408
391
409
392
/* Skips all values emitted by source (0, 1, 2, 3) until notifier emits at 500ms.
410
393
Then logs 4 5 6 7 8 9 10... to the console every 500ms. */
···
433
416
Skip values emitted from the source while they return `true` for the provided predicate function.
434
417
435
418
```reason
436
-
open Wonka;
437
-
open Wonka_operators;
438
-
open Wonka_sources;
439
-
open Wonka_sinks;
440
-
441
-
let source = fromArray([|1, 2, 3, 4, 5, 6|]);
419
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
442
420
443
421
source
444
-
|> skipWhile((. _val) => _val < 5)
445
-
|> subscribe((. _val) => print_int(_val));
422
+
|> Wonka.skipWhile((. _val) => _val < 5)
423
+
|> Wonka.subscribe((. _val) => print_int(_val));
446
424
447
425
/* Prints 5 6 to the console, as 1 2 3 4 all return true for the predicate function. */
448
426
```
···
462
440
463
441
// Prints 5 6 to the console, as 1 2 3 4 all return true for the predicate function.
464
442
```
443
+
444
+
## take
445
+
446
+
`take` only a specified number of emissions from the source before completing. `take` is the opposite of `skip`.
447
+
448
+
```reason
449
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
450
+
451
+
source |> Wonka.take(3) |> Wonka.subscribe((. _val) => print_int(_val));
452
+
453
+
/* Prints 1 2 3 to the console. */
454
+
```
455
+
456
+
```typescript
457
+
import { fromArray, pipe, take, subscribe } from 'wonka';
458
+
459
+
const source = fromArray([1, 2, 3, 4, 5, 6]);
460
+
461
+
pipe(
462
+
source,
463
+
take(3),
464
+
subscribe(val => {
465
+
console.log(val);
466
+
})
467
+
);
468
+
469
+
// Prints 1 2 3 to the console.
470
+
```
471
+
472
+
## takeLast
473
+
474
+
`takeLast` will take only the last n emissions from the source.
475
+
476
+
```reason
477
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
478
+
479
+
source |> Wonka.takeLast(3) |> Wonka.subscribe((. _val) => print_int(_val));
480
+
481
+
/* Prints 4 5 6 to the console. */
482
+
```
483
+
484
+
```typescript
485
+
import { fromArray, pipe, takeLast, subscribe } from 'wonka';
486
+
487
+
const source = fromArray([1, 2, 3, 4, 5, 6]);
488
+
489
+
pipe(
490
+
source,
491
+
takeLast(3),
492
+
subscribe(val => {
493
+
console.log(val);
494
+
})
495
+
);
496
+
497
+
// Prints 4 5 6 to the console.
498
+
```
499
+
500
+
## takeUntil
501
+
502
+
Take emissions from an outer source until an inner source (notifier) emits.
503
+
504
+
```reason
505
+
let source = Wonka.interval(100);
506
+
let notifier = Wonka.interval(500);
507
+
508
+
source
509
+
|> Wonka.takeUntil(notifier)
510
+
|> Wonka.subscribe((. _val) => print_int(_val));
511
+
512
+
/* Pauses 100ms, prints 0, pauses 100ms, prints 1, pauses 100ms, prints 2, pauses 100ms,
513
+
prints 3, pauses 100, then completes (notifier emits). */
514
+
```
515
+
516
+
```typescript
517
+
import { interval, pipe, takeUntil, subscribe } from 'wonka';
518
+
519
+
const source = interval(100);
520
+
const notifier = interval(500);
521
+
522
+
pipe(
523
+
source,
524
+
takeUntil(notifier),
525
+
subscribe(val => {
526
+
console.log(val);
527
+
})
528
+
);
529
+
530
+
// Pauses 100ms, prints 0, pauses 100ms, prints 1, pauses 100ms, prints 2, pauses 100ms,
531
+
// prints 3, pauses 100, then completes (notifier emits).
532
+
```
533
+
534
+
## takeWhile
535
+
536
+
Take emissions from the stream while they return `true` for the provided predicate function. If the first emission does not return `true`, no values will be `Push`ed to the sink.
537
+
538
+
```reason
539
+
let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]);
540
+
541
+
source
542
+
|> Wonka.takeWhile((. _val) => _val < 5)
543
+
|> Wonka.subscribe((. _val) => print_int(_val));
544
+
545
+
/* Prints 1 2 3 4 to the console. */
546
+
```
547
+
548
+
```typescript
549
+
import { pipe, fromArray, takeWhile, subscribe } from 'wonka';
550
+
551
+
const source = fromArray([1, 2, 3, 4, 5, 6]);
552
+
553
+
pipe(
554
+
source,
555
+
takeWhile(val => val < 5),
556
+
subscribe(val => {
557
+
console.log(val);
558
+
})
559
+
);
560
+
561
+
// Prints 1 2 3 4 to the console.
562
+
```