Iter

A bunch of utilities for working with iterables, many inspired by the native array methods.

Iterables are great for doing things you would normally do with arrays, lazily, meaning you only compute what you need. The aim of this module is to provide lazy iterable alternatives to javascript’s native array methods, as well as a few quality-of-life iterable utilities.

This library opts for standalone functions rather than an extended iterable type for the sake of simplicity and being lightweight. If an extension of the iterable type which provides these features as methods is what you are after, see IxJS (for Deno this can be imported via skypack).

Usage

Deno

The module is currently hosted on https://deno.land/x/iter.

import * as iter from "https://deno.land/x/iter/mod.ts";
// or with a version
import * as iter from "https://deno.land/x/iter@v3.1.0/mod.ts";

const naturals = iter.create.increments(1);
const odds = iter.filter(naturals, (n) => n % 2 === 1);

for (const num of iter.take(odds, 5)) {
  console.log(num);
}

npm

You can use this as an npm package too.

$ npm install --save iterable-utilities

import * as iter from "iterable-utilities";

const naturals = iter.create.increments(1);
const odds = iter.filter(naturals, (n) => n % 2 === 1);

for (const num of iter.take(odds, 5)) {
  console.log(num);
}

Functional programming

An alternative module is provided for functional programming styles, with a sensible level of currying. In Deno:

import * as iter from "https://deno.land/x/iter/fp.ts";
// or with a version
import * as iter from "https://deno.land/x/iter@v3.1.0/fp.ts";

const naturals = iter.create.increments(1);
const filterOdds = iter.filter<number>((n) => n % 2 === 1);
const odds = filterOdds(naturals);

for (const num of iter.take(5)(odds)) {
  console.log(num);
}

and from npm:

import * as iter from "iterable-utilities/fp";

const naturals = iter.create.increments(1);
const filterOdds = iter.filter<number>((n) => n % 2 === 1);
const odds = filterOdds(naturals);

for (const num of iter.take(5)(odds)) {
  console.log(num);
}

These curried functions are also available in the main module under iter.curried

// Deno
import { curried } from "https://deno.land/x/iter/fp.ts";
// npm
import { curried } from "iterable-utilities";

Chaining operations (composition)

To chain multiple operations together, partially applied curried iter functions can be composed together. Generic composition functions are notoriously difficult to implement in TypeScript, there are a few modules which provide solutions.

If you can deal with a slightly alien curried syntax, copb allows for type-safe currying of an unlimited number of functions.

import * as iter from "https://deno.land/x/iter/fp.ts";
import { c, p } from "https://deno.land/x/copb/mod.ts";

const pipeline = c(
  p (iter.map<number>(x => x * 100)) // Only needed type annotation, the rest is inferred.
    (iter.map(Math.floor))
    (iter.filter(x => x % 3 === 0))
    (iter.take(30))
    (iter.reduce((str, x) => str + x, ""))
    (console.log)
);

pipeline(iter.create.randomNumbers());
// ~> 661299633996843372696936915845169485496993302427362472690

If that isn’t your thing, compose achieves a similar thing in the familar JavaScript syntax by providing 64 type overloads. This does limit the number of functions which can be composed in one go, but if you reach that point you should probably be breaking your code into smaller functions anyway.

API

Full API documentation can be found here

Array.prototype parity completeness

• concat
• entries (as indexedPairs)
• every
• filter
• find
• findIndex
• includes
• map
• reduce
• some
• forEach
• flat
• flatMap

Currently not being considered

• copyWithin
• fill
• indexOf
• join
• lastIndexOf
• pop
• push
• reduceRight
• reverse
• shift
• slice
• sort
• splice
• toLocaleString
• toString
• unshift

Internal nomenclature

The functions are organised into the following categories. Note that when importing from mod.ts, all are included in the same namespace except for generators, which is exported under create.

• generators create new iterables from non-iterable arguments (or none at all).
• transformers transform one iterable to another.
• combiners transform multiple iterables to a single iterable.
• reducers reduce an iterable into a single, non-iterabe value.
• effectors are used for side effects and do not alter an iterable.