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)Sequenceby repeatedly applyingnextto a seed value | |range | Creates aSequenceof numbers fromstart(inclusive) toendExclusive(exclusive), advancing bystep| |sequenceOf | Creates aSequence` 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