kitten.sh
1# Wonka
2
3A fast push & pull stream library for Reason, loosely following the [callbag spec](https://github.com/callbag/callbag)
4
5[](https://travis-ci.org/kitten/wonka)
6[](https://coveralls.io/github/kitten/wonka?branch=master)
7[](https://www.npmjs.com/package/wonka)
8[](https://www.npmjs.com/package/wonka)
9
10> “There’s no earthly way of knowing<br>
11> Which direction we are going<br>
12> There’s no knowing where we’re rowing<br>
13> Or which way the river’s flowing” － **Willy Wonka**
14
15<br>
16
17
18
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)
24
25## What is `Wonka`
26
27`Wonka` is a library for lightweight observables and iterables loosely based on the [callbag spec](https://github.com/callbag/callbag).
28It exposes a set of helpers to create and transform sources and output sinks, meaning it helps you to turn an event source or an
29iterable set of data into streams, and manipulate these streams.
30
31## Why it exists
32
33Reason has been becoming increasingly popular, but it's missing a good pattern for streams that feels native to the language.
34The functional nature of callbags make them a perfect starting point to fix this, and to introduce a reactive programming
35pattern to a language that is well suited for it.
36
37Hence `Wonka` is a library that aims to make complex streams of data easy to deal with.
38
39## Installation
40
41Install the library first: `yarn add wonka` or `npm install --save wonka`,
42
43Then add `wonka` to `bs-dependencies` in your `bsconfig.json` file like so:
44
45```diff
46{
47 "name": "<your name>",
48 "version": "0.1.0",
49 "sources": ["src"],
50 "bsc-flags": ["-bs-super-errors"],
51 "bs-dependencies": [
52+ "wonka"
53 ]
54}
55```
56
57## Getting Started
58
59Writing your first stream is very easy! Let's suppose you would like to create a stream from a list, filter out some values,
60then map over the remaining ones, and lastly iterate over the final values.
61
62This can be done with a few operators that might remind you of functions you would also call on iterables.
63
64```reason
65let example = [1, 2, 3, 4, 5, 6];
66
67Wonka.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)));
71
72/* prints: 4, 8, 12 */
73```
74
75To explain what's going on:
76
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
81
82As you can see, all helpers that we've used are exposed on the `Wonka` module.
83But if we would like to use JavaScript-based APIs, then we need to use the `WonkaJs` module.
84
85Let's look at the same example, but instead of a list we will use an `interval` stream.
86This stream will output ascending numbers starting from `0` indefinitely.
87
88We will code the same example as before but we'd like the `interval` to push
89a new number every `50ms` and to stop after seven values.
90
91```reason
92WonkaJs.interval(50)
93 |> Wonka.take(7)
94 |> Wonka.filter((.x) => x mod 2 === 0)
95 |> Wonka.map((.x) => x * 2)
96 |> Wonka.forEach((.x) => print_endline(string_of_int(x)));
97
98/* prints: 4, 8, 12 */
99```
100
101The last three functions stay the same, but we are now using `interval` as our source.
102This is a listenable source, meaning that it pushes values downwards when it sees fit.
103And the `take` operator tells our source to stop sending values after having received seven
104values.
105
106And already you have mastered all the basics of `Wonka` and learned about a couple of its operators!
107Go, you! :tada:
108
109## Documentation
110
111I am currently still working on getting some documentation up and running. Those will contain:
112
113- The API, i.e. a list of all helpers
114- Examples
115- Usage Guides & Recipes
116- Developer Guides (How to write a source/operator/sink)
117- Modified Callbag spec
118
119Stay tuned and read the signature files in the meantime please:
120
121- [wonka.rei](./src/wonka.rei)
122- [wonkaJs.rei](./src/wonka.rei)
123