callbag-common

A collection of commonly used utilities for creating / working with reactive streams or iterables. Included utilities follow the callbag specification.

1link$npm i callbag-common

👉 If you do not know what reactive streams or callbags are, read this post first.

linkExample Usage

Create a source using a source factory:

1linkimport { interval } from 'callbag-common';

2link

3linkconst source = interval(1000) // --> emit every second

Transform your sources by piping them into some operators:

1linkimport { pipe, interval, map, filter } from 'callbag-common';

2link

3linkconst source = interval(1000) // --> emit every second

4linkpipe(

5link  source,

6link  map(x => x * 3),            // --> multipy by 3

7link  filter(x => x % 2),         // --> only allow odd numbers

8link)

Subscribe to your transformed source:

1link​import { interval, pipe, map, filter, subscribe } from 'callbag-common'

2link​

3link​const source = interval(1000) // --> emits every second

4link​pipe(

5link​  source,

6link​  map(x => x * 3),            // --> multiply by 3

7link​  filter(x => x % 2),         // --> only allow odd numbers

8link​  subscribe(console.log)      // --> log any incoming number

9link​)

10link​

 3
 9
 15
 21
 27

linkIncluded Utilities

linkSource Factories

• of: Convert static value(s) to a callbag.
• fromEvent: Listen to DOM event.
• fromPromise: Converts a promise to a callbag.
• interval: Emits an increasing number at given intervals.

linkOperators

• map: Transforms incoming values.
• filter: Filters incoming values.
• take: Take a maximum number of values from source.
• startWith: Start with given values.

• flatten: Flattens higher-order callbags.
• debounce: Debounces incoming values.
• scan: Combine consecutive values from source.

linkComination

• expr: Create expressions from other callbags.
• merge: Merges given callbags, emitting when each one emits.
• combine: Combines given callbags, emits arrays of latest values of each.

linkUtilities

• pipe: Pipes sources to operators to sinks.
• subscribe: Subscribes to given callbag.
• tap: Taps into given callbag (without subscribing).
• source: Turns values to callbag sources, keeping callbags as is.

linkWhy Callbags?

• They are pretty fast
• They are light-weight (this library is ~1.8kB total)
• They are simple and predictable
• They work seamlessly for iterable programming

👉 Read more

linkWhy a Collection?

A key aspect of callbag spec is its simplicity, which makes tools and utilities built around it pretty simple as well, leading to a an iterative and high-quality decentralized eco-system of community-maintained tools.

The down-side of such an eco-system is that discovering and using necessary libraries becomes more difficult. The callbag wiki acts as a good reference, but it can be daunting for new-comers to go through it and find what they need. Besides, importing from multiple libraries becomes more inconvenient, specifically with incosistent export conventions:

1linkimport pipe from 'callbag-pipe'

2linkimport subscribe from 'callbag-subscribe';

3linkimport map from 'callbag-map';

4linkimport filter from 'callbag-filter';

5linkimport flatten from 'callbag-flatten';

6linkimport { debounce } from 'callbag-debounce';

7linkimport { expr } from 'callbag-expr';

A collection solves these issues, as discovery of basic utilities (or utilities for a specific purpose) is already done by collection maintainers and imports become much easier as well:

1linkimport { pipe, subscribe, map, filter, flatten } from 'callbag-common';

linkWhy this Collection?

A strict collection can only be as agile as its least agile module. callbag-common, on the other hand:

• Provides external libraries, whenever possible.
• Provides internal stand-ins, whenever external counterparts are slow to catch up on their issues.

Additionally, it specifically targets TypeScript / ES6, and only includes callbags that are commonly used in real-life projects. This means while it gets all the benefits of a decentralized eco-system, it also always guarantees functionality and type safety.