iterutil

Iterator / AsyncIterator utility pack for JavaScript and TypeScript. Each module is designed to work independently, avoiding internal inter-dependencies as much as possible.

Usage

To apply single operation to an iterable, use modules under the root.

import { map } from "@core/iterutil/map";

const iter = map([1, 2, 3], (v) => v * 2);
console.log(Array.from(iter)); // [2, 4, 6]

To apply single asynchronous operation to an (async) iterable, use modules under the async submodule.

import { map } from "@core/iterutil/async/map";

const iter = map([1, 2, 3], (v) => Promise.resolve(v * 2));
console.log(await Array.fromAsync(iter)); // [2, 4, 6]

To apply multiple operations to an iterable, use the modules under the pipe submodule with the @core/pipe package.

import { pipe } from "@core/pipe";
import { cycle } from "@core/iterutil/pipe/cycle";
import { filter } from "@core/iterutil/pipe/filter";
import { map } from "@core/iterutil/pipe/map";
import { take } from "@core/iterutil/pipe/take";

const iter = pipe(
  [1, 2, 3],
  map((v) => v * 2),
  cycle,
  take(10),
  filter((v) => v % 2 === 0),
);
console.log(Array.from(iter)); // [2, 4, 6, 2, 4, 6, 2, 4, 6, 2]

To apply multiple asynchronous operations to an (async) iterable, use the modules under the pipe/async submodule with the @core/pipe package.

import { pipe } from "@core/pipe";
import { cycle } from "@core/iterutil/pipe/async/cycle";
import { filter } from "@core/iterutil/pipe/async/filter";
import { map } from "@core/iterutil/pipe/async/map";
import { take } from "@core/iterutil/pipe/async/take";

const iter = pipe(
  [1, 2, 3],
  map((v) => Promise.resolve(v * 2)),
  cycle,
  take(10),
  filter((v) => Promise.resolve(v % 2 === 0)),
);
console.log(await Array.fromAsync(iter)); // [2, 4, 6, 2, 4, 6, 2, 4, 6, 2]

chain

Chains multiple iterables together.

import { chain } from "@core/iterutil/chain";

const iter = chain([1, 2], ["a", "b"], [true, false]);
console.log(Array.from(iter)); // [1, 2, "a", "b", true, false]

import { chain } from "@core/iterutil/async/chain";

const iter = chain([1, 2], ["a", "b"], [true, false]);
console.log(await Array.fromAsync(iter)); // [1, 2, "a", "b", true, false]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { chain } from "@core/iterutil/pipe/chain";

const iter = pipe(
  [1, 2],
  chain(["a", "b"], [true, false]),
);
console.log(Array.from(iter)); // [1, 2, "a", "b", true, false]

import { pipe } from "@core/pipe";
import { chain } from "@core/iterutil/pipe/async/chain";

const iter = pipe(
  [1, 2],
  chain(["a", "b"], [true, false]),
);
console.log(await Array.fromAsync(iter)); // [1, 2, "a", "b", true, false]

chunked

Chunks an iterable into arrays of a given size.

import { chunked } from "@core/iterutil/chunked";

const iter = chunked([1, 2, 3, 4, 5], 2);
console.log(Array.from(iter)); // [[1, 2], [3, 4], [5]]

import { chunked } from "@core/iterutil/async/chunked";

const iter = chunked([1, 2, 3, 4, 5], 2);
console.log(await Array.fromAsync(iter)); // [[1, 2], [3, 4], [5]]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { chunked } from "@core/iterutil/pipe/chunked";

const iter = pipe(
  [1, 2, 3, 4, 5],
  chunked(2),
);
console.log(Array.from(iter)); // [[1, 2], [3, 4], [5]]

import { pipe } from "@core/pipe";
import { chunked } from "@core/iterutil/pipe/async/chunked";

const iter = pipe(
  [1, 2, 3, 4, 5],
  chunked(2),
);
console.log(await Array.fromAsync(iter)); // [[1, 2], [3, 4], [5]]

compact

Removes all nullish (null or undefined) values from an iterable.

import { compact } from "@core/iterutil/compact";

const iter = compact([1, undefined, 2, null, 3]);
console.log(Array.from(iter)); // [1, 2, 3]

import { compact } from "@core/iterutil/async/compact";

const iter = compact([1, undefined, 2, null, 3]);
console.log(await Array.fromAsync(iter)); // [1, 2, 3]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { compact } from "@core/iterutil/pipe/compact";

const iter = pipe(
  [1, undefined, 2, null, 3],
  compact,
);
console.log(Array.from(iter)); // [1, 2, 3]

import { pipe } from "@core/pipe";
import { compact } from "@core/iterutil/pipe/async/compact";

const iter = pipe(
  [1, undefined, 2, null, 3],
  compact,
);
console.log(await Array.fromAsync(iter)); // [1, 2, 3]

compress

Compresses an iterable by selecting elements using a selector iterable.

import { compress } from "@core/iterutil/compress";

const iter = compress(
  [1, 2, 3, 4, 5],
  [true, false, true, false, true],
);
console.log(Array.from(iter)); // [1, 3, 5]

import { compress } from "@core/iterutil/async/compress";

const iter = compress(
  [1, 2, 3, 4, 5],
  [true, false, true, false, true],
);
console.log(await Array.fromAsync(iter)); // [1, 3, 5]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { compress } from "@core/iterutil/pipe/compress";

const iter = pipe(
  [1, 2, 3, 4, 5],
  compress([true, false, true, false, true]),
);
console.log(Array.from(iter)); // [1, 3, 5]

import { pipe } from "@core/pipe";
import { compress } from "@core/iterutil/pipe/async/compress";

const iter = pipe(
  [1, 2, 3, 4, 5],
  compress([true, false, true, false, true]),
);
console.log(await Array.fromAsync(iter)); // [1, 3, 5]

count

Generates an infinite sequence of numbers starting from start with a step of step.

import { count } from "@core/iterutil/count";
import { take } from "@core/iterutil/take";

const iter = count(1, 2);
console.log(Array.from(take(iter, 5))); // [1, 3, 5, 7, 9]

cycle

Returns an infinite iterable that cycles through the given iterable.

import { cycle } from "@core/iterutil/cycle";
import { take } from "@core/iterutil/take";

const iter = cycle([1, 2, 3]);
console.log(Array.from(take(iter, 5))); // [1, 2, 3, 1, 2]

import { cycle } from "@core/iterutil/async/cycle";
import { take } from "@core/iterutil/async/take";

const iter = cycle([1, 2, 3]);
console.log(await Array.fromAsync(take(iter, 5))); // [1, 2, 3, 1, 2]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { cycle } from "@core/iterutil/pipe/cycle";
import { take } from "@core/iterutil/pipe/take";

const iter = pipe(
  [1, 2, 3],
  cycle,
  take(5),
);
console.log(Array.from(iter)); // [1, 2, 3, 1, 2]

import { pipe } from "@core/pipe";
import { cycle } from "@core/iterutil/pipe/async/cycle";
import { take } from "@core/iterutil/pipe/async/take";

const iter = pipe(
  [1, 2, 3],
  cycle,
  take(5),
);
console.log(await Array.fromAsync(iter)); // [1, 2, 3, 1, 2]

drop

Drops the first limit items from the iterable.

import { drop } from "@core/iterutil/drop";

const iter = drop([1, 2, 3, 4, 5], 2);
console.log(Array.from(iter)); // [3, 4, 5]

import { drop } from "@core/iterutil/async/drop";

const iter = drop([1, 2, 3, 4, 5], 2);
console.log(await Array.fromAsync(iter)); // [3, 4, 5]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { drop } from "@core/iterutil/pipe/drop";

const iter = pipe(
  [1, 2, 3, 4, 5],
  drop(2),
);
console.log(Array.from(iter)); // [3, 4, 5]

import { pipe } from "@core/pipe";
import { drop } from "@core/iterutil/pipe/async/drop";

const iter = pipe(
  [1, 2, 3, 4, 5],
  drop(2),
);
console.log(await Array.fromAsync(iter)); // [3, 4, 5]

dropWhile

Drops elements from the iterable while the predicate returns true.

import { dropWhile } from "@core/iterutil/drop-while";

const iter = dropWhile(
  [1, 2, 3, 4, 5],
  (v) => v < 3,
);
console.log(Array.from(iter)); // [3, 4, 5]

import { dropWhile } from "@core/iterutil/async/drop-while";

const iter = dropWhile(
  [1, 2, 3, 4, 5],
  (v) => v < 3,
);
console.log(await Array.fromAsync(iter)); // [3, 4, 5]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { dropWhile } from "@core/iterutil/pipe/drop-while";

const iter = pipe(
  [1, 2, 3, 4, 5],
  dropWhile((v) => v < 3),
);
console.log(Array.from(iter)); // [3, 4, 5]

import { pipe } from "@core/pipe";
import { dropWhile } from "@core/iterutil/pipe/async/drop-while";

const iter = pipe(
  [1, 2, 3, 4, 5],
  dropWhile((v) => v < 3),
);
console.log(await Array.fromAsync(iter)); // [3, 4, 5]

enumerate

Enumerates an iterable.

import { enumerate } from "@core/iterutil/enumerate";

const iter = enumerate(["a", "b", "c"]);
console.log(Array.from(iter)); // [[0, "a"], [1, "b"], [2, "c"]]

import { enumerate } from "@core/iterutil/async/enumerate";

const iter = enumerate(["a", "b", "c"]);
console.log(await Array.fromAsync(iter)); // [[0, "a"], [1, "b"], [2, "c"]]

Use pipe and pipe/async modules for @core/pipe package like.

import { pipe } from "@core/pipe";
import { enumerate } from "@core/iterutil/pipe/enumerate";

const iter = pipe(["a", "b", "c"], enumerate);
console.log(Array.from(iter)); // [[0, "a"], [1, "b"], [2, "c"]]

import { pipe } from "@core/pipe";
import { enumerate } fro