shelving/util/iteratemodule

General-purpose utilities for working with any Iterable<T> — arrays, sets, generators, and custom iterables alike. These complement the array-specific helpers by operating lazily on any sequence without forcing materialisation.

Things to know:

  • Most helpers are generators and return Iterable<T>, not arrays. Wrap with Array.from() when you need an array.
  • flattenItems() recurses into any depth of nested iterables, not just one level.
  • getRange() yields in descending order automatically when end < start.
  • reduceItems() returns undefined if the iterable is empty and no initial value is supplied.

Usage

Checking and counting

ts
import { isIterable, hasItems, countItems } from "shelving/util";

isIterable([1, 2, 3]);      // true
isIterable(new Set());      // true
isIterable("hello");        // false (strings are not iterable here)

hasItems([]);               // false
hasItems(new Set([1]));     // true

countItems(new Set([1, 2, 3])); // 3

Slicing, picking, and chunking

ts
import { limitItems, pickItems, omitItems, getChunks } from "shelving/util";

Array.from(limitItems([1, 2, 3, 4, 5], 3));     // [1, 2, 3]
Array.from(pickItems([1, 2, 3, 4], 2, 4));       // [2, 4]
Array.from(omitItems([1, 2, 3, 4], 2, 4));       // [1, 3]
Array.from(getChunks([1, 2, 3, 4, 5], 2));       // [[1, 2], [3, 4], [5]]

Ranges and merging

ts
import { getRange, mergeItems, interleaveItems, flattenItems } from "shelving/util";

Array.from(getRange(1, 5));   // [1, 2, 3, 4, 5]
Array.from(getRange(5, 1));   // [5, 4, 3, 2, 1]

Array.from(mergeItems([1, 2], [3, 4])); // [1, 2, 3, 4]

Array.from(interleaveItems(["a", "b", "c"], ", ")); // ["a", ", ", "b", ", ", "c"]

Array.from(flattenItems([1, [2, [3, 4]], 5])); // [1, 2, 3, 4, 5]

Reducing

ts
import { reduceItems } from "shelving/util";

reduceItems([1, 2, 3, 4], (acc, n) => acc + n, 0); // 10

Functions

Go

isIterable()function

Is an unknown value an iterable?

isIterable(value: unknown): value is Iterable<unknown>
Go

flattenItems()function

Flatten one or more (possibly nested) iterables into a flat sequence of items.

flattenItems(items: DeepIterable<T>): Iterable<T>
Go

hasItems()function

Does an iterable have one or more items.

hasItems(items: Iterable<unknown>): boolean
Go

countItems()function

Count the number of items in an iterable.

countItems(items: Iterable<unknown>): number
Go

getRange()function

Yield a range of numbers from start to end

getRange(start: number, end: number): Iterable<number>
Go

limitItems()function

Apply a limit to an iterable set of items.

limitItems(items: Iterable<T>, limit: number): Iterable<T>
Go

pickItems()function

Pick items from an iterable set of items.

pickItems(items: Iterable<T>, ...pick: T[]): Iterable<T>
Go

omitItems()function

Omit items from an iterable set of items.

omitItems(items: Iterable<T>, ...omit: T[]): Iterable<T>
Go

reduceItems()function

Reduce an iterable set of items using a reducer function.

reduceItems(items: Iterable<T>, reducer: (previous: T, item: T) => T, initial: T): T
reduceItems(items: Iterable<T>, reducer: (previous: T | undefined, item: T) => T, initial?: T): T | undefined
reduceItems(items: Iterable<I>, reducer: (previous: O, item: I) => O, initial: O): O
reduceItems(items: Iterable<I>, reducer: (previous: O | undefined, item: I) => O, initial?: O): O | undefined
Go

getChunks()function

Yield chunks of a given size.

getChunks(items: Iterable<T>, size: number): Iterable<readonly T[]>
Go

mergeItems()function

Merge two or more iterables into a single iterable set.

mergeItems(...inputs: [Iterable<T>, Iterable<T>, ...Iterable<T>[]]): Iterable<T>
Go

interleaveItems()function

Interleave items with a separator, i.e. [item1, separator, item2, separator, item3]

interleaveItems(items: Iterable<T>, separator: T): Iterable<T>
interleaveItems(items: Iterable<A>, separator: B): Iterable<A | B>

Types

Go

DeepIterabletype

An iterable containing items or nested iterables of items.

T | Iterable<DeepIterable<T>>