swisstable

This package is a port of Google's high-performance SwissTable hash map to freestanding wasm32, with thin TypeScript bindings. Keys are u32.

The table lives entirely inside WebAssembly linear memory: keys, values, control bytes, and probing never cross the JavaScript boundary, so a lookup costs one WASM call and a bulk operation costs one call per chunk regardless of batch size. At 100,000 entries that makes it 1.4–12x faster than Map on sparse integer keys — on Bun, Node, Deno, Chrome, and Firefox alike — with the widest margins on mutation and bulk transfer. Map wins below ~2,000 entries and on string keys, and dense integer keys belong in a typed array — see when not to use this.

The original C++ version can be found here.

Docs: API · Design · Performance · Examples · Contributing

Features

• One byte of metadata per slot, compared sixteen at a time with wasm_simd128.
• 10.3 bytes per entry at full occupancy, 20.6 with the standby bank a rehash needs, against a measured 37 for Map on V8 and 67 on JavaScriptCore.
• Holds up to 117,440,512 entries (u32) or 58,720,256 (u64).
• An instance starts at 1.25 MiB (u32) or 1.75 MiB (u64) and grows with the table, so a small table costs what a small table costs. See Footprint. dispose(), or a using declaration, hands an instance back without waiting for the collector.
• Bulk setMany/getMany/deleteMany on both tables cross once per batch: a 100,000-entry u32 fill is 6.1–6.9 ns/op against Map's 48–70, and the matching lookup 3.9–4.9 against 11–24.
• getOrInsert and increment do a read-modify-write in one crossing and one probe. Inserting a missing key is 5.0–6.3x faster than Map.
• No allocator. Linked -nostdlib, with the banks at computed offsets and linear memory grown to reach them. Nothing allocates on a hot path.
• Ships compiled ESM with type declarations, and the modules are compiled in: no .wasm to serve, no loader to write, no install step, no dependencies.
• Runs in Node, Bun, Deno, bundlers, and browsers. Anything with WebAssembly SIMD (Node 16.9+, Chrome 91+, Firefox 89+, Safari 16.4+), which supportsSimd() reports for the current runtime.

Usage

npm install swisstable    # or bun add / pnpm add / yarn add

Then:

import { SwissU32ToU32 } from "swisstable";

// Sizing up front avoids rehashing during the initial fill.
const table = await SwissU32ToU32.create(100_000);

table.set(0xdead_beef, 42);
table.get(0xdead_beef); // 42

create uses the module compiled into the package and compiles it once, sharing it across every table. To control loading yourself — streaming compilation, a module shared across workers, a custom asset path — use load(bytes) instead; the .wasm files are also exposed as package subpaths. loadSync(module) builds a table from an already-compiled module without awaiting, for the places that cannot.

Four exports:

| Export | Mapping | Use it for | | --- | --- | --- | | SwissU32ToU32 | u32 -> u32 | counters, ID remaps, presence sets | | SwissU32ToU64 | u32 -> u64 as {lo, hi} lanes | spans, offsets, packed pairs | | StringInterner | string -> u32 | stable IDs in first-seen order | | InternedSwissMap | string -> V | string keys over a numeric table |

Keys and values are strictly u32 and anything else throws RangeError. Capacity is bounded at 117,440,512 entries (u32) or 58,720,256 (u64). A stored 0 is always distinguishable from an absent key. See docs/api.md for every method and thrown error, and examples/ for five runnable programs.

Two operational notes. Each table seeds its hash from the runtime's CSPRNG, so a colliding key set cannot be computed offline and reused across processes; createWithSeed fixes the seed for reproducible runs and should not be pointed at untrusted input. And a table is single-threaded — one instance is one table, and no instance may be shared across workers. Both are covered in Untrusted keys and threading.

When not to use this

| Situation | Use instead | Why | | --- | --- | --- | | Fewer than ~2k entries | Map | A crossing costs a few ns before any work happens, and both containers are cache-resident. Between 2k and 16k the winner depends on the engine. | | String keys, looked up repeatedly | Map<string, V> | Engines cache a string's hash on the string object; a WASM table must copy and rehash the bytes. | | Dense integer keys with no gaps | Int32Array | Direct indexing is 0.5 ns and needs no hashing. | | Non-integer or > 2^32 - 1 keys | Map | Anything outside u32 throws. |

Both limits are structural rather than tuning problems; docs/performance.md quantifies them.

Benchmarks

Speedup against Map at 100,000 sparse u32 keys — above 1.00x the table is faster. Median of 21 rounds and of 3 passes, each contender in an isolate of its own, probed in a shuffled order. i9-13900K on x64 Linux.

| Workload | Bun 1.3 | Node 24 | Deno 2.9 | Chrome 151 | Firefox 153 | | --- | --- | --- | --- | --- | --- | | fill (pre-sized) | 5.2x | 6.2x | 5.0x | 3.6x | 4.7x | | lookup hit | 1.50x | 2.7x | 2.8x | 2.3x | 1.60x | | lookup miss | 1.29x | 3.2x | 3.4x | 2.5x | 1.70x | | has | 1.77x | 3.2x | 3.5x | 2.9x | 1.86x | | overwrite existing key | 2.2x | 2.5x | 2.5x | 2.2x | 2.8x | | delete | 6.1x | 5.5x | 5.8x | 4.1x | 4.7x | | churn (delete + reinsert) | 3.3x | 3.6x | 3.5x | 2.6x | 3.2x | | count (increment) | 1.26x | 1.33x | 1.35x | 1.28x | 0.89x | | u32 bulk fill (setMany) | 8.4x | 11x | 8.3x | 7.6x | 9.2x | | u32 bulk lookup (getMany) | 2.7x | 5.6x | 4.9x | 5.4x | 3.6x | | u64 bulk fill (setMany) | 10x | 9.7x | 8.6x | 6.4x | 8.5x | | u64 bulk lookup (getMany) | 2.1x | 4.1x | 3.8x | 3.6x | 2.3x |

The table costs about the same on every engine. The columns differ because Map does. Counting is the one row a browser engine takes: at 1,000 distinct keys Map stays in cache, and the crossing is most of the budget.

Reproduce with bun run build && bun run bench, or bun run bench:all for every runtime installed. Absolute figures, the cost model, the crossover by engine, and where the caller's own key storage costs 1.7x are in docs/performance.md.

Contributing

Contributions are welcome. Bug reports and benchmark results on other hardware are especially useful — the numbers above are from one machine. bun run bench:all followed by bun run bench:compare produces them in the same form, and records the engine, CPU, and clock each column was taken on.

bun install
bun run hooks      # lefthook pre-commit and pre-push gates
bun run build      # compile native/*.c to dist/wasm/*.wasm
bun test           # 246 tests across 24 suites
bun run typecheck
bun run smoke      # the built package under plain Node
bun run smoke:browser  # the built package in Chrome or Firefox
bun run bench      # this runtime
bun run bench:all  # bun, node, deno, chrome, firefox — three passes each

Run build, test, and typecheck before opening a pull request; bun run build is not optional even for a TypeScript-only change, since the tests load the compiled modules. Building needs nothing installed: bun run build downloads the pinned Zig toolchain into .zig/, verifies it against its published checksum, and compiles with it. Read docs/design.md before touching the C — several invariants are load bearing and not obvious from the code, and CONTRIBUTING.md has the full guide.

License

MIT