collectMap
Collects the values from an iterable into a record.
The iterable to collect from
A function that takes an element from the iterable and returns a key
An optional function that takes an element from the iterable and returns a value. If not provided, the original value is used
A record where the keys are the result of calling getKey on each element, and the values are the result of calling map on each element
Example
import { collectMap } from "@temelj/iterator";
const numbers = [1, 2, 3];
const result = collectMap(numbers, (n) => n * 2);
console.log(result); // { 2: 1, 4: 2, 6: 3 }
groupBy
Groups elements from an iterable using a key selector function.
A function that derives a key from an element
A Map where keys are the result of calling getKey on each element, and values are arrays of elements with that key
Example
import { groupBy } from "@temelj/iterator";
// Group numbers by even/odd
const numbers = [1, 2, 3, 4, 5, 6];
const result = groupBy(numbers, (x) => x % 2 === 0 ? "even" : "odd");
console.log(result.get("even")); // [2, 4, 6]
console.log(result.get("odd")); // [1, 3, 5]
// Group objects by property
const users = [
{ name: "Alice", group: "A" },
{ name: "Bob", group: "B" },
{ name: "Charlie", group: "A" },
];
const byGroup = groupBy(users, (u) => u.group);
console.log(byGroup.get("A"));
// [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }]
chunk
Splits an iterable into arrays of a specific size.
The size of each chunk (must be greater than 0)
Example
import { chunk } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5];
console.log(chunk(numbers, 2)); // [[1, 2], [3, 4], [5]]
const letters = ["a", "b", "c", "d"];
console.log(chunk(letters, 2)); // [["a", "b"], ["c", "d"]]
window
Yields a sliding window over the iterable.
The size of each window (must be greater than 0)
Example
import { window } from "@temelj/iterator";
const numbers = [1, 2, 3, 4];
console.log(window(numbers, 2));
// [[1, 2], [2, 3], [3, 4]]
console.log(window(numbers, 3));
// [[1, 2, 3], [2, 3, 4]]
zip
Combines two iterables into tuples until one is exhausted.
Example
import { zip } from "@temelj/iterator";
const numbers = [1, 2, 3];
const letters = ["a", "b", "c"];
console.log(zip(numbers, letters));
// [[1, "a"], [2, "b"], [3, "c"]]
// Stops when the shorter iterable is exhausted
console.log(zip([1, 2], ["a", "b", "c"]));
// [[1, "a"], [2, "b"]]
flatten
Flattens nested iterables by one level.
iterable
Iterable<Iterable<T> | T>
required
The iterable to flatten
An array of flattened elements
Example
import { flatten } from "@temelj/iterator";
const nested = [[1, 2], [3, 4], [5]];
console.log(flatten(nested)); // [1, 2, 3, 4, 5]
const mixed = [[1, 2], [], [3]];
console.log(flatten(mixed)); // [1, 2, 3]
unique
Returns a sequence of unique items from an iterable.
The iterable to filter for unique items
An optional function that returns a value to use for uniqueness comparison
Example
import { unique } from "@temelj/iterator";
// With primitive values
console.log(unique([1, 2, 2, 3, 3, 3])); // [1, 2, 3]
console.log(unique(["a", "b", "a", "c"])); // ["a", "b", "c"]
// With custom identity function
const users = [
{ id: 1, name: "Alice" },
{ id: 2, name: "Bob" },
{ id: 1, name: "Alice Duplicate" },
];
console.log(unique(users, (u) => u.id));
// [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
union
Combines two iterables into a set of unique items from both.
An array of unique items from both iterables
Example
import { union } from "@temelj/iterator";
console.log(union([1, 2, 3], [2, 3, 4])); // [1, 2, 3, 4]
console.log(union([1, 2], [3, 4])); // [1, 2, 3, 4]
intersection
Returns items present in both iterables.
An array of items present in both iterables
Example
import { intersection } from "@temelj/iterator";
console.log(intersection([1, 2, 3], [2, 3, 4])); // [2, 3]
console.log(intersection([1, 2, 3], [4, 5, 6])); // []
difference
Returns items in the first iterable that are not in the second.
An array of items in a but not in b
Example
import { difference } from "@temelj/iterator";
console.log(difference([1, 2, 3], [2, 3, 4])); // [1]
console.log(difference([1, 2, 3], [4, 5, 6])); // [1, 2, 3]
filterMap
Filters and maps an iterable in a single operation.
The iterable to filter and map
filter
(e: T, i: number) => U | undefined
required
A function that takes an element and its index, and returns the mapped element or undefined if the element should be filtered out
A new array containing the mapped elements that passed the filter
Example
import { filterMap } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5];
// Keep only even numbers and double them
const result = filterMap(numbers, (n) => {
if (n % 2 === 0) {
return n * 2;
}
return undefined;
});
console.log(result); // [4, 8]
// Parse strings, filtering out invalid ones
const strings = ["1", "not a number", "42"];
const parsed = filterMap(strings, (s) => {
const num = parseInt(s);
return isNaN(num) ? undefined : num;
});
console.log(parsed); // [1, 42]
partition
Splits an iterable into two arrays based on a predicate.
The iterable to partition
predicate
(item: T) => boolean
required
A function that returns true for elements that should go in the first array
A tuple of two arrays: [truthyElements, falsyElements]
Example
import { partition } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5, 6];
const [even, odd] = partition(numbers, (n) => n % 2 === 0);
console.log(even); // [2, 4, 6]
console.log(odd); // [1, 3, 5]
// Partition objects
const users = [
{ name: "Alice", active: true },
{ name: "Bob", active: false },
{ name: "Charlie", active: true },
];
const [active, inactive] = partition(users, (u) => u.active);
console.log(active); // [{ name: "Alice", ... }, { name: "Charlie", ... }]
console.log(inactive); // [{ name: "Bob", ... }]
take
Creates an iterator that yields the first n elements of the given iterable.
The iterable to take from
The number of elements to take
An array containing the first n elements
Example
import { take } from "@temelj/iterator";
console.log(take([1, 2, 3, 4, 5], 3)); // [1, 2, 3]
console.log(take([1, 2, 3], 5)); // [1, 2, 3]
console.log(take([1, 2, 3], 0)); // []
skip
Creates an iterator that skips the first n elements of the given iterable.
The iterable to skip from
The number of elements to skip
An array containing the remaining elements after skipping n
Example
import { skip } from "@temelj/iterator";
console.log(skip([1, 2, 3, 4, 5], 2)); // [3, 4, 5]
console.log(skip([1, 2, 3], 5)); // []
console.log(skip([1, 2, 3], 0)); // [1, 2, 3]
takeWhile
Creates an iterator that yields elements while the predicate returns true.
The iterable to take from
predicate
(item: T) => boolean
required
A function that returns true for elements to include
An array containing elements while the predicate was true
Example
import { takeWhile } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5];
console.log(takeWhile(numbers, (x) => x < 4)); // [1, 2, 3]
console.log(takeWhile(numbers, (x) => x > 10)); // []
skipWhile
Creates an iterator that skips elements while the predicate returns true.
The iterable to skip from
predicate
(item: T) => boolean
required
A function that returns true for elements to skip
An array containing elements after the predicate returned false
Example
import { skipWhile } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5];
console.log(skipWhile(numbers, (x) => x < 4)); // [4, 5]
console.log(skipWhile(numbers, (x) => x > 10)); // [1, 2, 3, 4, 5]
find
Finds the first element matching a predicate.
predicate
(item: T) => boolean
required
A function that returns true for the desired element
The first matching element, or undefined if not found
Example
import { find } from "@temelj/iterator";
const numbers = [1, 2, 3, 4, 5];
console.log(find(numbers, (x) => x > 3)); // 4
console.log(find(numbers, (x) => x > 10)); // undefined
any
Checks if any element satisfies the predicate.
predicate
(item: T) => boolean
required
A function that returns true for matching elements
True if any element satisfies the predicate, false otherwise
Example
import { any } from "@temelj/iterator";
console.log(any([1, 2, 3], (x) => x > 2)); // true
console.log(any([1, 2, 3], (x) => x > 10)); // false
all
Checks if all elements satisfy the predicate.
predicate
(item: T) => boolean
required
A function that returns true for matching elements
True if all elements satisfy the predicate, false otherwise
Example
import { all } from "@temelj/iterator";
console.log(all([1, 2, 3], (x) => x > 0)); // true
console.log(all([1, 2, 3], (x) => x > 2)); // false
console.log(all([], (x) => x > 0)); // true (vacuous truth)
count
Counts the number of elements in an iterable, or counts elements matching a predicate.
An optional predicate to filter elements
Example
import { count } from "@temelj/iterator";
// Count all elements
console.log(count([1, 2, 3, 4, 5])); // 5
// Count matching elements
console.log(count([1, 2, 3, 4, 5], (x) => x % 2 === 0)); // 2
console.log(count([1, 2, 3], (x) => x > 10)); // 0
minBy
Finds the minimum element using a selector function.
selector
(item: T) => number
required
A function that returns a comparable value for each element
The minimum element, or undefined if the iterable is empty
Example
import { minBy } from "@temelj/iterator";
// Find minimum number
console.log(minBy([3, 1, 4, 1, 5], (x) => x)); // 1
// Find user with minimum age
const users = [
{ name: "Alice", age: 30 },
{ name: "Bob", age: 25 },
{ name: "Charlie", age: 35 },
];
console.log(minBy(users, (u) => u.age));
// { name: "Bob", age: 25 }
maxBy
Finds the maximum element using a selector function.
selector
(item: T) => number
required
A function that returns a comparable value for each element
The maximum element, or undefined if the iterable is empty
Example
import { maxBy } from "@temelj/iterator";
// Find maximum number
console.log(maxBy([3, 1, 4, 1, 5], (x) => x)); // 5
// Find user with maximum age
const users = [
{ name: "Alice", age: 30 },
{ name: "Bob", age: 25 },
{ name: "Charlie", age: 35 },
];
console.log(maxBy(users, (u) => u.age));
// { name: "Charlie", age: 35 }