itrabble

Library to extend JavaScript ES6 iterables

Examples

API Documentation

Features

• small 920 bytes (ESM) with all dependencies, minified and brotlied.
• No dependencies.
• hand-crafted by single artisan developer - not mass produced by large corporation-backed open-source team.
• fun name to reference in your project dependencies

Why?

I know there are lots of other libraries that already do this kind of thing, and do it very well, providing the ability to extend ordinary JavaScript objects to be able to enjoy the breadth of functionality of say, a Ruby standard library object. For example Lodash.

The twist that interested me was to be able to incorporate the recent additions to the JavaScript language that make it possible to iterate through infinite sequences, evaluated lazily, with a handy range of methods. Plus having these methods work in a uniform way regardless of whether the source is an Array, a Map, a Set, a String or some form of TypedArray or stream. Or even a user-created object that has its own unique behaviour.

I wrote this mainly as a fun exercise for myself and a way to learn about the ES2015 features in more depth. I plan to add more utility functions as I see the need/think of them, or if people using the module request them.

Requirements

For a Node environment, you'll need a node version of at least 6.11.1 because this library uses a large number of the features introduced in ES2015 (iterators, generator functions, and rest/spread operators to name a few).

Changes from v1.0.1 -> v1.1.0

See here

Usage

install with npm:

npm install --save itrabble

Examples

1// define some iterables
2const array = ['a', 'b', 'c', 'd', 'e', 'f'];
3
4const map = new Map([
5  ['a', 'A'],
6  ['b', 'B'],
7  ['c', 'C'],
8  ['d', 'D'],
9  ['e', 'E'],
10  ['f', 'F'],
11]);
12
13const string = 'test string';

As of v1.1.0 there are now three ways to use the library.

Standard Usage

The easiest way is to use the imported module as a function to wrap the iterable object you wish to extend:

1const itrabble = require('itrabble');
2
3itrabble(array).skipUntil((x) => x === 'd');
4//  => iterable sequence { d e f }

Alternative Usage

Another way is to import the object-prototype-decorator nested module into scope and then call the itrabble property on any entity that has the following:

• Object in its prototype
• The Symbol.iterator property

In the previous version v1.0.1 this happened by default. It is now opt-in.

As the name suggests, this does modify the Object prototype. It's unlikely that the property itrabble will clash with any existing namespace, but it's good to be aware of what this is doing if you are going to use it.

1require('itrabble/lib/object-prototype-decorator');
2
3/* Array */
4array.itrabble.skipUntil((x) => x === 'd');
5//  => iterable sequence { d e f }
6
7/* Map */
8map.itrabble.takeUntil((xs) => xs.includes('e'));
9//  => iterable sequence { [ 'a', 'A' ] [ 'b', 'B' ] [ 'c', 'C' ] [ 'd', 'D' ] }
10
11/* String */
12string.itrabble.takeUntil((x) => x === 'i');
13//  => iterable sequence { test str }
14
15// All together now
16array.itrabble.zip(array, map, string).take(3);
17/* => iterable sequence {
18 *  [ 'a', 'a', [ 'a', 'A' ], 't' ] [ 'b', 'b', [ 'b', 'B' ], 'e' ] [ 'c', 'c', [ 'c', 'C' ], 's' ]
19 * }
20 */

The methods called on an instance of itrabble return an itrabble iterator over the updated sequence, which means they can be chained.

1itrabble(array)
2  .skipUntil((x) => x === 'd')
3  .first(); // or array.itrabble.skipUntil(x => x === 'd').first()
4// => iterable sequence { d e f } => iterable sequence { d }

In order to consume the actual values of the returned iterator, you can use one of the following standard ES2015 calls:

1const skipped = itrabble(array).skipUntil((x) => x === 'd');
2
3// ... operator
4console.log(...skipped);
5//  => d e f
6
7// for of loop
8for (let value of skipped) {
9  console.log(value);
10}
11/*
12 * => d
13 * => e
14 * => f
15 */
16
17// selected iteration through destructuring
18const [d, e, f] = skipped;
19/*
20  console.log(d) => d
21  console.log(e) => e
22  console.log(f) => f
23*/

or alternatively specify the format with the following methods:

1/* Array */
2itrabble(array)
3  .takeUntil((x) => x === 'e')
4  .toArray();
5// => ['a','b','c','d']
6
7/* Map */
8itrabble(map)
9  .takeUntil((x) => x.includes('e'))
10  .toMap();
11// => Map { 'a' => 'a', 'b' => 'b', 'c' => 'c', 'd' => 'd' }
12
13/* Set */
14itrabble(array)
15  .takeUntil((x) => x === 'e')
16  .toSet();
17// => Set { 'a', 'b', 'c', 'd' }

v1.1.0

The main way of using the module hasn't changed, for example:

1const itrabble = require('itrabble');
2
3itrabble(array).skipUntil((x) => x === 'd');
4//  => iterable sequence { d e f }

However if you were previously using the following syntax:

1require('itrabble');
2
3array.itrabble.skipUntil((x) => x === 'd');

This has been updated to:

1require('itrabble/lib/object-prototype-decorator');
2
3array.itrabble.skipUntil((x) => x === 'd');

As the name suggests more clearly now, this does modify the Object prototype. It's unlikely that the property itrabble will clash with any existing namespace, but it's good to be aware of what this is doing if you are going to use it.

Individual Exports

itrabble now provides a way to access the individual methods as separate exports which can be imported on a per-use basis, unattached to the rest of the itrabble module.

An ideal way to use this would be with the (somewhat) proposed bind operator ::. The proposal is on Github, and there is a Babel transform for this which describes the idea well. It hasn't progressed past stage 0 and seems to have lost momentum, so while it's probably not appropriate for production code I really like it. For example:

1import take from 'itrabble/lib/take';
2
3const array = ['a', 'b', 'c'];
4const firstTwo = array::take(2);
5// => iterable sequence { a b }

---

Acknowledgements

Thanks to @wouterken for the interest and help with this!

Contributing

This project is open to contributions. Please read the Code of Conduct before doing anything else.

Please open an issue to point out anything broken, lacking or otherwise worth mentioning.

For development:

fork and clone the repo

Given the minimum required version of Node of 6.11.1 there's not a lot to set up to get going.

install dependencies npm install

to run tests in watch mode npm run test:watch

or for a coverage report npm test

Related

You might find these related libraries & blog posts interesting

Dr Axel Rauschmayer explains ES6 iteration

IXJS - Interactive Extensions for JavaScript

Lodash

License

MIT © Alex Revell