wonka

What is wonka?

The wonka package is a lightweight but powerful stream library for TypeScript and JavaScript. It allows for the creation, manipulation, and consumption of streams of values over time. It's particularly useful for handling asynchronous operations and events in a functional reactive programming style.

What are wonka's main functionalities?

Creating streams

This feature allows for the creation of streams from various sources. In this example, a stream is created from an array.

import { fromArray } from 'wonka';
const stream = fromArray([1, 2, 3]);

Transforming streams

This feature demonstrates how to transform streams using operators like `map`. In the example, each value in the stream is doubled.

import { fromArray, map } from 'wonka';
const stream = fromArray([1, 2, 3]);
const doubled = map(x => x * 2)(stream);

Consuming streams

This feature shows how to consume streams. The `forEach` operator is used to log each value from the stream to the console.

import { fromArray, forEach } from 'wonka';
const stream = fromArray([1, 2, 3]);
forEach(x => console.log(x))(stream);

Other packages similar to wonka

rxjs

RxJS is a comprehensive library for reactive programming using Observables. It offers a wider range of operators than wonka, making it more powerful but also larger in size. It's well-suited for complex data flow scenarios.

xstream

xstream is a library designed for creating and working with streams of values. It's similar to wonka in its focus on streams but differs in API and operator availability. It's known for its simplicity and small bundle size.

most

Most.js is a high-performance reactive programming library. It focuses on providing a rich set of operators for composing asynchronous and event-based programs. It's known for its speed and efficiency compared to other streaming libraries.

README

Wonka

A fast push & pull stream library for Reason, loosely following the callbag spec

“There’s no earthly way of knowing
Which direction we are going
There’s no knowing where we’re rowing
Or which way the river’s flowing” － Willy Wonka

• What is Wonka
• Why it exists
• Installation
• Getting Started
• Documentation (In Progress)

What is Wonka

Wonka is a library for lightweight observables and iterables loosely based on the callbag spec. 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.

Why it exists

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.

Installation

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:

{
  "name": "<your name>",
  "version": "0.1.0",
  "sources": ["src"],
  "bsc-flags": ["-bs-super-errors"],
  "bs-dependencies": [
+    "wonka"
  ]
}

Getting Started

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)));

/* prints: 4, 8, 12 */

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.

WonkaJs.interval(50)
  |> Wonka.take(7)
  |> Wonka.filter((.x) => x mod 2 === 0)
  |> Wonka.map((.x) => x * 2)
  |> Wonka.forEach((.x) => print_endline(string_of_int(x)));

/* prints: 4, 8, 12 */

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 values.

And already you have mastered all the basics of Wonka and learned about a couple of its operators! Go, you! :tada:

Documentation

I am currently still working on getting some documentation up and running. Those will contain:

• The API, i.e. a list of all helpers
• Examples
• 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
• wonkaJs.rei