@rimbu/bimap

Fast, immutable bidirectional maps for TypeScript & JavaScript.

@rimbu/bimap provides an efficient, type-safe BiMap: a data structure that maintains a strict one‑to‑one relationship between keys and values. Every key maps to exactly one value, and every value maps back to exactly one key – giving you O(1)-style lookup in both directions with immutable, persistent semantics.

Use it whenever you need reverse lookups, unique associations (like IDs ↔ handles, user ↔ email, code ↔ label), or want to avoid keeping two maps in sync manually.

Table of Contents

1. Why @rimbu/bimap?
2. Feature Highlights
3. Quick Start
4. Core Concepts & Types
5. Working with Hash & Sorted BiMaps
6. Performance Notes
7. Installation
8. FAQ
9. Ecosystem & Integration
10. Contributing
11. License

Why @rimbu/bimap?

Plain maps give you key → value lookups, but often you also need value → key:

• Unique identifiers – map userId ↔ email, handle ↔ id, token ↔ session.
• Code / label pairs – statusCode ↔ statusLabel, enumValue ↔ string.
• Indexing external data – keep a stable, unique mapping between two domains.

@rimbu/bimap focuses on:

• True bijection – the structure guarantees a one‑to‑one mapping at all times.
• Immutable operations – updates return new instances, sharing structure internally.
• Safe reverse lookups – getValue and getKey mirror each other.
• Ergonomic API – familiar map-like operations plus BiMap‑specific helpers.

If you find yourself maintaining two maps in sync, a BiMap is usually the better fit.

Feature Highlights

• Bidirectional lookups – efficient key → value and value → key access.
• Strict uniqueness – inserting a key or value replaces any existing association.
• Immutable & persistent – structural sharing for fast copies and diffs.
• Multiple views – access keyValueMap and valueKeyMap as regular Rimbu maps.
• Configurable contexts – backed by hash maps by default, with support for custom underlying map contexts via BiMap.createContext.
• Rich operations – add/remove by key or value, bulk updates, streaming, traversal utilities.

Quick Start

import { BiMap } from '@rimbu/bimap';

// Create from entry tuples
const biMap = BiMap.of([1, 'a'], [2, 'b'], [3, 'c']);

// Forward lookup: key -> value
console.log(biMap.getValue(2)); // 'b'

// Reverse lookup: value -> key
console.log(biMap.getKey('c')); // 3

// Update associations immutably
const updated = biMap.set(2, 'z'); // value 'z' can only belong to one key
console.log(updated.getKey('z')); // 2

Try Rimbu (including @rimbu/bimap) live in the browser using the Rimbu Sandbox on CodeSandbox.

Core Concepts & Types

Exported Types

| Name | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | BiMap<K, V> | Immutable, type‑invariant bidirectional map with a strict one‑to‑one mapping between K and V. | | BiMap.NonEmpty<K, V> | Non‑empty refinement of BiMap<K, V> with stronger type guarantees. | | BiMap.Context<UK, UV> | Factory/context for creating BiMaps with configurable underlying map implementations for keys and values. | | BiMap.Builder<K, V> | Mutable builder for efficiently constructing or mutating a BiMap before freezing it into an immutable instance. |

Key Operations

import { BiMap } from '@rimbu/bimap';

// Construction
const empty = BiMap.empty<number, string>();
const fromEntries = BiMap.of([1, 'one'], [2, 'two']);

// Size & emptiness
empty.isEmpty; // true
fromEntries.size; // 2

// Lookups
fromEntries.hasKey(1); // true
fromEntries.hasValue('two'); // true
fromEntries.getValue(2); // 'two'
fromEntries.getKey('one'); // 1

// Updating (returns new BiMap)
const updated = fromEntries.set(3, 'three');

// Removing by key or value
const withoutKey = updated.removeKey(1);
const withoutValue = updated.removeValue('two');

See the full BiMap docs and API reference for all operations.

Performance Notes

• BiMaps in Rimbu are built on persistent data structures – updates are typically \(O(\log n)\) and share most of their structure.
• Lookups by key or value are designed to behave similarly to their underlying map implementations (HashMap / sorted maps).
• Many bulk operations accept generic StreamSource inputs, letting you construct and transform BiMaps efficiently from arrays, iterables, or streams.

For detailed performance characteristics and benchmarks, see the main Rimbu documentation at rimbu.org.

Installation

Node / Bun / npm / Yarn / Deno

npm install @rimbu/bimap
# or
yarn add @rimbu/bimap
# or
bun add @rimbu/bimap
# or
deno add npm:@rimbu/bimap

Browser / ESM

@rimbu/bimap ships both ESM and CJS builds. Use it with any modern bundler (Vite, Webpack, esbuild, Bun, etc.) or directly in Node ESM projects.

FAQ

Q: How is a BiMap different from a regular Map?
A BiMap enforces a one‑to‑one relationship: each value can appear at most once. It also gives you efficient value → key lookups via getKey.

Q: What happens if I insert a key or value that already exists?
The new association replaces the previous one, keeping the BiMap bijective. This may remove or re‑associate other entries to preserve uniqueness.

Q: Is the structure mutable?
No. All updates return new BiMap instances; existing ones remain unchanged and can be safely shared across your application.

Q: Can I iterate keys or values separately?
Yes. Use keyValueMap and valueKeyMap to access standard Rimbu map views with all their APIs.

Ecosystem & Integration

• Part of the broader Rimbu collection ecosystem – interoperates with @rimbu/hashed, @rimbu/ordered, @rimbu/collection-types, and @rimbu/stream.
• Ideal for modelling unique relationships in domain models, routing tables, protocol maps, etc.
• Works seamlessly with other Rimbu collections and utilities for building rich, immutable data models.

Explore more at the Rimbu documentation and the BiMap API docs.

Contributing

We welcome contributions! See the Contributing guide for details.

Made with contributors-img.

License

MIT © Rimbu contributors. See LICENSE for details.

Attributions

Created and maintained by Arvid Nicolaas. Logo © Rimbu.