···
19
-
**Work in Progress:** Please come back in — let's say — one week! :tada:
19
+
* [What is `Wonka`](#what-is-wonka)
20
+
* [Why it exists](#why-it-exists)
21
+
* [Installation](#installation)
22
+
* [Getting Started](#getting-started)
23
+
* [Documentation (In Progress)](#documentation)
27
+
`Wonka` is a library for lightweight observables and iterables loosely based on the [callbag spec](https://github.com/callbag/callbag).
28
+
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
29
+
iterable set of data into streams, and manipulate these streams.
33
+
Reason has been becoming increasingly popular, but it's missing a good pattern for streams that feels native to the language.
34
+
The functional nature of callbags make them a perfect starting point to fix this, and to introduce a reactive programming
35
+
pattern to a language that is well suited for it.
37
+
Hence `Wonka` is a library that aims to make complex streams of data easy to deal with.
41
+
Install the library first: `yarn add wonka` or `npm install --save wonka`,
43
+
Then add `wonka` to `bs-dependencies` in your `bsconfig.json` file like so:
47
+
"name": "<your name>",
50
+
"bsc-flags": ["-bs-super-errors"],
51
+
"bs-dependencies": [
59
+
Writing your first stream is very easy! Let's suppose you would like to create a stream from a list, filter out some values,
60
+
then map over the remaining ones, and lastly iterate over the final values.
62
+
This can be done with a few operators that might remind you of functions you would also call on iterables.
65
+
let example = [1, 2, 3, 4, 5, 6];
67
+
Wonka.fromList(example)
68
+
|> Wonka.filter(x => x mod 2 === 0)
69
+
|> Wonka.map(x => x * 2)
70
+
|> Wonka.forEach(x => print_endline(string_of_int(x)));
72
+
/* prints: 4, 8, 12 */
75
+
To explain what's going on:
77
+
- `fromList` creates a pullable source with values from the list
78
+
- `filter` only lets even values through
79
+
- `map` multiplies the values by `2`
80
+
- `forEach` pulls values from the resulting source and prints them
82
+
As you can see, all helpers that we've used are exposed on the `Wonka` module.
83
+
But if we would like to use JavaScript-based APIs, then we need to use the `WonkaJs` module.
85
+
Let's look at the same example, but instead of a list we will use an `interval` stream.
86
+
This stream will output ascending numbers starting from `0` indefinitely.
88
+
We will code the same example as before but we'd like the `interval` to push
89
+
a new number every `50ms` and to stop after seven values.
92
+
WonkaJs.interval(50)
94
+
|> Wonka.filter(x => x mod 2 === 0)
95
+
|> Wonka.map(x => x * 2)
96
+
|> Wonka.forEach(x => print_endline(string_of_int(x)));
98
+
/* prints: 4, 8, 12 */
101
+
The last three functions stay the same, but we are now using `interval` as our source.
102
+
This is a listenable source, meaning that it pushes values downwards when it sees fit.
103
+
And the `take` operator tells our source to stop sending values after having received seven
106
+
And already you have mastered all the basics of `Wonka` and learned about a couple of its operators!
111
+
I am currently still working on getting some documentation up and running. Those will contain:
113
+
- The API, i.e. a list of all helpers
115
+
- Usage Guides & Recipes
116
+
- Developer Guides (How to write a source/operator/sink)
117
+
- Modified Callbag spec
119
+
Stay tuned and read the signature files in the meantime please:
121
+
- [wonka.rei](./src/wonka.rei)
122
+
- [wonkaJs.rei](./src/wonka.rei)
kitten.sh