kollectionjs

Lazy, chainable collection utilities for TypeScript, inspired by Kotlin's sequence API.

Sequence<T> is a native subclass of Iterator<T>. Operations are lazy — nothing runs until a terminal call like toArray() or forEach().

Github repo: https://github.com/geowarin/kollectionjs

Installation

pnpm add kollectionjs

Example usage

const sequence = sequenceOf(1, 2, 3);
let result = sequence
  .map(it => it * 2)
  .filter(it => it % 3 == 0)
  .toArray();

expect(result).toEqual([6]);

const result = entriesOf({ name: "yoda" })
  .mapKeys(k => k.toUpperCase())
  .mapValues(v => v.toUpperCase())
  .toObject();

API Reference

Full API documentation is available here.

Factory functions

	Description
asSequence	Wraps any Iterable in a Sequence
concat	Creates a Sequence that lazily concatenates all given iterables in order
emptySequence	Creates an empty Sequence
entriesOf	Creates a Sequence of [key, value] pairs from a plain object, equivalent to `asSequence(Object
generate	Creates an infinite (or finite) Sequence by repeatedly applying next to a seed value
range	Creates a Sequence of numbers from start (inclusive) to endExclusive (exclusive), advancing by step
sequenceOf	Creates a Sequence from the given arguments

Sequence<T> methods

	Description
associate	Returns a Map built by applying transform to each element and using the resulting [key, value] pair
associateBy	Returns a Map keyed by the result of keySelector (or a property name)
associateWith	Returns a Map where each element is the key and valueSelector provides the value
average	Returns the arithmetic mean of a numeric sequence
chunk	Splits the sequence into chunks of at most chunkSize elements
contains	Returns true if the sequence contains the given element (using ===)
count	Returns the number of elements that satisfy the predicate
distinct	Returns a sequence containing only distinct elements (first occurrence wins)
distinctBy	Returns a sequence containing only elements with distinct keys as computed by selector
drop	Returns a sequence that skips the first num elements
dropWhile	Returns a sequence that skips elements from the start while the predicate holds
elementAt	Returns the element at the given zero-based index, or undefined if the index is out of bounds
elementAtOrElse	Returns the element at the given zero-based index, or the result of defaultValue if the index is out of bounds
every	Determines whether all the members of this iterator satisfy the specified test
filter	Returns a sequence containing only the elements that satisfy the predicate
filterKeys	Returns a sequence containing only the [key, value] pairs whose key satisfies the predicate
filterNot	Returns a sequence containing only the elements that do not satisfy the predicate
filterNotNull	Returns a sequence with all null and undefined elements removed
filterValues	Returns a sequence containing only the [key, value] pairs whose value satisfies the predicate
find	Returns the first element matching the predicate, or undefined if none match
first	Returns the first element matching the predicate, or undefined if none match
flatMap	Maps each element to an iterable and flattens the results into a single sequence
flatten	Flattens a sequence of iterables into a single sequence
fold	Accumulates a value by applying operation left-to-right, starting from initial
forEach	Performs the specified action for each element in the iterator
groupBy	Groups elements into a Map by the key returned by keySelector
indexOf	Returns the zero-based index of the first occurrence of element (using ===), or -1 if it is not found
indexOfFirst	Returns the zero-based index of the first element matching the predicate, or -1 if none match
indexOfLast	Returns the zero-based index of the last element matching the predicate, or -1 if none match
isEmpty	Returns true if the sequence contains no elements
isNotEmpty	Returns true if the sequence contains at least one element
joinToString	Joins all elements into a single string
last	Returns the last element matching the predicate, or undefined if none match
map	Returns a sequence where each element is transformed by transform
mapKeys	Returns a sequence of [key, value] pairs where each key is transformed by transform
mapNotNull	Returns a sequence of transformed elements, skipping any null or undefined results
mapValues	Returns a sequence of [key, value] pairs where each value is transformed by transform
max	Returns the maximum element using the natural > ordering, or undefined if the sequence is empty
maxBy	Returns the element for which selector returns the largest value, or undefined if the sequence is empty
maxWith	Returns the maximum element according to the given compare function, or undefined if the sequence is empty
min	Returns the minimum element using the natural < ordering, or undefined if the sequence is empty
minBy	Returns the element for which selector returns the smallest value, or undefined if the sequence is empty
minus	Returns a sequence with the given element(s) excluded
minWith	Returns the minimum element according to the given compare function, or undefined if the sequence is empty
none	Returns true if no element satisfies the predicate
onEach	Performs the given action on each element and returns the same sequence unchanged
partition	Splits the sequence into two arrays: the first contains elements that satisfy the predicate, the second contains the rest
plus	Returns a sequence that contains all elements of this sequence followed by the given element or all elements of the given iterable
reduce	Calls the specified callback function for all the elements in this iterator
reverse	Returns a new sequence with elements in reverse order
scan	Returns a sequence of running accumulator values, starting with initial
single	Returns the single element matching the predicate, or undefined if there is no match or more than one match
some	Returns true if any element satisfies the predicate
sorted	Returns a new sequence with elements sorted in ascending order using natural ordering
sortedBy	Returns a new sequence sorted in ascending order by the key returned by selector
sortedDescending	Returns a new sequence with elements sorted in descending order using natural ordering
sortedDescendingBy	Returns a new sequence sorted in descending order by the key returned by selector
sortedWith	Returns a new sequence sorted using the given comparator
sum	Returns the sum of all elements in a numeric sequence
sumBy	Returns the sum of the values returned by selector for each element
take	Returns a sequence containing the first num elements
takeWhile	Returns a sequence of elements taken from the start while the predicate holds
toArray	Creates a new array from the values yielded by this iterator
toMap	Collects a sequence of [key, value] pairs into a Map
toObject	Collects a sequence of [key, value] pairs into a plain object
toSet	Collects all elements into a Set
unzip	Unzips a sequence of [A, B] pairs into a tuple of two arrays [A[], B[]]
windowed	Returns a sequence of sliding windows of the given size
withIndex	Returns a sequence of { index, value } pairs, where index is the zero-based position of each element
zip	Returns a sequence of pairs built by combining the elements of this sequence with elements from other
zipWithNext	Returns a sequence of pairs of each consecutive element with the next one
from	Creates a native iterator from an iterator or iterable object

Development

pnpm build       # compile to dist/
pnpm test        # run tests
pnpm typecheck   # TypeScript type check
pnpm dev         # watch mode

License

MIT