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