Introduction
@ylcnfrht/collections is a collections framework for TypeScript and JavaScript, ported from the Java Collections
Framework and Stream API. It provides lists, queues, deques, sets and maps behind one set of interfaces, lazy streams
with collectors and gatherers, Optional, and the Collections utility class. It has zero runtime dependencies.
import { ArrayList, TreeMap, Collectors, List } from '@ylcnfrht/collections';
const words = ArrayList.of('pear', 'fig', 'apple', 'kiwi');const byLength = words.stream().collect( Collectors.groupingBy((w) => w.length, () => new TreeMap<number, List<string>>(), Collectors.toList()),);console.log(byLength.toString()); // → {3=[fig], 4=[pear, kiwi], 5=[apple]}Why this library
Section titled “Why this library”JavaScript’s Map and Set compare object keys by reference, have no sorted variants, no navigation (floor,
ceiling, range views), no priority queue or deque, and do not fail when modified during iteration. This library
fills those gaps with one set of interfaces that every implementation honours:
- Value equality through
equals()andhashCode(), so a list or your own class works as a map key. - Sorted, navigable collections:
TreeMapandTreeSetwithfloor,ceiling, range views and descending order. - Live views such as
subList,keySet,headMapandreversed(). - Fail-fast iterators that throw on concurrent modification.
- Lazy, short-circuiting streams:
Stream,CollectorsandGatherers.
It also follows JavaScript conventions: every collection is iterable, maps iterate as [key, value] pairs, and
comparators are plain functions. Behaviour is verified against a real JDK on over 1.6 million compared operations
(see Compatibility).
The interface hierarchy
Section titled “The interface hierarchy”Declare variables and parameters with the interfaces, and choose a class at construction time.
Collection├── SequencedCollection│ ├── List ............... ArrayList, LinkedList, Vector, Stack│ ├── Deque .............. ArrayDeque, LinkedList (Deque also extends Queue)│ └── SequencedSet ....... LinkedHashSet (SequencedSet also extends Set)│ └── SortedSet│ └── NavigableSet ... TreeSet├── Queue .................. PriorityQueue└── Set .................... HashSet
Map ........................ HashMap, IdentityHashMap└── SequencedMap ........... LinkedHashMap └── SortedMap └── NavigableMap ... TreeMapA class can be used through any interface it implements:
import { LinkedList, List, Deque, SequencedCollection } from '@ylcnfrht/collections';
const ll = new LinkedList<number>();const asList: List<number> = ll;const asDeque: Deque<number> = ll;const seq: SequencedCollection<number> = ll;asDeque.push(2);asList.add(3);console.log(seq.getFirst(), seq.getLast(), ll.toString()); // → 2 3 [2, 3]| Group | Types |
|---|---|
| Immutable collections | List.of/copyOf (a List), Set.of/copyOf (a Set), Map.of/copyOf/ofEntries (a Map) |
| Skeletal implementations | AbstractCollection, AbstractList, AbstractSequentialList, AbstractQueue, AbstractSet, AbstractMap (see Custom collections) |
| Iteration | Iterator, ListIterator, Enumeration, Spliterator; every collection is also a JS Iterable |
| Streams | Stream, IntStream, LongStream, DoubleStream (all BaseStream), Collector, Gatherer, Optional* |