@rimbu/collection-types

Core collection interfaces for maps and sets in the Rimbu ecosystem.

@rimbu/collection-types provides the shared public interfaces and higher‑kind utility types used by all Rimbu collection implementations.
It defines the common contracts for:

• Maps – via @rimbu/collection-types/map
• Sets – via @rimbu/collection-types/set

Concrete implementations such as HashMap, SortedMap, HashSet, and SortedSet (from packages like @rimbu/hashed, @rimbu/sorted, etc.) implement these interfaces.

For a high‑level overview, see the Immutable Collections docs.
For full API details, see the Collection Types API reference.

You can also try Rimbu in the browser.

Table of Contents

1. Sub‑packages
2. Core Concepts & Types
3. Quick Start
4. Map Interfaces
5. Set Interfaces
6. Installation
7. Ecosystem & Integration
8. Contributing
9. License

Sub‑packages

This package acts as a convenience entry point that re‑exports the following sub‑packages:

• @rimbu/collection-types/map – interfaces for:
  • RMap<K, V> – type‑invariant immutable map
  • VariantMap<K, V> – type‑variant immutable map
• @rimbu/collection-types/set – interfaces for:
  • RSet<T> – type‑invariant immutable set
  • VariantSet<T> – type‑variant immutable set

Each of these sub‑packages is implemented by concrete data structures in packages like @rimbu/hashed, @rimbu/ordered, @rimbu/sorted, etc.

Core Concepts & Types

Utility Higher‑Kind Types

The @rimbu/collection-types/common module exposes reusable higher‑kind helper types:

These types are used to express higher‑kinded collection families, such as the Types helpers on RMap, VariantMap, RSet, and VariantSet.

Quick Start

Although @rimbu/collection-types itself only contains types and interfaces, you’ll mostly encounter it indirectly when using concrete collections such as HashMap or HashSet:

import { HashMap } from '@rimbu/hashed'; // implements RMap
import type { RMap } from '@rimbu/collection-types/map';

const m: RMap<number, string> = HashMap.of([1, 'one'], [2, 'two']);

console.log(m.get(2)); // 'two'

For sets:

import { HashSet } from '@rimbu/hashed';
import type { RSet } from '@rimbu/collection-types/set';

const s: RSet<number> = HashSet.of(1, 2, 3);

console.log(s.has(2)); // true
console.log(s.toArray()); // [1, 2, 3] (order depends on implementation)

Map Interfaces

From @rimbu/collection-types/map:

Exported Types

Key Operations (via RMapBase / VariantMapBase)

Concrete map implementations share a common core API:

import { HashMap } from '@rimbu/hashed';

const m = HashMap.of<[number, string]>([1, 'a'], [2, 'b']);

// Size & emptiness
m.size; // 2
m.isEmpty; // false
m.nonEmpty(); // true (narrows type)

// Lookups
m.get(2); // 'b'
m.hasKey(1); // true

// Transform / filter
const onlyB = m.filter(([k, v]) => v === 'b');
const lengths = m.mapValues((v) => v.length);

// Bulk operations (implementation‑specific)
const m2 = m.set(3, 'c').removeKey(1);

For the full list of operations and overloads, see:

• Map docs
• @rimbu/collection-types/map API

Set Interfaces

From @rimbu/collection-types/set:

Exported Types

Key Operations (via RSetBase / VariantSetBase)

Concrete set implementations share a common core API:

import { HashSet } from '@rimbu/hashed';

const s = HashSet.of(1, 2, 3);

// Size & emptiness
s.size; // 3
s.isEmpty; // false

// Membership
s.has(2); // true

// Combining sets
const other = HashSet.of(2, 4);
const union = s.union(other); // {1, 2, 3, 4}
const diff = s.difference(other); // {1, 3}
const inter = s.intersect(other); // {2}

// Builders
const builder = s.toBuilder();
builder.add(5);
const s2 = builder.build();

See also:

• Set docs
• @rimbu/collection-types/set API

Installation

Node / Bun / npm / Yarn

npm install @rimbu/collection-types
# or
yarn add @rimbu/collection-types
# or
bun add @rimbu/collection-types
# or
deno add npm:@rimbu/collection-types

Then you can import relative modules, for example:

import { HashMap } from '@rimbu/hashed/mod.ts';
import { RMap } from '@rimbu/collection-types/map/mod.ts';

Replace <version> with the desired Rimbu version.

Browser / ESM

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

Ecosystem & Integration

• Part of the broader Rimbu collection ecosystem – interoperates with packages like @rimbu/core, @rimbu/hashed, @rimbu/ordered, @rimbu/sorted, @rimbu/bimap, and others.
• The interfaces in this package define the shared contracts that all map/set implementations conform to.
• Many Rimbu utilities (@rimbu/stream, @rimbu/common, etc.) are designed to work with these interfaces directly.

Explore more at the Rimbu documentation and the
Collection Types 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.