+20 -53

README.md

reviewed

··· 26 26 27 27  28 28 29 29 - * [What is `Wonka`](#what-is-wonka) 30 30 - * [Why it exists](#why-it-exists) 31 31 - * [Installation](#installation) 32 32 - * [Getting Started](#getting-started) 33 33 - * [Documentation (In Progress)](#documentation) 29 29 + Wonka is a lightweight iterable and observable library loosely based on 30 30 + the [callbag spec](https://github.com/callbag/callbag). It exposes a set of helpers to create streams, 31 31 + which are sources of multiple values, which allow you to create, transform 32 32 + and consume event streams or iterable sets of data. 34 33 35 35 - ## What is `Wonka` 34 34 + Wonka is written in [Reason](https://reasonml.github.io/), a dialect of OCaml, and can hence be used 35 35 + for native applications. It is also compiled using [BuckleScript](https://bucklescript.github.io) to plain 36 36 + JavaScript and has typings for [TypeScript](https://www.typescriptlang.org/) and [Flow](https://flow.org/). 36 37 37 37 - `Wonka` is a library for lightweight observables and iterables loosely based on the [callbag spec](https://github.com/callbag/callbag). 38 38 - It exposes a set of helpers to create and transform sources and output sinks, meaning it helps you to turn an event source or an 39 39 - iterable set of data into streams, and manipulate these streams. 38 38 + This means that out of the box Wonka is usable in any project that use the following: 40 39 41 41 - Reason has been becoming increasingly popular, but it's missing a good pattern for streams that feels native to the language. 42 42 - The functional nature of callbags make them a perfect starting point to fix this, and to introduce a reactive programming 43 43 - pattern to a language that is well suited for it. 44 44 - 45 45 - This library also attempts to support as many Reason/JS environments as possible, which makes the adoption of streams across 46 46 - multiple projects a lot easier. Hence `Wonka` is a library that aims to make complex streams of data easy to deal with. 47 47 - 48 48 - ## Compatibility 49 49 - 50 50 - `Wonka` is not only compatible with Reason/Bucklescript, but out of the box with other environments as well. 51 51 - 40 40 + - Plain JavaScript 52 41 - TypeScript 53 53 - - JS/Flow 54 54 - - Reason/OCaml Bucklescript 55 55 - - Reason/OCaml `bs-native` 56 56 - - Reason/OCaml Dune 42 42 + - Flow 43 43 + - Reason/OCaml with BuckleScript 44 44 + - Reason/OCaml with `bs-native` 45 45 + - Reason/OCaml with Dune and Esy 57 46 58 58 - In summary, it should work in any TypeScript/Flow/Reason/OCaml environment with full type safety. 59 59 - 60 60 - ## Installation 61 61 - 62 62 - Install the library first: `yarn add wonka` or `npm install --save wonka`, 63 63 - 64 64 - ### BuckleScript 65 65 - 66 66 - For Bucklescript you will also need to add `wonka` to `bs-dependencies` in your `bsconfig.json` file like so: 67 67 - 68 68 - ```diff 69 69 - { 70 70 - "name": "<your name>", 71 71 - "version": "0.1.0", 72 72 - "sources": ["src"], 73 73 - "bsc-flags": ["-bs-super-errors"], 74 74 - "bs-dependencies": [ 75 75 - + "wonka" 76 76 - ] 77 77 - } 78 78 - ``` 47 47 + ## [Documentation](https://wonka.kitten.sh/) 79 48 80 80 - ## Documentation 49 49 + **See the documentation at [wonka.kitten.sh](https://wonka.kitten.sh)** for more information about using `wonka`! 81 50 82 82 - This is still a work-in-progress but will contain full information on the following 83 83 - across all supported languages: 51 51 + - [Introduction](https://wonka.kitten.sh/) 52 52 + - [**Getting started**](https://wonka.kitten.sh/getting-started) 53 53 + - [Basics](https://wonka.kitten.sh/basics/) 54 54 + - [API Reference](https://wonka.kitten.sh/api/) 84 55 85 85 - - The API, i.e. a list of all helpers 86 86 - - Examples 87 87 - - Usage Guides & Recipes 88 88 - - Developer Guides (How to write a source/operator/sink) 89 89 - - Modified Callbag spec 56 56 + The raw markdown files can be found [in this repository in the `docs` folder](https://github.com/kitten/wonka/tree/master/docs).

+59 -59

__tests__/wonka_test.re

reviewed

··· 322 322 }); 323 323 }); 324 324 325 325 + describe("sample", () => { 326 326 + open Expect; 327 327 + open! Expect.Operators; 328 328 + 329 329 + afterEach(() => Jest.useRealTimers()); 330 330 + 331 331 + it("should sample the last emitted value from a source", () => { 332 332 + Jest.useFakeTimers(); 333 333 + let a = Wonka.interval(50); 334 334 + 335 335 + let talkback = ref((. _: Wonka_types.talkbackT) => ()); 336 336 + let signals = [||]; 337 337 + 338 338 + let source = Wonka.sample(Wonka.interval(100), a); 339 339 + 340 340 + source((. signal) => 341 341 + switch (signal) { 342 342 + | Start(x) => 343 343 + talkback := x; 344 344 + x(. Pull); 345 345 + | Push(_) => 346 346 + ignore(Js.Array.push(signal, signals)); 347 347 + talkback^(. Pull); 348 348 + | End => ignore(Js.Array.push(signal, signals)) 349 349 + } 350 350 + ); 351 351 + 352 352 + Jest.runTimersToTime(200); 353 353 + 354 354 + expect(signals) == [|Push(1), Push(3)|]; 355 355 + }); 356 356 + 357 357 + it("should emit an End signal when the source has emitted all values", () => { 358 358 + Jest.useFakeTimers(); 359 359 + let a = Wonka.interval(50); 360 360 + 361 361 + let talkback = ref((. _: Wonka_types.talkbackT) => ()); 362 362 + let signals = [||]; 363 363 + 364 364 + let source = Wonka.sample(Wonka.interval(100), a) |> Wonka.take(3); 365 365 + 366 366 + source((. signal) => 367 367 + switch (signal) { 368 368 + | Start(x) => 369 369 + talkback := x; 370 370 + x(. Pull); 371 371 + | Push(_) => 372 372 + ignore(Js.Array.push(signal, signals)); 373 373 + talkback^(. Pull); 374 374 + | End => ignore(Js.Array.push(signal, signals)) 375 375 + } 376 376 + ); 377 377 + 378 378 + Jest.runTimersToTime(300); 379 379 + 380 380 + expect(signals) == [|Push(1), Push(3), Push(5), End|]; 381 381 + }); 382 382 + }); 383 383 + 325 384 describe("scan", () => { 326 385 open Expect; 327 386 ··· 2025 2084 Jest.runTimersToTime(3000); 2026 2085 2027 2086 expect(signals) == [|Push(1), Push(2), Push(3), End|]; 2028 2028 - }); 2029 2029 - }); 2030 2030 - 2031 2031 - describe("sample", () => { 2032 2032 - open Expect; 2033 2033 - open! Expect.Operators; 2034 2034 - 2035 2035 - afterEach(() => Jest.useRealTimers()); 2036 2036 - 2037 2037 - it("should sample the last emitted value from a source", () => { 2038 2038 - Jest.useFakeTimers(); 2039 2039 - let a = Wonka.interval(50); 2040 2040 - 2041 2041 - let talkback = ref((. _: Wonka_types.talkbackT) => ()); 2042 2042 - let signals = [||]; 2043 2043 - 2044 2044 - let source = WonkaJs.sample(Wonka.interval(100), a); 2045 2045 - 2046 2046 - source((. signal) => 2047 2047 - switch (signal) { 2048 2048 - | Start(x) => 2049 2049 - talkback := x; 2050 2050 - x(. Pull); 2051 2051 - | Push(_) => 2052 2052 - ignore(Js.Array.push(signal, signals)); 2053 2053 - talkback^(. Pull); 2054 2054 - | End => ignore(Js.Array.push(signal, signals)) 2055 2055 - } 2056 2056 - ); 2057 2057 - 2058 2058 - Jest.runTimersToTime(200); 2059 2059 - 2060 2060 - expect(signals) == [|Push(1), Push(3)|]; 2061 2061 - }); 2062 2062 - 2063 2063 - it("should emit an End signal when the source has emitted all values", () => { 2064 2064 - Jest.useFakeTimers(); 2065 2065 - let a = Wonka.interval(50); 2066 2066 - 2067 2067 - let talkback = ref((. _: Wonka_types.talkbackT) => ()); 2068 2068 - let signals = [||]; 2069 2069 - 2070 2070 - let source = WonkaJs.sample(Wonka.interval(100), a) |> Wonka.take(3); 2071 2071 - 2072 2072 - source((. signal) => 2073 2073 - switch (signal) { 2074 2074 - | Start(x) => 2075 2075 - talkback := x; 2076 2076 - x(. Pull); 2077 2077 - | Push(_) => 2078 2078 - ignore(Js.Array.push(signal, signals)); 2079 2079 - talkback^(. Pull); 2080 2080 - | End => ignore(Js.Array.push(signal, signals)) 2081 2081 - } 2082 2082 - ); 2083 2083 - 2084 2084 - Jest.runTimersToTime(300); 2085 2085 - 2086 2086 - expect(signals) == [|Push(1), Push(3), Push(5), End|]; 2087 2087 }); 2088 2088 }); 2089 2089

+430 -151

docs/api/operators.md

reviewed

··· 5 5 6 6 Operators in Wonka allow you to transform values from a source before they are sent to a sink. Wonka has the following operators. 7 7 8 8 + ## buffer 9 9 + 10 10 + Buffers emissions from an outer source and emits a buffer array of items every time an 11 11 + inner source (notifier) emits. 12 12 + 13 13 + This operator can be used to group values into a arrays on a source. The emitted values will 14 14 + be sent when a notifier fires and will be arrays of all items before the notification event. 15 15 + 16 16 + In combination with `interval` this can be used to group values in chunks regularly. 17 17 + 18 18 + ```reason 19 19 + Wonka.interval(50) 20 20 + |> Wonka.buffer(Wonka.interval(100)) 21 21 + |> Wonka.take(2) 22 22 + |> Wonka.subscribe((. buffer) => { 23 23 + Js.Array.forEach(num => print_int(num), buffer); 24 24 + print_endline(";"); 25 25 + }); 26 26 + /* Prints 1 2; 2 3 to the console. */ 27 27 + ``` 28 28 + 29 29 + ``` typescript 30 30 + import { pipe, interval, buffer, take, subscribe } from 'wonka'; 31 31 + 32 32 + pipe( 33 33 + interval(50), 34 34 + buffer(interval(100)), 35 35 + take(2), 36 36 + subscribe(buffer => { 37 37 + buffer.forEach(x => console.log(x)); 38 38 + console.log(';'); 39 39 + }) 40 40 + ); // Prints 1 2; 2 3 to the console. 41 41 + ``` 42 42 + 8 43 ## combine 9 44 10 45 `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. ··· 14 49 let sourceTwo = Wonka.fromArray([|4, 5, 6|]); 15 50 16 51 Wonka.combine(sourceOne, sourceTwo) 17 17 - |> Wonka.subscribe((. (_valOne, _valTwo)) => print_int(_valOne + _valTwo)); 52 52 + |> Wonka.subscribe((. (a, b)) => print_int(a + b)); 18 53 19 54 /* Prints 56789 (1+4, 2+4, 3+4, 3+5, 3+6) to the console. */ 20 55 ``` ··· 30 65 subscribe(([valOne, valTwo]) => { 31 66 console.log(valOne + valTwo); 32 67 }) 33 33 - ); 34 34 - 35 35 - // Prints 56789 (1+4, 2+4, 3+4, 3+5, 3+6) to the console. 68 68 + ); // Prints 56789 (1+4, 2+4, 3+4, 3+5, 3+6) to the console. 36 69 ``` 37 70 38 71 ## concat ··· 40 73 `concat` will combine two sources together, subscribing to the next source after the previous source completes. 41 74 42 75 ```reason 43 43 - let sourceOne = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 44 44 - let sourceTwo = Wonka.fromArray([|6, 5, 4, 3, 2, 1|]); 45 45 - 46 46 - Wonka.concat([|sourceOne, sourceTwo|]) |> Wonka.subscribe((. _val) => print_int(_val)); 76 76 + let sourceOne = Wonka.fromArray([|1, 2, 3|]); 77 77 + let sourceTwo = Wonka.fromArray([|6, 5, 4|]); 47 78 48 48 - /* Prints 1 2 3 4 5 6 6 5 4 3 2 1 to the console. */ 79 79 + Wonka.concat([|sourceOne, sourceTwo|]) 80 80 + |> Wonka.subscribe((. x) => print_int(x)); 81 81 + /* Prints 1 2 3 6 5 4 to the console. */ 49 82 ``` 50 83 51 84 ```typescript 52 85 import { fromArray, pipe, concat, subscribe } from 'wonka'; 53 86 54 54 - const sourceOne = fromArray([1, 2, 3, 4, 5, 6]); 55 55 - const sourceTwo = fromArray([6, 5, 4, 3, 2, 1]); 87 87 + const sourceOne = fromArray([1, 2, 3]); 88 88 + const sourceTwo = fromArray([6, 5, 4]); 56 89 57 90 pipe( 58 91 concat([sourceOne, sourceTwo]), 59 59 - subscribe(val => { 60 60 - console.log(val); 61 61 - }) 62 62 - ); 92 92 + subscribe(val => console.log(val)) 93 93 + ); // Prints 1 2 3 6 5 4 to the console. 94 94 + ``` 63 95 64 64 - // Prints 1 2 3 4 5 6 6 5 4 3 2 1 to the console. 96 96 + ## concatAll 97 97 + 98 98 + `concatAll` will combine all sources emitted on an outer source together, subscribing to the 99 99 + next source after the previous source completes. 100 100 + 101 101 + It's very similar to `concat`, but instead accepts a source of sources as an input. 102 102 + 103 103 + ```reason 104 104 + let sourceOne = Wonka.fromArray([|1, 2, 3|]); 105 105 + let sourceTwo = Wonka.fromArray([|6, 5, 4|]); 106 106 + 107 107 + Wonka.fromList([sourceOne, sourceTwo]) 108 108 + |> Wonka.concatAll 109 109 + |> Wonka.subscribe((. x) => print_int(x)); 110 110 + /* Prints 1 2 3 6 5 4 to the console. */ 111 111 + ``` 112 112 + 113 113 + ```typescript 114 114 + import { pipe, fromArray, concatAll, subscribe } from 'wonka'; 115 115 + 116 116 + const sourceOne = fromArray([1, 2, 3]); 117 117 + const sourceTwo = fromArray([6, 5, 4]); 118 118 + 119 119 + pipe( 120 120 + fromArray([sourceOne, sourceTwo]), 121 121 + concatAll, 122 122 + subscribe(val => console.log(val)) 123 123 + ); // Prints 1 2 3 6 5 4 to the console. 65 124 ``` 66 125 67 126 ## concatMap ··· 95 154 delay(val * 1000) 96 155 ); 97 156 }), 98 98 - subscribe(val => { 99 99 - console.log(val); 100 100 - }) 157 157 + subscribe(val => console.log(val)) 158 158 + ); 159 159 + ``` 160 160 + 161 161 + 162 162 + ## delay 163 163 + 164 164 + `delay` delays all emitted values of a source by the given amount of milliseconds. 165 165 + 166 166 + > _Note:_ This operator is only available in JavaScript environments, and will be excluded 167 167 + > when compiling natively. 168 168 + 169 169 + ```reason 170 170 + Wonka.fromList([1, 2]) 171 171 + |> Wonka.delay(10) 172 172 + |> Wonka.subscribe((. x) => print_int(x)); 173 173 + /* waits 10ms then prints 1, waits 10ms then prints 2, waits 10ms then ends */ 174 174 + ``` 175 175 + 176 176 + ```typescript 177 177 + import { pipe, fromArray, delay, subscribe } from 'wonka'; 178 178 + 179 179 + pipe( 180 180 + fromArray([1, 2]), 181 181 + delay(10) 182 182 + subscribe(val => console.log(val)) 183 183 + ); 184 184 + // waits 10ms then prints 1, waits 10ms then prints 2, waits 10ms then ends 185 185 + ``` 186 186 + 187 187 + ## debounce 188 188 + 189 189 + `debounce` doesn't emit values of a source until no values have been emitted after 190 190 + a given amount of milliseconds. Once this threshold of silence has been reached, the 191 191 + last value that has been received will be emitted. 192 192 + 193 193 + > _Note:_ This operator is only available in JavaScript environments, and will be excluded 194 194 + > when compiling natively. 195 195 + 196 196 + ```reason 197 197 + let sourceA = Wonka.interval(10) 198 198 + |> Wonka.take(5); 199 199 + let sourceB = Wonka.fromValue(1); 200 200 + 201 201 + Wonka.concat([|sourceA, sourceB|]) 202 202 + |> Wonka.debounce((. _x) => 20) 203 203 + |> Wonka.subscribe((. x) => print_int(x)); 204 204 + /* The five values from sourceA will be omitted */ 205 205 + /* After these values and after 20ms `1` will be logged */ 206 206 + ``` 207 207 + 208 208 + ```typescript 209 209 + import { pipe, interval, take, fromValue, concat, debounce, subscribe } from 'wonka'; 210 210 + 211 211 + const sourceA = pipe(interval(10), take(5)); 212 212 + const sourceB = fromValue(1); 213 213 + 214 214 + pipe( 215 215 + concat([sourceA, sourceB]) 216 216 + debounce(() => 20), 217 217 + subscribe(val => console.log(val)) 101 218 ); 219 219 + 220 220 + // The five values from sourceA will be omitted 221 221 + // After these values and after 20ms `1` will be logged 102 222 ``` 103 223 104 224 ## filter ··· 106 226 `filter` will remove values from a source by passing them through an iteratee that returns a `bool`. 107 227 108 228 ```reason 109 109 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 110 229 let isEven = (. n) => n mod 2 === 0; 111 230 112 112 - source |> Wonka.filter(isEven) |> Wonka.subscribe((. _val) => print_int(_val)); 113 113 - 231 231 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 232 232 + |> Wonka.filter(isEven) 233 233 + |> Wonka.subscribe((. x) => print_int(x)); 114 234 /* Prints 246 to the console. */ 115 235 ``` 116 236 117 237 ```typescript 118 238 import { fromArray, filter, subscribe } from 'wonka'; 119 239 120 120 - const source = fromArray([1, 2, 3, 4, 5, 6]); 121 240 const isEven = n => n % 2 === 0; 122 241 123 242 pipe( 124 124 - source, 243 243 + fromArray([1, 2, 3, 4, 5, 6]), 125 244 filter(isEven), 126 126 - subscribe(val => { 127 127 - console.log(val); 128 128 - }) 245 245 + subscribe(val => console.log(val)) 129 246 ); 130 247 131 248 // Prints 246 to the console. ··· 136 253 `map` will transform values from a source by passing them through an iteratee that returns a new value. 137 254 138 255 ```reason 139 139 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 140 256 let square = (. n) => n * n; 141 257 142 142 - source |> Wonka.map(square) |> Wonka.subscribe((. _val) => print_int(_val)); 143 143 - 258 258 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 259 259 + |> Wonka.map(square) 260 260 + |> Wonka.subscribe((. x) => print_int(x)); 144 261 /* Prints 1 4 9 16 25 36 to the console. */ 145 262 ``` 146 263 147 264 ```typescript 148 265 import { fromArray, pipe, map, subscribe } from 'wonka'; 149 266 150 150 - const source = fromArray([1, 2, 3, 4, 5, 6]); 151 267 const square = n => n * n; 152 268 153 269 pipe( 154 154 - source, 270 270 + fromArray([1, 2, 3, 4, 5, 6]), 155 271 map(square), 156 156 - subscribe(val => { 157 157 - console.log(val); 158 158 - }) 272 272 + subscribe(val => console.log(val)) 159 273 ); 160 274 161 275 // Prints 1 4 9 16 25 36 to the console. ··· 163 277 164 278 ## merge 165 279 166 166 - `merge` two sources together into a single source. 280 280 + `merge` merges an array of sources together into a single source. It subscribes 281 281 + to all sources that it's passed and emits all their values on the output source. 167 282 168 283 ```reason 169 284 let sourceA = Wonka.fromArray([|1, 2, 3|]); 170 285 let sourceB = Wonka.fromArray([|4, 5, 6|]); 171 286 172 172 - Wonka.merge([|sourceA, sourceB|]) |> Wonka.subscribe((. _val) => print_int(_val)); 287 287 + Wonka.merge([|sourceA, sourceB|]) 288 288 + |> Wonka.subscribe((. x) => print_int(x)); 289 289 + /* Prints 1 2 3 4 5 6 to the console. */ 290 290 + ``` 173 291 174 174 - /* Prints 1 2 3 4 5 6 to the console. 292 292 + ```typescript 293 293 + import { fromArray, pipe, merge, subscribe } from 'wonka'; 294 294 + 295 295 + const sourceOne = fromArray([1, 2, 3]); 296 296 + const sourceTwo = fromArray([4, 5, 6]); 297 297 + 298 298 + pipe( 299 299 + merge(sourceOne, sourceTwo), 300 300 + subscribe((val) => console.log(val)) 301 301 + ); // Prints 1 2 3 4 5 6 to the console. 302 302 + ``` 303 303 + 304 304 + ## mergeAll 305 305 + 306 306 + `mergeAll` will merge all sources emitted on an outer source into a single one. 307 307 + It's very similar to `merge`, but instead accepts a source of sources as an input. 308 308 + 309 309 + > _Note:_ This operator is also exported as `flatten` which is just an alias for `mergeAll` 310 310 + 311 311 + ```reason 312 312 + let sourceA = Wonka.fromArray([|1, 2, 3|]); 313 313 + let sourceB = Wonka.fromArray([|4, 5, 6|]); 314 314 + 315 315 + Wonka.fromList([sourceA, sourceB]) 316 316 + |> Wonka.mergeAll 317 317 + |> Wonka.subscribe((. x) => print_int(x)); 318 318 + /* Prints 1 2 3 4 5 6 to the console. */ 175 319 ``` 176 320 177 321 ```typescript 178 178 - import { fromArray, pipe, merge, subscribe } from 'wonka'; 322 322 + import { pipe, fromArray, mergeAll, subscribe } from 'wonka'; 179 323 180 324 const sourceOne = fromArray([1, 2, 3]); 181 325 const sourceTwo = fromArray([4, 5, 6]); 182 326 183 327 pipe( 184 184 - merge(sourceOne, sourceTwo) 185 185 - subscribe((val) => { 186 186 - console.log(val); 187 187 - }) 188 188 - ); 328 328 + fromArray([sourceOne, sourceTwo]), 329 329 + mergeAll, 330 330 + subscribe(val => console.log(val)) 331 331 + ); // Prints 1 2 3 4 5 6 to the console. 332 332 + ``` 189 333 190 190 - // Prints 1 2 3 4 5 6 to the console. 334 334 + ## mergeMap 335 335 + 336 336 + `mergeMap` allows you to map values of an outer source to an inner source. 337 337 + This allows you to create nested sources for each emitted value, which will 338 338 + all be merged into a single source, like with `mergeAll`. 339 339 + 340 340 + Unlike `concatMap` all inner sources will be subscribed to at the same time 341 341 + and all their values will be emitted on the output source as they come in. 342 342 + 343 343 + ```reason 344 344 + Wonka.fromList([1, 2]) 345 345 + |> Wonka.mergeMap((. value) => 346 346 + Wonka.fromList([value - 1, value])) 347 347 + |> Wonka.subscribe((. x) => print_int(x)); 348 348 + /* Prints 0 1 1 2 to the console. */ 349 349 + ``` 350 350 + 351 351 + ```typescript 352 352 + import { pipe, fromArray, mergeMap, subscribe } from 'wonka'; 353 353 + 354 354 + pipe( 355 355 + fromArray([1, 2]), 356 356 + mergeMap(x => fromArray([x - 1, x])), 357 357 + subscribe(val => console.log(val)) 358 358 + ); // Prints 0 1 1 2 to the console. 191 359 ``` 192 360 193 361 ## onEnd ··· 207 375 208 376 let sourceOne = Wonka.fromPromise(promiseOne); 209 377 let sourceTwo = Wonka.fromPromise(promiseTwo); 210 210 - let source = Wonka.concat([|sourceOne, sourceTwo|]); 211 378 212 212 - source 213 213 - |> Wonka.onEnd((.) => print_endline("onEnd")) 214 214 - |> Wonka.subscribe((. _val) => print_endline(_val)); 379 379 + Wonka.concat([|sourceOne, sourceTwo|]) 380 380 + |> Wonka.onEnd((.) => print_endline("onEnd")) 381 381 + |> Wonka.subscribe((. x) => print_endline(x)); 215 382 216 383 /* Logs ResolveOne after one second, then ResolveTwo after an additional second, then onEnd immediately. */ 217 384 ``` ··· 232 399 233 400 const sourceOne = fromPromise(promiseOne); 234 401 const sourceTwo = fromPromise(promiseTwo); 235 235 - const source = concat([sourceOne, sourceTwo]); 236 402 237 403 pipe( 238 238 - source, 239 239 - onEnd(() => { 240 240 - console.log('onEnd'); 241 241 - }), 242 242 - subscribe(val => { 243 243 - console.log(val); 244 244 - }) 404 404 + concat([sourceOne, sourceTwo]), 405 405 + onEnd(() => console.log('onEnd')), 406 406 + subscribe(val => console.log(val)) 245 407 ); 246 408 247 409 // Logs ResolveOne after one second, then ResolveTwo after an additional second, then onEnd immediately. ··· 252 414 Run a callback on each `Push` signal sent to the sink by the source. 253 415 254 416 ```reason 255 255 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 256 256 - 257 257 - Wonka.source 258 258 - |> Wonka.onPush((. _val) => print_string({j|Push $_val|j})) 259 259 - |> Wonka.subscribe((. _val) => print_int(_val)); 260 260 - 417 417 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 418 418 + |> Wonka.onPush((. x) => print_string({j|Push $x|j})) 419 419 + |> Wonka.subscribe((. x) => print_int(x)); 261 420 /* Prints Push 1 1 Push 2 2 Push 3 3 Push 4 4 Push 5 5 Push 6 6 to the console. */ 262 421 ``` 263 422 264 423 ```typescript 265 424 import { fromArray, pipe, onPush, subscribe } from 'wonka'; 266 266 - 267 267 - const source = fromArray([1, 2, 3, 4, 5, 6]); 268 425 269 426 pipe( 270 270 - source, 271 271 - onPush(val => { 272 272 - console.log(`Push ${val}`); 273 273 - }), 274 274 - subscribe(val => { 275 275 - console.log(val); 276 276 - }) 277 277 - ); 278 278 - 279 279 - // Prints Push 1 1 Push 2 2 Push 3 3 Push 4 4 Push 5 5 Push 6 6 to the console. 427 427 + fromArray([1, 2, 3, 4, 5, 6]), 428 428 + onPush(val => console.log(`Push ${val}`)), 429 429 + subscribe(val => console.log(val)) 430 430 + ); // Prints Push 1 1 Push 2 2 Push 3 3 Push 4 4 Push 5 5 Push 6 6 to the console. 280 431 ``` 281 432 282 433 ## onStart ··· 289 440 Js.Global.setTimeout(() => resolve(. "Resolve"), 1000) |> ignore 290 441 ); 291 442 292 292 - let source = Wonka.fromPromise(promise); 293 293 - 294 294 - source 295 295 - |> Wonka.onStart((.) => print_endline("onStart")) 296 296 - |> Wonka.subscribe((. _val) => print_endline(_val)); 297 297 - 443 443 + Wonka.fromPromise(promise) 444 444 + |> Wonka.onStart((.) => print_endline("onStart")) 445 445 + |> Wonka.subscribe((. _val) => print_endline(_val)); 298 446 /* Logs onStart to the console, pauses for one second to allow the timeout to finish, 299 447 then logs "Resolve" to the console. */ 300 448 ``` ··· 308 456 }, 1000); 309 457 }); 310 458 311 311 - const source = fromPromise(promise); 312 312 - 313 459 pipe( 314 314 - source, 315 315 - onStart(() => { 316 316 - console.log('onStart'); 317 317 - }), 318 318 - subscribe(val => { 319 319 - console.log(val); 320 320 - }) 460 460 + fromPromise(promise), 461 461 + onStart(() => console.log('onStart')), 462 462 + subscribe(val => console.log(val)) 321 463 ); 322 464 323 465 // Logs onStart to the console, pauses for one second to allow the timeout to finish, 324 466 // then logs "Resolve" to the console. 325 467 ``` 326 468 469 469 + ## sample 470 470 + 471 471 + `sample` emits the previously emitted value from an outer source every time 472 472 + an inner source (notifier) emits. 473 473 + 474 474 + In combination with `interval` it can be used to get values from a noisy source 475 475 + more regularly. 476 476 + 477 477 + ```reason 478 478 + Wonka.interval(10) 479 479 + |> Wonka.sample(Wonka.interval(100)) 480 480 + |> Wonka.take(2) 481 481 + |> Wonka.subscribe((. x) => print_int(x)); 482 482 + /* Prints 10 20 to the console. */ 483 483 + ``` 484 484 + 485 485 + ``` typescript 486 486 + import { pipe, interval, sample, take, subscribe } from 'wonka'; 487 487 + 488 488 + pipe( 489 489 + interval(10), 490 490 + sample(interval(100)), 491 491 + take(2), 492 492 + subscribe(x => console.log(x)) 493 493 + ); // Prints 10 20 to the console. 494 494 + ``` 495 495 + 327 496 ## scan 328 497 329 498 Accumulate emitted values of a source in a accumulator, similar to JavaScript `reduce`. 330 499 331 500 ```reason 332 332 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 333 333 - 334 334 - source 335 335 - |> Wonka.scan((. acc, x) => acc + x, 0) 336 336 - |> Wonka.subscribe((. _val) => print_int(_val)); 501 501 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 502 502 + |> Wonka.scan((. acc, x) => acc + x, 0) 503 503 + |> Wonka.subscribe((. x) => print_int(x)); 337 504 /* Prints 1 3 6 10 15 21 to the console. */ 338 505 ``` 339 506 340 507 ```typescript 341 508 import { fromArray, pipe, scan, subscribe } from 'wonka'; 342 509 343 343 - const source = fromArray([1, 2, 3, 4, 5, 6]); 344 344 - 345 510 pipe( 346 346 - source, 511 511 + fromArray([1, 2, 3, 4, 5, 6]), 347 512 scan((acc, val) => acc + val), 348 348 - subscribe(val => { 349 349 - console.log(val); 350 350 - }) 513 513 + subscribe(val => console.log(val)) 351 514 ); 352 515 353 516 // Prints 1 3 6 10 15 21 to the console. 354 517 ``` 355 518 356 356 - ## skip 519 519 + ## share 520 520 + 521 521 + `share` ensures that all subscriptions to the underlying source are shared. 357 522 358 358 - `skip` the specified number of emissions from the source. 523 523 + By default Wonka's sources are lazy. They only instantiate themselves and begin 524 524 + emitting signals when they're being subscribed to, since they're also immutable. 525 525 + This means that when a source is used in multiple places, their underlying subscription 526 526 + is not shared. Instead, the entire chain of sources and operators will be instantiated 527 527 + separately every time. 528 528 + 529 529 + The `share` operator prevents this by creating an output source that will reuse a single 530 530 + subscription to the parent source, which will be unsubscribed from when no sinks are 531 531 + listening to it anymore. 532 532 + 533 533 + This is especially useful if you introduce side-effects to your sources, 534 534 + for instance with `onStart`. 359 535 360 536 ```reason 361 361 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 537 537 + let source = Wonka.never 538 538 + |> Wonka.onStart((.) => print_endline("start")) 539 539 + |> Wonka.share; 362 540 363 363 - source |> Wonka.skip(2) |> Wonka.subscribe((. _val) => print_int(_val)); 541 541 + /* Without share this would print "start" twice: */ 542 542 + Wonka.publish(source); 543 543 + Wonka.publish(source); 544 544 + ``` 545 545 + 546 546 + ```typescript 547 547 + import { pipe, never, onStart, share, publish } from 'wonka'; 548 548 + 549 549 + const source = pipe( 550 550 + never 551 551 + onStart(() => console.log('start')), 552 552 + share 553 553 + ); 364 554 555 555 + // Without share this would print "start" twice: 556 556 + publish(source); 557 557 + publish(source); 558 558 + ``` 559 559 + 560 560 + ## skip 561 561 + 562 562 + `skip` the specified number of emissions from the source. 563 563 + 564 564 + ```reason 565 565 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 566 566 + |> Wonka.skip(2) 567 567 + |> Wonka.subscribe((. x) => print_int(x)); 365 568 /* Prints 3 4 5 6 to the console, since the first two emissions from the source were skipped. 366 569 ``` 367 570 368 571 ```typescript 369 572 import { fromArray, pipe, skip, subscribe } from 'wonka'; 370 573 371 371 - const source = fromArray([1, 2, 3, 4, 5, 6]); 372 372 - 373 574 pipe( 374 374 - source, 575 575 + fromArray([1, 2, 3, 4, 5, 6]), 375 576 skip(2), 376 376 - subscribe(val => { 377 377 - console.log(val); 378 378 - }) 577 577 + subscribe(val => console.log(val)) 379 578 ); 380 579 ``` 381 580 ··· 387 586 let source = Wonka.interval(100); 388 587 let notifier = Wonka.interval(500); 389 588 390 390 - source |> Wonka.skipUntil(notifier) |> Wonka.subscribe((. _val) => print_int(_val)); 589 589 + source 590 590 + |> Wonka.skipUntil(notifier) 591 591 + |> Wonka.subscribe((. x) => print_int(x)); 391 592 392 593 /* Skips all values emitted by source (0, 1, 2, 3) until notifier emits at 500ms. 393 594 Then logs 4 5 6 7 8 9 10... to the console every 500ms. */ ··· 402 603 pipe( 403 604 source, 404 605 skipUntil(notifier), 405 405 - subscribe(val => { 406 406 - console.log(val); 407 407 - }) 606 606 + subscribe(val => console.log(val)) 408 607 ); 409 608 410 609 // Skips all values emitted by source (0, 1, 2, 3) until notifier emits at 500ms. ··· 428 627 ```typescript 429 628 import { fromArray, pipe, skipWhile, subscribe } from 'wonka'; 430 629 431 431 - const source = fromArray([1, 2, 3, 4, 5, 6]); 432 432 - 433 630 pipe( 434 434 - source, 631 631 + fromArray([1, 2, 3, 4, 5, 6]), 435 632 skipWhile(val => val < 5), 436 436 - subscribe(val => { 437 437 - console.log(val); 438 438 - }) 633 633 + subscribe(val => console.log(val)) 439 634 ); 440 635 441 636 // Prints 5 6 to the console, as 1 2 3 4 all return true for the predicate function. 442 637 ``` 443 638 639 639 + ## switchMap 640 640 + 641 641 + `switchMap` allows you to map values of an outer source to an inner source. 642 642 + The inner source's values will be emitted on the returned output source. If 643 643 + a new inner source is returned, because the outer source emitted a new value 644 644 + before the previous inner source completed, the inner source is closed and unsubscribed 645 645 + from. 646 646 + 647 647 + This is similar to `concatMap` but instead of waiting for the last inner source to complete 648 648 + before emitting values from the next, `switchMap` just cancels the previous inner source. 649 649 + 650 650 + ```reason 651 651 + Wonka.interval(50) 652 652 + |> Wonka.switchMap((. _value) => 653 653 + Wonka.interval(40)) 654 654 + |> Wonka.take(3) 655 655 + |> Wonka.subscribe((. x) => print_int(x)); 656 656 + /* Prints 1 2 3 to the console. */ 657 657 + /* The inner interval is cancelled after its first value every time */ 658 658 + ``` 659 659 + 660 660 + ```typescript 661 661 + import { pipe, interval, switchMap, take, subscribe } from 'wonka'; 662 662 + 663 663 + pipe( 664 664 + interval(50), 665 665 + // The inner interval is cancelled after its first value every time 666 666 + switchMap(value => interval(40)), 667 667 + take(3), 668 668 + subscribe(x => console.log(x)) 669 669 + ); // Prints 1 2 3 to the console 670 670 + ``` 671 671 + 672 672 + ## switchAll 673 673 + 674 674 + `switchAll` will combined sources emitted on an outer source together, subscribing 675 675 + to only one source at a time, and cancelling the previous inner source, when it hasn't 676 676 + ended while the next inner source is created. 677 677 + 678 678 + It's very similar to `switchMap`, but instead accepts a source of sources. 679 679 + 680 680 + ```reason 681 681 + Wonka.interval(50) 682 682 + |> Wonka.map((. _value) => 683 683 + Wonka.interval(40)) 684 684 + |> Wonka.switchAll 685 685 + |> Wonka.take(3) 686 686 + |> Wonka.subscribe((. x) => print_int(x)); 687 687 + /* Prints 1 2 3 to the console. */ 688 688 + ``` 689 689 + 690 690 + ```typescript 691 691 + import { pipe, interval, map, switchAll, take, subscribe } from 'wonka'; 692 692 + 693 693 + pipe( 694 694 + interval(50), 695 695 + map(() => interval(40)), 696 696 + switchAll, 697 697 + take(3), 698 698 + subscribe(x => console.log(x)) 699 699 + ); // Prints 1 2 3 to the console 700 700 + ``` 701 701 + 702 702 + These examples are practically identical to the `switchMap` examples, but note 703 703 + that `map` was used instead of using `switchMap` directly. This is because combining 704 704 + `map` with a subsequent `switchAll` is the same as using `switchMap`. 705 705 + 444 706 ## take 445 707 446 708 `take` only a specified number of emissions from the source before completing. `take` is the opposite of `skip`. 447 709 448 710 ```reason 449 449 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 450 450 - 451 451 - source |> Wonka.take(3) |> Wonka.subscribe((. _val) => print_int(_val)); 452 452 - 711 711 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]) 712 712 + |> Wonka.take(3) 713 713 + |> Wonka.subscribe((. x) => print_int(x)); 453 714 /* Prints 1 2 3 to the console. */ 454 715 ``` 455 716 456 717 ```typescript 457 718 import { fromArray, pipe, take, subscribe } from 'wonka'; 458 719 459 459 - const source = fromArray([1, 2, 3, 4, 5, 6]); 460 460 - 461 720 pipe( 462 462 - source, 721 721 + fromArray([1, 2, 3, 4, 5, 6]), 463 722 take(3), 464 464 - subscribe(val => { 465 465 - console.log(val); 466 466 - }) 723 723 + subscribe(val => console.log(val)) 467 724 ); 468 725 469 726 // Prints 1 2 3 to the console. ··· 474 731 `takeLast` will take only the last n emissions from the source. 475 732 476 733 ```reason 477 477 - let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 478 478 - 479 479 - source |> Wonka.takeLast(3) |> Wonka.subscribe((. _val) => print_int(_val)); 480 480 - 734 734 + Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 735 735 + |> Wonka.takeLast(3) 736 736 + |> Wonka.subscribe((. x) => print_int(x)); 481 737 /* Prints 4 5 6 to the console. */ 482 738 ``` 483 739 484 740 ```typescript 485 741 import { fromArray, pipe, takeLast, subscribe } from 'wonka'; 486 742 487 487 - const source = fromArray([1, 2, 3, 4, 5, 6]); 488 488 - 489 743 pipe( 490 490 - source, 744 744 + fromArray([1, 2, 3, 4, 5, 6]), 491 745 takeLast(3), 492 492 - subscribe(val => { 493 493 - console.log(val); 494 494 - }) 746 746 + subscribe(val => console.log(val)) 495 747 ); 496 748 497 749 // Prints 4 5 6 to the console. ··· 506 758 let notifier = Wonka.interval(500); 507 759 508 760 source 509 509 - |> Wonka.takeUntil(notifier) 510 510 - |> Wonka.subscribe((. _val) => print_int(_val)); 761 761 + |> Wonka.takeUntil(notifier) 762 762 + |> Wonka.subscribe((. x) => print_int(x)); 511 763 512 764 /* Pauses 100ms, prints 0, pauses 100ms, prints 1, pauses 100ms, prints 2, pauses 100ms, 513 765 prints 3, pauses 100, then completes (notifier emits). */ ··· 522 774 pipe( 523 775 source, 524 776 takeUntil(notifier), 525 525 - subscribe(val => { 526 526 - console.log(val); 527 527 - }) 777 777 + subscribe(val => console.log(val)) 528 778 ); 529 779 530 780 // Pauses 100ms, prints 0, pauses 100ms, prints 1, pauses 100ms, prints 2, pauses 100ms, ··· 539 789 let source = Wonka.fromArray([|1, 2, 3, 4, 5, 6|]); 540 790 541 791 source 542 542 - |> Wonka.takeWhile((. _val) => _val < 5) 543 543 - |> Wonka.subscribe((. _val) => print_int(_val)); 792 792 + |> Wonka.takeWhile((. x) => x < 5) 793 793 + |> Wonka.subscribe((. x) => print_int(x)); 544 794 545 795 /* Prints 1 2 3 4 to the console. */ 546 796 ``` ··· 553 803 pipe( 554 804 source, 555 805 takeWhile(val => val < 5), 556 556 - subscribe(val => { 557 557 - console.log(val); 558 558 - }) 806 806 + subscribe(val => console.log(val)) 559 807 ); 560 808 561 809 // Prints 1 2 3 4 to the console. 562 810 ``` 811 811 + 812 812 + ## throttle 813 813 + 814 814 + `throttle` emits values of a source, but after each value it will omit all values for 815 815 + the given amount of milliseconds. It enforces a time of silence after each value it 816 816 + receives and skips values while the silence is still ongoing. 817 817 + 818 818 + This is very similar to `debounce` but instead of waiting for leading time before a 819 819 + value it waits for trailing time after a value. 820 820 + 821 821 + > _Note:_ This operator is only available in JavaScript environments, and will be excluded 822 822 + > when compiling natively. 823 823 + 824 824 + ```reason 825 825 + Wonka.interval(10) 826 826 + |> Wonka.throttle((. _x) => 50) 827 827 + |> Wonka.take(2) 828 828 + |> Wonka.subscribe((. x) => print_int(x)); 829 829 + /* Outputs 0 6 to the console. */ 830 830 + ``` 831 831 + 832 832 + ```typescript 833 833 + import { pipe, interval, throttle, take, subscribe } from 'wonka'; 834 834 + 835 835 + pipe( 836 836 + interval(10), 837 837 + throttle(() => 50) 838 838 + takew(2), 839 839 + subscribe(val => console.log(val)) 840 840 + ); // Outputs 0 6 to the console. 841 841 + ```

+77

docs/api/sinks.md

reviewed

··· 123 123 124 124 If you have a source that doesn't complete and are looking to resolve on the first 125 125 value instead of the last, you may have to apply `take(1)` to your source. 126 126 + 127 127 + ## toObservable 128 128 + 129 129 + `toObservable` returns a [spec-compliant JS Observable](https://github.com/tc39/proposal-observable), which emits the same 130 130 + values as a source. 131 131 + 132 132 + As per the specification, the Observable is annotated using `Symbol.observable`. 133 133 + 134 134 + > _Note:_ This sink is only available in JavaScript environments, and will be excluded 135 135 + > when compiling natively. 136 136 + 137 137 + ```reason 138 138 + let observable = Wonka.fromArray([|1, 2, 3|]) 139 139 + |> Wonka.toObservable; 140 140 + 141 141 + observable##subscribe([@bs] { 142 142 + as _; 143 143 + pub next = value => print_int(value); 144 144 + pub complete = () => (); 145 145 + pub error = _ => (); 146 146 + }); /* Prints 1 2 3 to the console. */ 147 147 + ``` 148 148 + 149 149 + ```typescript 150 150 + import { pipe, fromArray, toObservable } from 'wonka'; 151 151 + 152 152 + const observable = pipe( 153 153 + fromArray([1, 2, 3]), 154 154 + toObservable, 155 155 + ); 156 156 + 157 157 + observable.subscribe({ 158 158 + next: value => console.log(value), 159 159 + complete: () => {}, 160 160 + error: () => {}, 161 161 + }); // Prints 1 2 3 to the console. 162 162 + ``` 163 163 + 164 164 + ## toCallbag 165 165 + 166 166 + `toCallbag` returns a [spec-compliant JS Callbag](https://github.com/callbag/callbag), which emits the same signals 167 167 + as a Wonka source. 168 168 + 169 169 + Since Wonka's sources are very similar to callbags and only diverge from the specification 170 170 + minimally, Callbags map to Wonka's sources very closely and `toCallbag` only creates a thin 171 171 + wrapper which is mostly concerned with converting between the type signatures. 172 172 + 173 173 + > _Note:_ This sink is only available in JavaScript environments, and will be excluded 174 174 + > when compiling natively. 175 175 + 176 176 + ```reason 177 177 + /* This example uses the callbag-iterate package for illustrative purposes */ 178 178 + [@bs.module] external callbagIterate: 179 179 + (. ('a => unit)) => (. Wonka.callbagT('a)) => unit = "callbag-iterate"; 180 180 + 181 181 + let callbag = Wonka.fromArray([|1, 2, 3|]) 182 182 + |> Wonka.toCallbag; 183 183 + 184 184 + callbagIterate(. value => { 185 185 + print_int(value); 186 186 + })(. callbag); /* Prints 1 2 3 to the console. */ 187 187 + ``` 188 188 + 189 189 + ```typescript 190 190 + import { pipe, fromArray, toCallbag } from 'wonka'; 191 191 + 192 192 + // This example uses the callbag-iterate package for illustrative purposes 193 193 + import callbagIterate from 'callbag-iterate'; 194 194 + 195 195 + const callbag = pipe( 196 196 + fromArray([1, 2, 3]), 197 197 + toCallbag, 198 198 + ); 199 199 + 200 200 + callbagIterate(value => console.log(value))(callbag); 201 201 + // Prints 1 2 3 to the console. 202 202 + ```

+109

docs/api/sources.md

reviewed

··· 188 188 ); // Prints 1 to the console. 189 189 ``` 190 190 191 191 + ## fromObservable 192 192 + 193 193 + `fromObservable` transforms a [spec-compliant JS Observable](https://github.com/tc39/proposal-observable) into a source. 194 194 + The resulting source will behave exactly the same as the Observable that it was 195 195 + passed, so it will start, end, and push values identically. 196 196 + 197 197 + > _Note:_ This source is only available in JavaScript environments, and will be excluded 198 198 + > when compiling natively. 199 199 + 200 200 + ```typescript 201 201 + import { pipe, fromObservable, subscribe } from 'wonka'; 202 202 + 203 203 + // This example uses zen-observable for illustrative purposes 204 204 + import Observable from 'zen-observable'; 205 205 + 206 206 + const observable = Observable.from([1, 2, 3]); 207 207 + 208 208 + pipe( 209 209 + fromObservable(observable), 210 210 + subscribe(e => console.log(e)) 211 211 + ); // Prints 1 2 3 to the console 212 212 + ``` 213 213 + 214 214 + If you're using Reason in a JavaScript environment and you're interested in this 215 215 + operator, you may be using a library to create or get Observables. 216 216 + 217 217 + Some libraries don't expose Observables with the same BuckleScript type signature 218 218 + that Wonka uses to type them. So while Wonka's `observableT` type is fairly 219 219 + lenient it may not work for you. 220 220 + 221 221 + ```reason 222 222 + type observableT('a) = {. 223 223 + [@bs.meth] "subscribe": observerT('a) => subscriptionT 224 224 + }; 225 225 + ``` 226 226 + 227 227 + To work around this you can create a function that casts your observable type 228 228 + to Wonka's `observableT`. 229 229 + 230 230 + ```reason 231 231 + type yourObservableType('a); 232 232 + external asObservable: yourObservableType('a) => Wonka.observableT('a) = "%identity"; 233 233 + ``` 234 234 + 235 235 + This snippet would create an `asObservable` function, which can type-cast your 236 236 + Observable type to `Wonka.observableT` and compiles away completely. 237 237 + 238 238 + ## fromCallbag 239 239 + 240 240 + `fromCallbag` transforms a [spec-compliant JS Callbag](https://github.com/callbag/callbag) into a source. 241 241 + 242 242 + Since Wonka's sources are very similar to callbags and only diverge from the specification 243 243 + minimally, Callbags map to Wonka's sources very closely and the `fromCallbag` wrapper 244 244 + is very thin and mostly concerned with converting between the type signatures. 245 245 + 246 246 + > _Note:_ This source is only available in JavaScript environments, and will be excluded 247 247 + > when compiling natively. 248 248 + 249 249 + ```reason 250 250 + /* This example uses the callbag-from-iter package for illustrative purposes */ 251 251 + [@bs.module] external callbagFromArray: 252 252 + array('a) => Wonka.callbagT('a) = "callbag-from-iter"; 253 253 + 254 254 + let callbag = callbagFromArray([|1, 2, 3|]); 255 255 + 256 256 + Wonka.fromCallbag(callbag) 257 257 + |> Wonka.subscribe((. x) => Js.log(x)); 258 258 + /* Prints 1 2 3 to the console. */ 259 259 + ``` 260 260 + 261 261 + ```typescript 262 262 + import { pipe, fromCallbag, subscribe } from 'wonka'; 263 263 + 264 264 + // This example uses the callbag-from-iter package for illustrative purposes 265 265 + import callbagFromArray from 'callbag-from-iter'; 266 266 + 267 267 + const callbag = callbagFromArray([1, 2, 3]); 268 268 + 269 269 + pipe( 270 270 + fromCallbag(callbag), 271 271 + subscribe(e => console.log(e)) 272 272 + ); // Prints 1 2 3 to the console. 273 273 + ``` 274 274 + 275 275 + ## interval 276 276 + 277 277 + `interval` creates a source that emits values after the given amount of milliseconds. 278 278 + Internally it uses `setInterval` to accomplish this. 279 279 + 280 280 + > _Note:_ This source is only available in JavaScript environments, and will be excluded 281 281 + > when compiling natively. 282 282 + 283 283 + ```reason 284 284 + Wonka.interval(50) 285 285 + |> Wonka.subscribe((. x) => Js.log(x)); 286 286 + /* Prints 0 1 2... to the console. */ 287 287 + /* The incrementing number is logged every 50ms */ 288 288 + ``` 289 289 + 290 290 + ```typescript 291 291 + import { pipe, interval, subscribe } from 'wonka'; 292 292 + 293 293 + pipe( 294 294 + interval(50), 295 295 + subscribe(e => console.log(e)) 296 296 + ); // Prints 0 1 2... to the console. 297 297 + // The incrementing number is logged every 50ms 298 298 + ``` 299 299 + 191 300 ## empty 192 301 193 302 This is a source that doesn't emit any values when subscribed to and

+17

docs/getting-started.md

reviewed

··· 117 117 118 118 It's worth noting that most callbacks in Wonka need to be explicitly uncurried, since 119 119 this will help them compile cleanly to JavaScript. 120 120 + 121 121 + ## Interoperability 122 122 + 123 123 + In JavaScript environments, Wonka comes with several utilities that make it easier 124 124 + to interoperate with JavaScript primitives and other libraries: 125 125 + 126 126 + - [`fromPromise`](./api/sources.md#frompromise) & [`toPromise`](./api/sinks.md#topromise) can be used to interoperate with Promises 127 127 + - [`fromObservable`](./api/sources.md#fromobservable) & [`toObservable`](./api/sinks.md#toobservable) can be used to interoperate with spec-compliant Observables 128 128 + - [`fromCallbag`](./api/sources.md#fromcallbag) & [`toCallbag`](./api/sinks.md#tocallbag) can be used to interoperate with spec-compliant Callbags 129 129 + 130 130 + Furthermore there are a couple of operators that only work in JavaScript environments 131 131 + since they need timing primitives, like `setTimeout` and `setInterval`: 132 132 + 133 133 + - [`delay`](./api/operators.md#delay) 134 134 + - [`debounce`](./api/operators.md#debounce) 135 135 + - [`throttle`](./api/operators.md#throttle) 136 136 + - [`interval`](./api/sources.md#interval)

+1 -2

src/web/wonkaJs.d.ts

reviewed

··· 1 1 /* operators */ 2 2 export * from './wonka_operator_debounce'; 3 3 export * from './wonka_operator_delay'; 4 4 - export * from './wonka_operator_interval'; 5 5 - export * from './wonka_operator_sample'; 6 4 export * from './wonka_operator_throttle'; 7 5 8 6 /* sinks */ 9 7 export * from './wonka_sink_toPromise'; 10 8 11 9 /* sources */ 10 10 + export * from './wonka_source_interval'; 12 11 export * from './wonka_source_fromDomEvent'; 13 12 export * from './wonka_source_fromListener'; 14 13 export * from './wonka_source_fromPromise';

+1 -2

src/web/wonkaJs.re

reviewed

··· 1 1 /* operators */ 2 2 include Wonka_operator_debounce; 3 3 include Wonka_operator_delay; 4 4 - include Wonka_operator_interval; 5 5 - include Wonka_operator_sample; 6 4 include Wonka_operator_throttle; 7 5 8 6 /* sinks */ 9 7 include Wonka_sink_toPromise; 10 8 11 9 /* sources */ 10 10 + include Wonka_source_interval; 12 11 include Wonka_source_fromDomEvent; 13 12 include Wonka_source_fromListener; 14 13 include Wonka_source_fromPromise;

src/web/wonka_operator_interval.d.ts src/web/wonka_source_interval.d.ts

reviewed

src/web/wonka_operator_interval.re src/web/wonka_source_interval.re

reviewed

src/web/wonka_operator_interval.rei src/web/wonka_source_interval.rei

reviewed

src/web/wonka_operator_sample.d.ts src/operators/wonka_operator_sample.d.ts

reviewed

src/web/wonka_operator_sample.re src/operators/wonka_operator_sample.re

reviewed

src/web/wonka_operator_sample.rei src/operators/wonka_operator_sample.rei

reviewed

+1

src/wonka.d.ts

reviewed

··· 16 16 export * from './operators/wonka_operator_onEnd'; 17 17 export * from './operators/wonka_operator_onPush'; 18 18 export * from './operators/wonka_operator_onStart'; 19 19 + export * from './operators/wonka_operator_sample'; 19 20 export * from './operators/wonka_operator_scan'; 20 21 export * from './operators/wonka_operator_share'; 21 22 export * from './operators/wonka_operator_skip';

+1

src/wonka_operators.re

reviewed

··· 7 7 include Wonka_operator_onEnd; 8 8 include Wonka_operator_onPush; 9 9 include Wonka_operator_onStart; 10 10 + include Wonka_operator_sample; 10 11 include Wonka_operator_scan; 11 12 include Wonka_operator_share; 12 13 include Wonka_operator_skip;