Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including iterare with all npm packages installed. Try it out:

var iterare = require("iterare")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

iterare v0.0.8

Array methods for ES6 Iterators

iterare

lat. to repeat, to iterate

Version Downloads Build Status Coverage Dependency Status Node Version License Gitter

ES6 Iterator library for applying multiple transformations to a collection in a single iteration.

API Documentation

Motivation

Ever wanted to iterate over ES6 collections like Map or Set with Array-built-ins like map(), filter(), reduce()? Lets say you have a large Set of URIs and want to get a Set back that contains file paths from all file:// URIs.

The loop solution is very clumsy and not very functional:

const uris = new Set([
  'file:///foo.txt',
  'http:///npmjs.com',
  'file:///bar/baz.txt'
])
const paths = new Set()
for (const uri of uris) {
  if (!uri.startsWith('file://')) {
    continue
  }
  const path = uri.substr('file:///'.length)
  paths.add(path)
}

Much more readable is converting the Set to an array, using its methods and then converting back:

new Set(
  Array.from(uris)
    .filter(uri => uri.startsWith('file://'))
    .map(uri => uri.substr('file:///'.length))
)

But there is a problem: Instead of iterating once, you iterate 4 times (one time for converting, one time for filtering, one time for mapping, one time for converting back). For a large Set with thousands of elements, this has significant overhead.

Other libraries like RxJS or plain NodeJS streams would support these kinds of "pipelines" without multiple iterations, but they work only asynchronously.

With this library you can use many methods you know and love from Array and lodash while only iterating once - thanks to the ES6 iterator protocol:

import iterate from 'iterare'

iterate(uris)
  .filter(uri => uri.startsWith('file://'))
  .map(uri => uri.substr('file:///'.length))
  .toSet()

iterate accepts any kind of Iterator or Iterable (arrays, collections, generators, ...) and returns a new Iterator object that can be passed to any Iterable-accepting function (collection constructors, Array.from(), for of, ...). Only when you call a method like toSet(), reduce() or pass it to a for of loop will each value get pulled through the pipeline, and only once.

This library is essentially

  • RxJS, but fully synchronous
  • lodash, but with first-class support for ES6 collections.

Performance

Benchmark based on the example above:

Methodops/sec
Loop225 ops/sec ±1.87% (73 runs sampled)
iterare211 ops/sec ±2.79% (73 runs sampled)
Array method chain132 ops/sec ±1.84% (73 runs sampled)
Lodash (with lazy evalution)179 ops/sec ±1.67% (77 runs sampled)
RxJS204 ops/sec ±1.69% (75 runs sampled)

Lazy Evaluation

Going a step further, if you only care about a specific number of elements in the end, only these elements will run through the pipeline:

iterate(collection)
  .filter(uri => uri.startsWith('file://'))
  .take(5)

In this example, the filter predicate is called only until 5 elements have been found. The alternative with an array would call it for every element in the collection:

Array.from(collection)
  .filter(uri => uri.startsWith('file://'))
  .slice(0, 5)

Contributing

The source is written in TypeScript.

  • npm run build compiles TS
  • npm run watch compiles on file changes
  • npm test runs tests
  • node lib/benchmarks/____ runs a benchmark

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free