Home

Itrabble Documentation

Usage

// given some defined iterables
const array = ['a','b','c','d','e','f']

const map = new Map([['a', 'a'],['b', 'b'], ['c', 'c'],['d','d'],['e','e'],['f','f']])

const string = 'test string'

There are currently 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:

const itrabble = require('itrabble')

itrabble(array).skipUntil(x => x === 'd')
//  => 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

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.

require('itrabble/lib/object-prototype-decorator')

/* Array */
array.itrabble.skipUntil(x => x === 'd')
//  => iterable sequence { d e f }

/* Map */
map.itrabble.takeUntil(xs => xs.includes('e'))
//  => iterable sequence { [ 'a', 'A' ] [ 'b', 'B' ] [ 'c', 'C' ] [ 'd', 'D' ] }

/* String */
string.itrabble.takeUntil(x => x === 'i')
//  => iterable sequence { test str }

// All together now
array.itrabble.zip( array, map, string ).take(3)
/* => iterable sequence {
 *  [ 'a', 'a', [ 'a', 'A' ], 't' ] [ 'b', 'b', [ 'b', 'B' ], 'e' ] [ 'c', 'c', [ 'c', 'C' ], 's' ]
 * }
*/

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

itrabble(array).skipUntil(x => x === 'd').first() // or array.itrabble.skipUntil(x => x === 'd').first()
// => 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:

const skipped = itrabble(array).skipUntil(x => x === 'd')

// ... operator
console.log(...skipped)
//  => d e f

// for of loop
for (let value of skipped){
  console.log(value)
}
/*
 * => d
 * => e
 * => f
*/

// selected iteration through destructuring
const [ d, e, f ] = skipped
/*
  console.log(d) => d
  console.log(e) => e
  console.log(f) => f
*/

or alternatively specify the format with the following methods:

/* Array */
itrabble(array).takeUntil(x => x === 'e').toArray()
// => ['a','b','c','d']

/* Map */
itrabble(map).takeUntil(x => x.includes('e')).toMap()
// => Map { 'a' => 'a', 'b' => 'b', 'c' => 'c', 'd' => 'd' }

/* Set */
itrabble(array).takeUntil(x => x === 'e').toSet()
// => Set { 'a', 'b', 'c', 'd' }

Individual Exports Usage

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:

import take from 'itrabble/lib/take'

const array = ['a','b','c']
const firstTwo = array::take(2)
// => iterable sequence { a b }

View documentation of methods