event-creek v0.7.0

Creek

Creek is a minimalistic functional reactive streams library.

Motivation and Goals

Creek is created with the intent of condensing the powerful concepts of the functional reactive programming in a compact, and handy package. The project is aimed at delivering an ad-hoc, independent, extensible, lightweight, and functional API for building reactive applications.

Overview

The functional reactive programming is a programming pattern (or a paradigm if you like) that can be summarized to: abstracting the I/O as a sequence of events and implementing the logic of the program in a declarative way by using the tools of the functional programming - map, filter, reduce, etc.

A Creek application consists of a stream, and operations. The operations are just functions that follow a specific convention. They receive an event payload, or message, as an argument and are expected to return a processed result. The stream organizes the operations in a queue, in which every operation passes the result of its execution to the next.

Getting Started

Installation

npm i event-creek

Example usage

import {stream, reduce, map} from 'event-creek';

Assuming there are some controls in the view:

<button id="increment">+</button>
<span id="count">0</span>
<button id="decrement">-</button>

Define the actions of the buttons.

const incrementer = count => count + 1;
const decrementer = count => count - 1;

Define a stream implementing the logic of the application.

const applyAction = (count, action) => action(count);
const toText = count => `The current count is ${count}`;
const render = count => document.getElementById('count').innerHTML = count;
const initialCount = 0;

const dispatch = stream(reduce(applyAction, initialCount), map(toText), map(render));

The first operation is a reduce operation - with the help of applyAction function executes the incoming actions over the current count and then overwrites it with the result. The result is also passed to the next map operation that converts it to a text. The text result is passed to the render with another map operation.

Attach event listeners that injects the actions when the corresponding buttons are clicked.

document.getElementById('increment').addEventListener('click', () => dispatch(incrementer));
document.getElementById('decrement').addEventListener('click', () => dispatch(decrementer));

API reference

For the examples below, the following definition is in place:

function output(message) {
	console.log(message);
}

stream(...operations)

Constructs a stream function from the list of operations. The operations are functions with two arguments operation(message, next), where message is the message that is passed down the stream and next is a callback function, next(message), that may to be called by the operation to pass a message down the stream.

function operation(message, next) {
	next('modified ' + message);
}

Creek provides operation factories for the traditional operations on sequences: map, flatMap, filter, and reduce.

The result is a function that injects messages into the stream.

const dispatch = stream(operation, output);
dispatch('message');

Result:

modified message

map(rule)

Creates an operation that will runs rule(message) on every message and injects the result into the stream.

const dispatch = stream(map(x => x * 2), output);

Result:

> dispatch(1);
2

> dispatch(2);
4

> dispatch(3);
6

flatMap(rule)

Creates an operation that will runs rule(message) on every message and (separately) injects the items of the resulting array into the stream.

const dispatch = stream(flatMap(x => [x, -x]), output);

Result:

> dispatch(1);
1
-1

> dispatch(2);
2
-2

filter(condition)

Returns a filtering operation that will run the expression condition(message) on every incoming message and will pass back into the stream only if the result of the expression is true.

const dispatch = stream(filter(x => x > 1), output);

Result:

> dispatch(1);
> dispatch(2);
2

> dispatch(3);
3

reduce(rule, initial)

Returns an operation that applies the given rule function against an accumulator and each incoming message and inject the result back into the stream. On the first run, the rule function will receive the initial value as a value of the accumulator. On the subsequent runs the value of the accumulator will be the result of the previous execution.

const rule = (accumulator, x) => accumulator + x;
const example = stream(reduce(rule, 10), output);

Result:

> dispatch(1);
11

> dispatch(2);
13

> dispatch(3);
16

Building

Creek's development environment depends on having npm and git installed.

Grab a copy of the repository.

git clone https://github.com/zvchei/creek.git

Navigate in the newly created directory and install the dependencies.

cd creek
npm install

Generate a bundled ES6 module.

npm run build-es

The module will be created as creek.es.js in the lib directory.

It is also possible to build a distribution package.

npm run build-dist

A compressed, production-ready UMD module creek.umd.min.js will be generated in dist. An uncompressed version will also be available as creek.umd.js in lib.

The build scripts depend on rollup, so with a little bit of tweaking various types of modules could be generated.

Testing

Clone the repository and install the dependencies if needed.

git clone https://github.com/zvchei/creek.git
cd creek
npm install

Then execute the tests:

npm test

Or generate a test coverage report:

npm run coverage

License

This project is licensed under the MIT License.