Chimes

Array.prototype iteration methods for any iterator.

The new iterable data structures in ES6 are hard to justify using as they're severely lacking in expressive power when compared to Arrays. This library's goal is to add all the expressive power of Arrays to anything iterable, including generators.

Current implementation is porcelain for future sugar.

Installation

npm install chimes

Requires an ES6 transpiler such as 6to5, traceur or a polyfill like core-js.

Usage

Most methods work just as they do for Array.prototype, though they take the iterable as the first argument and always return an iterator.

Note that even every, some & reduce return iterators – the last value in the iterator is the value you'd expect from the corresponding Array.prototype method.

An iterable is any object that implements Symbol.iterator or a generator.

const {map} = require('chimes')

let set = new Set()
set.add(1)
set.add(2)
set.add(3)

let doubleSet = new Set(map(set, (value, i) => value * 2))
console.log(doubleSet.has(1)) // false
console.log(doubleSet.has(2)) // true
console.log(doubleSet.has(4)) // true
console.log(doubleSet.has(6)) // true
console.log(Array.from(doubleSet))
// [2,4,6]

API

Methods Implemented

• map
• filter
• every
• some
• reduce
• concat

Helpers

• first
• last

map(iterable, fn, context)

Creates a new Iterator with the results of lazily calling fn on every element in the supplied iterable.

Array.prototype.map for Iterables.

const {map} = require('chimes')

let set = new Set()
set.add(1)
set.add(2)
set.add(3)

let doubleSet = new Set(map(set, value => value * 2))
console.log(doubleSet.has(1)) // false
console.log(doubleSet.has(2)) // true
console.log(doubleSet.has(4)) // true
console.log(doubleSet.has(6)) // true
console.log(Array.from(doubleSet))
// [2,4,6]

Parameters

iterable: Iterable, Creates a new Iterator with the results of lazily calling fn on every element in the supplied iterable. fn: function, Will be invoked with: value, index & iteration object context: Mixed, Optional. Value to use as this when executing fn. Returns: Iterator

filter(iterable, fn, context)

Creates a new Iterator with all elements in the supplied iterable that pass the test implemented by fn. fn is applied lazily.

Array.prototype.filter for iterables.

const {filter} = require('chimes')

let isEven = value => value % 2 === 0
let size = 5
let evenNumbers = filter(function* () {
  while(size--) yield size
}, isEven)

Array.from(evenNumbers) // [ 4, 2, 0 ]

Parameters

iterable: Iterable, Creates a new Iterator with all elements in the supplied iterable that pass the test implemented by fn. fn is applied lazily.

fn: function, Will be invoked with: value, index & iteration object

context: Mixed, Optional. Value to use as this when executing fn.

Returns: Iterator

every(iterable, fn, context)

Creates a new Iterator which tests whether all elements that have passed through the iterator thus far pass the test implemented by fn. fn is applied lazily.

Array.prototype.every for iterables.

const {every} = require('chimes')

let isEven = value => value % 2 === 0
let size = 5
let allEven = every(new Set([2,4,6]), isEven)
let notAllEven = every(new Set([2,3,6]), isEven)

Array.from(allEven.next().value) // true
Array.from(notAllEven.next().value) // false

Parameters

iterable: Iterable, Creates a new Iterator which tests whether all elements that have passed through the iterator thus far pass the test implemented by fn. fn is applied lazily.

fn: function, Will be invoked with: value, index & iteration object

context: Mixed, Optional. Value to use as this when executing fn.

Returns: Iterator

some(iterable, fn, context)

Creates a new Iterator which tests whether any elements that have passed through the iterator thus far pass the test implemented by fn. fn is applied lazily.

Array.prototype.some for iterables.

const {some} = require('chimes')

let isEven = value => value % 2 === 0
let allEven = some(new Set([2,4,6]), isEven)
let someEven = some(new Set([2,3,6]), isEven)
let noneEven = some(new Set([1,3,5]), isEven)

Array.from(allEven.next().value) // true
Array.from(someEven.next().value) // true
Array.from(noneEven.next().value) // false

Parameters

iterable: Iterable, Creates a new Iterator which tests whether any elements that have passed through the iterator thus far pass the test implemented by fn. fn is applied lazily.

fn: function, Will be invoked with: value, index & iteration object

context: Mixed, Optional. Value to use as this when executing fn.

Returns: Iterator

reduce(iterable, fn, initialValue)

Creates a new Iterator that lazily applies fn against an accumulator. Each step of the iteration reduces it to a single value.

Array.prototype.reduce for iterables.

const {reduce} = require('chimes')

let addNumbers = (init, value, i) => init + value
let total = reduce(new Set([1,2,3]), addNumbers, 0))
let otherTotal = reduce(new Set([1,2,3]), addNumbers, 1))

Array.from(total.next().value) // 6
Array.from(otherTotal.next().value) // 7

Parameters

iterable: Iterable, Creates a new Iterator that lazily applies fn against an accumulator. Each step of the iteration reduces it to a single value.

fn: function, Will be invoked with: previousValue, currentValue, index & iteration object.

initialValue: Mixed, Optional. Object to use as the first argument to the first call of fn.

Returns: Iterator

concat(iterable, )

Creates a new Iterator comprising of the first iterable joined with the second iterable.

Array.prototype.concat for iterables.

const {concat} = require('chimes')

let set = new Set([1,2,3])
let array = [4,5,6]
let joined = concat(set, array)
for (let item in joined) {
  console.log(item)
}
// 1
// 2
// 3
// 4
// 5
// 6

Parameters

iterable: Iterable, Creates a new Iterator comprising of the first iterable joined with the second iterable.

concat: Iterable, Creates a new Iterator comprising of the first iterable joined with the second iterable.

Array.prototype.concat for iterables.

Returns: Iterator

last(iterable)

Creates a new Iterator that simply contains the last element of iterable.

const {last} = require('chimes')

for (let item in last(new Set([2,4,6]))) {
  console.log(item) // 6
}

Parameters

iterable: Iterable, Creates a new Iterator that simply contains the last element of iterable.

Returns: Iterator

first(iterable)

Creates a new Iterator that simply contains the first element of iterable.

const {first} = require('chimes')

for (let item in first(new Set([2,4,6]))) {
  console.log(item) // 2
}

Parameters

iterable: Iterable, Creates a new Iterator that simply contains the first element of iterable.

Returns: Iterator

License

MIT