iterare

What is iterare?

The iterare npm package provides a set of utilities for working with iterables in JavaScript. It allows you to create, transform, and consume iterables in a functional programming style.

What are iterare's main functionalities?

Creating Iterables

You can create an iterable from an array or any other iterable object using the `iterate` function.

const { iterate } = require('iterare');

const iterable = iterate([1, 2, 3, 4]);
console.log([...iterable]); // Output: [1, 2, 3, 4]

Transforming Iterables

You can transform iterables using methods like `map` and `filter` to apply functions to each element or filter elements based on a condition.

const { iterate } = require('iterare');

const iterable = iterate([1, 2, 3, 4])
  .map(x => x * 2)
  .filter(x => x > 4);
console.log([...iterable]); // Output: [6, 8]

Consuming Iterables

You can consume iterables using methods like `reduce` to aggregate values or perform other operations that consume the iterable.

const { iterate } = require('iterare');

const iterable = iterate([1, 2, 3, 4]);
const sum = iterable.reduce((acc, val) => acc + val, 0);
console.log(sum); // Output: 10

Other packages similar to iterare

lodash

Lodash is a popular utility library that provides a wide range of functions for working with arrays, objects, and other data types. It includes methods for creating, transforming, and consuming collections, similar to iterare, but with a broader scope and more features.

ramda

Ramda is a functional programming library for JavaScript that emphasizes immutability and side-effect-free functions. It provides utilities for working with lists and other data structures in a functional style, similar to iterare, but with a focus on functional programming principles.

rxjs

RxJS is a library for reactive programming using Observables, which can be thought of as a more powerful and flexible form of iterables. It provides a wide range of operators for transforming and consuming data streams, similar to iterare, but with a focus on reactive programming.

README

iterare

lat. to repeat, to iterate

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

Benchmarks based on the examples above:

map + filter

Simulate iterating over a very lage Set of strings and applying a filter and a map on it.

Method	ops/sec
Loop	466 ops/sec ±1.31% (84 runs sampled)
iterare	397 ops/sec ±2.01% (81 runs sampled)
RxJS	339 ops/sec ±0.77% (83 runs sampled)
Array method chain	257 ops/sec ±1.73% (79 runs sampled)
Lodash	268 ops/sec ±0.84% (81 runs sampled)
IxJS (ES6)	216 ops/sec ±0.81% (81 runs sampled)
IxJS (ES5)	141 ops/sec ±0.87% (77 runs sampled)

filter + take

Simulate iterating over a very lage Set of strings and applying a filter on it, then taking only the first 1000 elements. A smart implementations should only apply the filter predicate to the first 5 elements.

Method	ops/sec
Loop	3,059,466 ops/sec ±0.75% (88 runs sampled)
iterare	963,257 ops/sec ±0.68% (89 runs sampled)
IxJS (ES6)	424,488 ops/sec ±0.63% (89 runs sampled)
RxJS	168,853 ops/sec ±2.58% (86 runs sampled)
IxJS (ES5)	107,961 ops/sec ±1.88% (78 runs sampled)
Lodash	41.71 ops/sec ±1.15% (54 runs sampled)
Array method chain	24.74 ops/sec ±3.69% (45 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