hashmap

A small HashMap class for JavaScript — any key type, stable API since 2012, rewritten for 3.0.

Works in Node.js (14+) and the browser. ESM, CommonJS, TypeScript types, and an IIFE build included.

npm install hashmap

import HashMap from 'hashmap'
// or
const HashMap = require('hashmap')

---

Why this exists

Native Map didn't exist when this library was created. It does now — and for most new code, Map is the right default.

hashmap is still worth reaching for when you need more than Map gives you:

	hashmap	Map	WeakMap
Any key type (null, numbers, strings, objects, …)	yes	yes	objects only
Object keys by identity	yes	yes	yes
Iterate all entries / .size	yes	yes	no
Value-based equality for Date, RegExp, arrays	yes	no	no
Reverse lookup (.search(value))	yes	no	no
Method chaining on mutators	yes	partial	no

Use hashmap when:

• You need custom key equality — two Date objects with the same timestamp, two /foo/ regexes, arrays compared element-wise.
• You need .search() — find the key for a value.
• You're maintaining legacy code that already depends on this API (plugin systems, protobuf registries, object-key pools, etc.).
• You want a stable, zero-dependency map that behaves the same in Node and the browser.

Use native Map when: string/number/symbol keys with === equality is enough. That's most apps.

Use WeakMap when: keys are objects and you want them garbage-collected when nothing else references them. You can't iterate a WeakMap.

---

Quick start

const map = new HashMap()

map.set('1', 'string one')
map.set(1, 'number one')
map.get('1') // 'string one'
map.get(1)   // 'number one'

const a = {}
const b = {}
map.set(a, 'first')
map.set(b, 'second')
map.get(a) // 'first' — object identity, not stringification

Method chaining

new HashMap()
  .set(1, 'one')
  .set(2, 'two')
  .forEach((value, key) => console.log(key, value))

Iteration

map.forEach((value, key) => { /* … */ })

for (const { key, value } of map) {
  console.log(key, value)
}

Reverse lookup

map.set('id', 42)
map.search(42) // 'id'

---

API

Constructor

• new HashMap() — empty map
• new HashMap(other) — copy from another HashMap
• new HashMap([['k1', 'v1'], ['k2', 'v2']]) — from pairs array
• new HashMap(k1, v1, k2, v2, …) — from arguments

Methods

Method	Description
get(key)	Value for key, or undefined
set(key, value)	Store a pair (chainable)
has(key)	Whether key exists
delete(key)	Remove by key (chainable)
search(value)	Key for value, or null
clear()	Remove all entries (chainable)
forEach(fn, ctx?)	Iterate (value, key) (chainable)
keys() / values() / entries()	Arrays of keys, values, or [key, value] pairs
clone()	Shallow copy as a new HashMap
copy(other)	Copy entries from other into this map (chainable)
multi(k1, v1, …)	Set several pairs at once (chainable)
size	Number of entries

Deprecated aliases kept for compatibility: remove() → delete(), count() → size, type().

TypeScript

Types ship with the package. Generics work as expected:

import HashMap from 'hashmap'

const cache = new HashMap<string, number>()
cache.set('answer', 42)

Upgrading from 2.x / @types/hashmap

Types ship with the package since 3.0.0 — remove DefinitelyTyped:

npm uninstall @types/hashmap

@types/hashmap used export = HashMap (CommonJS assignment import). 3.0 uses a default export:

import HashMap from 'hashmap'
// import HashMap = require('hashmap')  // still works in TS with esModuleInterop

hash() was removed (internal helper, no known dependents). Deprecated remove(), count(), and type() remain. See docs/backwards-compatibility.md.

---

Browser

For a script tag without a bundler, use the IIFE build:

<script src="node_modules/hashmap/dist/hashmap.iife.js"></script>
<script>
  const map = new HashMap()
  map.set(document.body, 'root')
</script>

---

Benchmarks

3.0 rewrote the internals (numeric hashing, flat entry storage, eager Map index, cached entry hashes). Measured on Node 24, ~250 ms per benchmark, string keys unless noted. Run locally:

npm run benchmark
npm run benchmark -- -o tmp/current.json --compare tmp/benchmark-baseline.json

vs 2.4.0

Operation	2.4.0	3.0.0	Change
set	226K	266K	1.2×
get	224K	298K	1.3×
has	237K	268K	1.1×
delete	210K	264K	1.3×
set (replace existing key)	7K	193K	26×
get (map with 1024 entries)	10K	273K	27×
forEach (1024 entries)	29K	1.7M	60×
keys (1024 entries)	26K	722K	28×
clone (1024 entries)	11K	19K	1.7×
copy (1024 entries)	12K	19K	1.6×
set after delete (1024 entries)	238K	91K	0.4×

Summary: 18 of 20 benchmarks faster than 2.4.0. Biggest wins: replacing/updating keys, iteration, and clone/copy. Remaining gaps: burst inserts into an empty map and delete-then-set on large maps.

Values are ops/sec (higher is better). Native Map is faster on plain get with string keys — hashmap trades that for custom equality, .search(), and the legacy API.

---

Development

npm test        # types + unit tests
npm run build   # dist (esm, cjs, iife, dts)
npm run lint

License

MIT © Ariel Flesler