Mirror: 🎩 A tiny but capable push & pull stream library for TypeScript and Flow
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

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
··· 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 + ```