Skip to content
Buy me a coffee

@ylcnfrht/collections

Zero dependencies · Node, Deno, Bun, browsers

Lists, sets, maps and streams.
The way they should work.

Inspired by the Java Collections Framework: ArrayList, HashMap, TreeMap, PriorityQueue, Stream and more, typed for TypeScript. Value equality, sorted navigation, live views and fail-fast iterators.

example.ts
import { HashSet, List, TreeMap } from '@ylcnfrht/collections';
// elements compare by value: two equal lists are one element
const seen = new HashSet<List<number>>();
seen.add(List.of(1, 2)); // → true
seen.add(List.of(1, 2)); // → false, already there
// sorted by key, with navigation and range views
const plans = new TreeMap<number, string>();
plans.put(10, 'basic');
plans.put(25, 'pro');
plans.put(50, 'team');
plans.floorKey(30); // → 25
plans.headMap(25); // → {10=basic}
0dependencies
1.69Moperations checked vs the JDK
10,000+tests
~99%line coverage
ESM + CJStyped, tree-shakeable

What it does

Collections with the guarantees arrays and Map don't give you.

Equality

Compare by value, not by reference.

HashMap and HashSet use equals() and hashCode(), so a list, a date or your own class works as a key. Plain strings and numbers take a fast path.

Read more
const seen = new HashSet<List<number>>();
seen.add(List.of(1, 2)); // → true
seen.add(List.of(1, 2)); // → false
seen.size(); // → 1
Sorted

Sorted maps that navigate.

TreeMap and TreeSet are red-black trees with floor, ceiling, range views and descending order.

Read more
prices.floorKey(30); // → 25
prices.ceilingKey(30); // → 50
prices.headMap(25); // → {10=basic}
Views

Live views, no copies.

subList, keySet, headMap and reversed() read and write through to the collection behind them.

Read more
const list = ArrayList.of(1, 2, 3, 4, 5);
list.subList(1, 4).clear();
list.toString(); // → [1, 5]
Iteration

Fail fast, never skip.

Changing a collection while iterating it throws at once, instead of silently skipping or repeating elements.

Read more
for (const x of list) list.add(x);
// → ConcurrentModificationException
Streams

Lazy streams that stop early.

Stream, IntStream, Collectors and Gatherers run each element through the whole pipeline and stop as soon as the result is known.

Read more
IntStream.iterate(1, (n) => n * 2)
.filter((n) => n > 100)
.findFirst(); // → OptionalInt[128]
Verified

Checked against the JDK, operation by operation.

200,000 random operation scripts run on a real JDK and on this library, and every return value, exception and resulting state is compared.

Read more
Scripts 200,000
Operations compared 1,692,438
Comparable API covered 1602 / 1602 (100%)

The toolbox

Every collection you reach for, one API.

Lists

  • ArrayListResizable array, O(1) get
  • LinkedListList and deque in one
  • List.of · List.copyOfImmutable lists
  • Vector · StackLegacy, kept for parity

Queues

  • ArrayDequeRing buffer, both ends O(1)
  • PriorityQueueBinary heap, any comparator
  • Dequepush, pop, peek at either end
  • Collections.asLifoQueueA stack view of a deque

Sets & maps

  • HashSet · HashMapValue equality
  • LinkedHashSet · LinkedHashMapInsertion or access order, LRU
  • TreeSet · TreeMapSorted, navigable
  • IdentityHashMapCompare by reference

Streams & utilities

  • Stream · IntStreamLazy, short-circuiting
  • Collectors · GatherersgroupingBy, windows, folds
  • OptionalA value that may be absent
  • Collections · ComparatorSort, search, compose

In code

The classes you know, a few lines each.

import { ArrayList } from '@ylcnfrht/collections';
const fruits = new ArrayList<string>();
fruits.add('pear');
fruits.add('apple');
fruits.add('fig');
fruits.sort(null); // natural order
fruits.get(0); // → 'apple'
fruits.indexOf('fig'); // → 1
fruits.subList(0, 2); // → [apple, fig]

Get started

Install it. Import a class. Done.

Start with an ArrayList or a HashMap. Reach for TreeMap, PriorityQueue and streams when the problem asks for them.