awesome-iter

Gives iterables & iterators a facelift by allowing you to manipulate them like an array or stream of values.

npm install @aloreljs/awesome-iter

Table of Contents

• Motivation
• Alternatives
• API
  • AwesomeIter
    • constructor()
    • pipe()
    • consume()

Motivation

Arrays have useful functions, iterables don't. While you could just transform an iterable into an array, that results in multiple iterations:

const someSet: Set<string> = getSomeSet();
const uppercased: Set<string> = new Set(
    [...someSet] // first full iteration
        .filter(str => str !== 'foo') // second full iteration
        .map(str => str.toUpperCase()) // third, partial iteration
); // fourth partial iteration to construct the Set

This library allows you to work with iterables directly:

import {AwesomeIter} from '@aloreljs/awesome-iter';
import {concat, filter, map} from '@aloreljs/awesome-iter/pipes';
import {toSet} from '@aloreljs/awesome-iter/consumers';

const someSet: Set<string> = getSomeSet();
const someMap: Map<number, string> = getSomeMap();
const someArray: string[] = getSomeArray();

// Only 1 iteration over someSet, someMap & someArray
const uppercasedSet: Set<string> = new AwesomeIter(someSet)
    .pipe(
        concat(someMap.values(), someArray),
        filter(str => str !== 'foo'),
        map(str => str.toUpperCase()) // Only gets called `length - numberOfFoos` times
    )
    .collect(toSet()); // Set is populated as values get yielded

Alternatives

• For any async data just use Rxjs - it's awesome & it has more functionality.
• I'm unaware of similar libraries for synchronous iterables & iterators. This one is very lean & tree-shakeable!

API

AwesomeIter

constructor()

Just pass an Iterable or Iterator and AwesomeIter will be able to start managing it.

pipe()

Pipes manipulate the source Iterable or Iterator in some way - filter results, map them to different values etc. Each pipe has documentation & examples written for it in the projects/awesome-iter/pipes directory and is imported from @aloreljs/awesome-iter/pipes, e.g.

import {filter} from '@aloreljs/awesome-iter/pipes';

The current list of pipes is as follows:

• chunk
• concat
• distinct
• filter
• map
• sequentiallyDistinct
• skip
• take
• tap

consume()

Consumers consume the source Iterable or Iterator & produce a single result - these include functions like those in Array.prototype that don't necessarily return an array & functions for collecting the source into some JS collection. Each consumer has documentation & examples written for it in the projects/awesome-iter/consumers directory and is imported from @aloreljs/awesome-iter/consumers, e.g.

import {some} from '@aloreljs/awesome-iter/consumers';

The current list of consumers is as follows:

• count
• find
• first
• includes
• last
• reduce
• some
• split
• toArray
• toMap
• toObject
• toSet