Rimbu: Immutable collections and tools for TypeScript

Rimbu is a modern TypeScript library for fast, immutable data structures and composable async utilities. It gives you persistent lists, maps, sets, graphs, tables, streams, channels, and tasks with a strong type story and predictable performance across Node, Deno, Bun, and the browser.

Use Rimbu when you want:

• Immutable by default: structural sharing instead of manual copying, ideal for state management and undo/redo.
• First-class TypeScript: rich generics, non-empty refinements, and higher-kinded collection types.
• Production-grade performance: tree-based and hash-based structures tuned for real applications.
• Composable APIs: collections, streams, channels, and tasks that interoperate cleanly.

Documentation & playground

• Docs: rimbu.org
• API reference: rimbu.org/api
• Guides & collection docs: rimbu.org/docs
• Playground / sandbox: Rimbu Sandbox on CodeSandbox

---

Getting started

Runtime compatibility

• Node
• Deno
• Bun
• Web

Install (@rimbu/core)

Yarn

yarn add @rimbu/core

npm

npm install @rimbu/core

pnpm

pnpm add @rimbu/core

Bun

bun add @rimbu/core

Deno

deno add npm:@rimbu/core

---

Quick example

import { List, HashMap, Stream } from '@rimbu/core';

type User = { id: number; name: string; active: boolean };

const users = List.of<User>(
  { id: 1, name: 'Ada', active: true },
  { id: 2, name: 'Grace', active: false },
  { id: 3, name: 'Linus', active: true }
);

// Build an immutable index by id
const byId = HashMap.from(users.stream().map((u) => [u.id, u] as const));

// Stream over active user names
const activeNames = Stream.from(users)
  .filter((u) => u.active)
  .map((u) => u.name)
  .toArray();

// Nothing above mutates the original data structures
console.log(byId.get(1)?.name); // 'Ada'
console.log(activeNames); // ['Ada', 'Linus']

For more examples, start from the @rimbu/core README or the online docs.

---

Stable packages (v1.0.0 and higher)

Rimbu is a monorepo of focused npm packages.
This overview only lists packages that have reached version 1.0.0 or higher. Each package directory contains a detailed README and API documentation links.

Core foundations

Package	Description
@rimbu/core	Single entrypoint that re-exports the main Rimbu collections and utilities from one import.
@rimbu/base	Foundational immutable array and utility primitives used by all other Rimbu collections.
@rimbu/collection-types	Shared map/set interfaces and higher-kinded collection types implemented by concrete packages.
@rimbu/common	Shared equality, comparison, range, lazy, and type-level utilities across the ecosystem.
@rimbu/deep	Deep patching, matching, paths, and selectors for treating plain JS objects as immutable data.

Collections: maps, sets, lists, graphs, tables

Package	Description
@rimbu/list	Immutable random-access lists (vector-like) with efficient updates, slicing, and non-empty variants.
@rimbu/hashed	HashMap and HashSet implementations with configurable hashing and equality strategies.
@rimbu/sorted	SortedMap and SortedSet with deterministic ordering, range queries, and index-based access.
@rimbu/ordered	OrderedMap and OrderedSet that preserve insertion order on top of existing map/set implementations.
@rimbu/bimap	Bidirectional maps (BiMap) that maintain a strict one-to-one mapping between keys and values.
@rimbu/bimultimap	Many-to-many bidirectional multimaps where keys and values can both have multiple associations.
@rimbu/multimap	One-to-many multimaps where each key maps to a set of unique values.
@rimbu/multiset	Multisets (bags) that track how many times each element occurs.
@rimbu/table	2D tables indexed by row and column keys, with hashed and sorted row/column variants.
@rimbu/graph	Directed, undirected, and valued graphs with traversal helpers and hashed/sorted variants.
@rimbu/proximity	Proximity-based maps (ProximityMap) that resolve lookups using nearest-key distance functions.

Streams, channels, and tasks

Package	Description
@rimbu/stream	Lazy synchronous and asynchronous streams (Stream / AsyncStream) for composable data pipelines.
@rimbu/channel	Typed channels and concurrency primitives (Go-style channels, remote channels, mutexes, semaphores).
@rimbu/task	Composable, cancellable async tasks with structured concurrency, retries, timeouts, and supervision.

---

Development

Local setup

1. Clone the repository.
2. Run yarn to install dependencies.
3. Build all packages with yarn build.
4. Run tests with yarn test.

See the individual package READMEs and the docs for package-specific commands (benchmarks, type tests, docs generation, etc.).

Contributing

We welcome contributions of all kinds—bug reports, docs, examples, and new features.
Please read the Contributing guide before opening an issue or pull request.

Author & community

• Author: Arvid Nicolaas
• Sponsors: Special thanks to early sponsors like bglgwyng 🙌

Contributors

Made with contributors-img.

---

License

This project is licensed under the MIT License. See the LICENSE for details.