Iterable-utilities NPM

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@$MODULE_VERSION/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@$MODULE_VERSION/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.