@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 – type‑invariant immutable map
- VariantMap – type‑variant immutable map
- @rimbu/collection-types/set – interfaces for:
- RSet – type‑invariant immutable set
- VariantSet – 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

$3

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

| Name | Description |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| Elem | Describes a collection that has an element type T (used by set‑like collections). |
| WithElem | Binds a higher‑kind Tp to a concrete element type T. |
| KeyValue | Describes a collection that has key type K and value type V (used by map‑like types). |
| WithKeyValue | Binds a higher‑kind Tp to concrete key and value types. |
| Row | Describes row/column/value types (used by table‑like collections). |
| WithRow | Binds a higher‑kind Tp to concrete row, column, and value 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:

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

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

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

For sets:

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

const s: RSet = 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:

$3

| Name | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| RMap | Type‑invariant immutable map of keys K to values V. Each key has exactly one value; no duplicate keys. |
| RMap.NonEmpty | Non‑empty refinement of RMap with stronger guarantees (e.g. isEmpty is always false). |
| RMap.Context | Factory/context for creating RMap instances with upper‑bounded key type UK. |
| RMap.Builder | Mutable builder used to efficiently construct or mutate an RMap before freezing it into an immutable instance. |
| VariantMap | Type‑variant immutable map of keys K to values V. Supports safe key/value widening; excludes mutating operations. |
| VariantMap.NonEmpty | Non‑empty refinement of VariantMap. |

$3

Concrete map implementations share a common core API:

`ts
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:

$3

| Name | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| RSet | Type‑invariant immutable set of values T. No duplicate values. |
| RSet.NonEmpty | Non‑empty refinement of RSet. |
| RSet.Context | Factory/context for creating RSet instances with upper‑bounded element type UT. |
| RSet.Builder | Mutable builder for efficiently constructing or mutating an RSet before freezing it. |
| VariantSet | Type‑variant immutable set of values T. Allows safe value widening; excludes mutating methods. |
| VariantSet.NonEmpty | Non‑empty refinement of VariantSet. |

$3

Concrete set implementations share a common core API:

`ts
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

$3

`sh
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:

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

> Replace with the desired Rimbu version.

$3

@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.