Benchmarks
These numbers compare this library with what you would write without it: native Array, Map and Set, including
the cases where this library is slower.
How the comparison is run
Section titled “How the comparison is run”npm run bench:isolated is built so that no implementation can affect another:
- One implementation per process. Every (workload, implementation) pair runs alone in a fresh Docker container, so one run’s JIT state and garbage cannot affect another.
- Same environment. One image for all: Node.js v24.12.0 and this library’s published build (
dist/). Each container is pinned to one CPU (--cpuset-cpus 1 --cpus 1 --memory 2g --network none). - Same data, same test. Each workload has one seeded dataset and one test loop, written once in
bench/isolated/workloads.ts; implementations plug in through a small adapter (put,get,offer,poll, …). - Same answer. Before timing, every implementation must return the same checksum on that data (for example the same number of LRU cache hits). The run stops if any disagrees.
- Order and repeats. Containers run one at a time in shuffled order, 3 times each; tables show the median.
Docker on macOS runs a Linux VM, so compare the ratios, not the absolute rates. Run on an Apple M1 Pro.
Run it in your browser
Section titled “Run it in your browser”The same tests on your device: the same data and code, each implementation in its own Web Worker. Until you run a test, its bar shows the isolated run’s result.
Results
Section titled “Results”| Test | This library | Native | Result |
|---|---|---|---|
| ArrayList add + get 100k appends, 100k indexed reads; native: Array | 81.8M add/get calls/s | 113.8M/s | 1.39× slower |
| ArrayList sort 100k random numbers, comparator; native: Array | 4.3M elements/s | 4.1M/s | 1.04× faster |
| ArrayDeque as a queue size 1k, 100k offer + poll; native: Array push + shift | 279.8M offer/poll calls/s | 42.7M/s | 6.55× faster |
| LinkedList as a queue size 1k, 100k offer + poll; native: Array push + shift | 324.2M offer/poll calls/s | 34.2M/s | 9.47× faster |
| Stack push + pop (ArrayDeque) 100k pushes, then 100k pops; native: Array push + pop | 110.1M push/pop calls/s | 108.0M/s | 1.02× faster |
| Stack push + pop (Stack) 100k pushes, then 100k pops; native: Array push + pop | 96.0M push/pop calls/s | 108.0M/s | 1.12× slower |
| PriorityQueue churn size 1k, 100k offer + poll; native: sorted Array | 55.5M offer/poll calls/s | 55.2M/s | about the same |
| HashSet add + has 100k integers; native: Set | 66.9M add/has calls/s | 19.8M/s | 3.39× faster |
| LinkedHashSet add + has 100k integers, insertion order; native: Set | 55.9M add/has calls/s | 18.7M/s | 2.99× faster |
| HashMap.get 100k integer keys; native: Map | 155.9M get calls/s | 40.5M/s | 3.85× faster |
| HashMap.put 100k string keys; native: Map | 5.5M put calls/s | 7.3M/s | 1.32× slower |
| HashMap with value keys 10k points with equals()/hashCode(); native: Map with string keys | 7.1M put/get calls/s | 7.2M/s | about the same |
| LinkedHashMap put + iterate 100k entries, insertion order; native: Map | 44.9M puts and visited entries/s | 16.9M/s | 2.65× faster |
| LRU cache capacity 1k, 100k get-or-put; native: Map delete + set | 25.5M get-or-put calls/s | 4.3M/s | 5.99× faster |
| TreeMap floor + ceiling 100k keys, 100k queries; native: sorted Array + binary search | 2.2M floor/ceiling calls/s | 9.1M/s | 4.07× slower |
| Stream filter → map → sum (Stream) 100k numbers; native: Array filter/map/reduce | 689.3M elements/s | 41.9M/s | 16× faster |
| Stream filter → map → sum (IntStream) 100k numbers; native: Array filter/map/reduce | 660.3M elements/s | 41.9M/s | 16× faster |
Why it is faster
Section titled “Why it is faster”- Integer keys skip hashing.
HashMap,HashSetand theLinkedHash*variants store each key in the fastest storage that is still correct for it: integers in0..2^30-1go to a dense array indexed by the key (while it stays at least 25% full), primitives and plain objects go to a nativeMap, and only keys withequals()/hashCode()orDates use a hash-bucket table.LinkedHashMapthreads a doubly linked list through its nodes, so ordered iteration,pollFirstEntryand LRU moves are O(1). ArrayDequeis a power-of-two ring buffer. Wrapping is a bitmask, vacated slots hold a small integer so a deque of numbers stays in V8’s fast numeric arrays, and removing from the middle shifts the shorter side.PriorityQueuesifts a hole instead of swapping (half the writes), compares with a plain<while it has only seen non-NaNnumbers under natural order, and heapifies a source collection in O(n).TreeMapis a red-black tree with parent pointers. Iterators step to the successor without a stack, the maximum is cached (solastKey()is O(1) and ascending inserts skip the descent), and number and string keys are compared inline.- Streams push, and fuse stages. Without short-circuiting stages the source runs one tight loop; short-circuiting
sinks flag cancellation upstream instead of being asked per element; consecutive
filters fuse into one stage, as do consecutivemaps.Arraychains allocate an intermediate array per stage, which streams do not. ArrayListkeeps a packed array with no holes, soget,setandpushcompile to plain array accesses. That is also why itsinitialCapacityis validated but never used to preallocate.
Where it is slower, and what to do
Section titled “Where it is slower, and what to do”| Case | Measured | Why, and what to do |
|---|---|---|
for..of over ArrayList/ArrayDeque |
0.26–0.33× a native array | Each step returns a { value, done } object and checks for concurrent modification. Use forEach (faster than native Array.forEach) or an indexed get loop. On maps, map.forEach((k, v) => …) was 1.5× faster than for (const [k, v] of map). |
string keys in HashMap / LinkedHashMap |
0.75–0.83× / 0.69× a native Map |
Every call goes through the key-kind dispatch, and LinkedHashMap also keeps its list. Sparse integer keys (too spread out for the dense array) take the same path: 0.76×. If all keys are strings and you need neither value equality nor the Map interface, use a native Map. |
ArrayList add + get, Stack push + pop |
about 0.7× and 0.9× a native array | Every get checks the index and every change updates modCount for fail-fast iterators. An ArrayDeque used as a stack matches native push/pop. Presize an ArrayDeque: new ArrayDeque(n) really preallocates and about doubles addLast throughput. new ArrayList(n), new HashMap(n) and new PriorityQueue(n) only validate n. |
TreeMap on read-mostly data |
about 0.25× a sorted array on floor/ceiling |
A sorted array with binary search (or a sorted ArrayList with Collections.binarySearch) is faster when the keys rarely change, and over 10× faster to iterate. Use TreeMap when inserts and removals interleave with queries. |
short streams (findFirst, limit on tiny inputs) |
about 0.4× Array.find or a loop |
A fixed setup cost per stream. For a single find, use Array.find. Prefer mapMulti over flatMap on hot paths: it does not create a stream per element. |
Collectors.toList, partitioningBy |
0.74×, 0.87× native | The generic supplier/accumulator/finisher protocol. Use stream.toList() when you only need a list. |
For numeric pipelines, IntStream/DoubleStream (mapToInt, IntStream.range) are faster than Stream<number>
because of their specialised sum(), average(), typed-array sorted() and number distinct(): 2.3× on
distinct + sorted. Give hash keys a cheap hashCode(), since it runs on every lookup.
Run it yourself
Section titled “Run it yourself”npm run bench:isolated # the comparison above (needs a running Docker daemon)npm run bench:isolated -- --only lru-cache,hashmap-get-int --reps 5npm run bench # in-process suite, every bench/*.bench.ts (several minutes)npm run bench -- HashMap # files whose name contains "HashMap"npm run build && node bench/demo/index.js # HashMap.get vs a native Mapnode bench/demo/index.js strings # the same with string keysbench:isolated writes bench/isolated/results.json; --only replaces just the selected workloads. The in-process
suite (bench/*.bench.ts, tinybench) covers many more cases against native code in one process; it prints ops/s,
margin of error and the ratio to the fastest case per group, then a “Not fastest in” summary. bench/demo
runs the same get test on this library’s HashMap and a native Map, each in its own Node process, and prints calls,
time, calls per second and nanoseconds per call.
For stable numbers, close heavy processes and plug in a laptop (throttling moves results by 10–20%), run a group two or
three times, and treat differences under about 10%, or within the printed ±%, as noise.