# @rimbu/base
> Utilities to implement Rimbu collections
Latest version **2.0.7** (published 2026-01-19) · MIT license · 0 weekly downloads
## Install
```sh
npm install @rimbu/base
pnpm add @rimbu/base
yarn add @rimbu/base
bun add @rimbu/base
```
## Health
**Score 70/100 (B)** — status: stable.
Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 2.0.7 |
| Published | 2026-01-19 |
| First published | 2021-06-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 111.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 144 |
| Author | Arvid Nicolaas |
| Maintainers | vitoke |
| Keywords | array, rimbu, internal, typescript |
## Links
- npm: https://www.npmjs.com/package/@rimbu/base
- Repository: https://github.com/rimbu-org/rimbu
- Homepage: https://rimbu.org
- Issues: https://github.com/rimbu-org/rimbu/issues
- Funding: https://github.com/sponsors/vitoke
- npm.io page: https://npm.io/package/@rimbu/base
## Dependencies (1)
- [@rimbu/common](https://npm.io/package/@rimbu/common.md) ^2.0.7
## Alternatives
- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads
## Recent versions
- 2.0.7 (latest) — 2026-01-19
- 2.0.6 — 2026-01-15
- 2.0.5 — 2025-11-28
- 2.0.4 — 2025-11-25
- 2.0.3 — 2025-11-23
- 2.0.2 — 2025-05-16
- 2.0.1 — 2024-03-05
- 2.0.0 — 2024-01-26
- 1.1.0 — 2023-07-29
- 1.0.0 — 2023-07-03
- 1.0.0-alpha.2 — 2023-07-02
- 1.0.0-alpha.1 — 2023-07-02
- 0.11.4 — 2023-05-21
- 0.11.3 — 2023-04-26
- 0.11.2 — 2023-04-25
- … 29 more at https://npm.io/package/@rimbu/base/versions
## README
[](https://www.npmjs.com/package/@rimbu/base)
# `@rimbu/base`
**Foundational immutable array and utility primitives powering all other Rimbu collections.**
`@rimbu/base` exposes a small, efficient set of low-level utilities (array operations, tuple helpers, type predicates, error types) used internally across Rimbu’s high-level data structures. While primarily an implementation substrate, you can use these helpers directly for performance‑aware immutable array manipulation and advanced type constraints.
> Think: ultra-focused building blocks for persistent & type‑rich collections.
Full documentation: **[Rimbu Docs](https://rimbu.org)** · **[Rimbu API](https://rimbu.org/api)**
---
## Table of Contents
1. [Why Rimbu Base?](#why-rimbu-base)
2. [Feature Highlights](#feature-highlights)
3. [Quick Start](#quick-start)
4. [Immutable Array Operations (`Arr`)](#immutable-array-operations-arr)
5. [Tuple & Token Utilities](#tuple--token-utilities)
6. [Type Utilities (`plain-object`)](#type-utilities-plain-object)
7. [Error Types (`RimbuError`)](#error-types-rimbuerror)
8. [Installation](#installation)
9. [FAQ](#faq)
10. [Contributing](#contributing)
11. [License](#license)
12. [Attributions](#attributions)
13. [Quick Reference](#quick-reference-api-surface)
---
## Why Rimbu Base?
High‑level persistent collections depend on fast, predictable low‑level primitives. Instead of rewriting array cloning, sparse copying, index‑safe mutation, and structured error handling in every package, `@rimbu/base` centralizes these operations:
- **Consistency** – shared implementations eliminate subtle divergence.
- **Performance** – leverages modern `Array` prototype methods (`toSpliced`, `toReversed`, `with`, `at`) when available; falls back gracefully.
- **Immutability by default** – every operation returns a new array only when changes occur (structural sharing where possible).
- **Sparse array awareness** – preserves sparsity for specialized internal block layouts.
- **Type guards & predicates** – compile‑time discrimination for plain objects vs. functions/iterables.
- **Focused surface** – zero external runtime dependencies (aside from internal Rimbu type modules).
Use it directly if you need ergonomic immutable array helpers without pulling in full collection abstractions.
---
## Feature Highlights
- **`Arr` Immutable Ops** – `append`, `prepend`, `concat`, `reverse`, `update`, `mod`, `insert`, `splice`, `tail`, `init`, `last`, `mapSparse`, `copySparse`.
- **Conditional Optimization** – automatically chooses modern O(1) helpers when your runtime supports them.
- **Tuple Helpers** – `Entry.first`, `Entry.second` for lightweight entry handling in map-like structures.
- **Type Predicates** – `IsPlainObj`, `IsArray`, `IsAny`, plus runtime `isPlainObj`, `isIterable`.
- **Structured Errors** – clear error signaling via custom error classes (e.g. `InvalidStateError`).
- **Sentinel Token** – a shared `Token` symbol for internal identity and tagging.
- **Tree-shakable** – import only what you use: `import { Arr } from '@rimbu/base';`.
---
## Quick Start
```ts
import { Arr } from '@rimbu/base';
const base = [1, 2, 3];
// Pure modification: only clones when the value actually changes
const incremented = Arr.mod(base, 1, (v) => v + 1); // [1, 3, 3]
// Structural no-op returns original reference for efficiency
const same = Arr.mod(base, 5, (v) => v); // index out of range → original
// Append without mutating
const appended = Arr.append(incremented, 4); // [1, 3, 3, 4]
// Reverse slice
const reversed = Arr.reverse(appended); // [4, 3, 3, 1]
console.log(base); // [1, 2, 3]
```
---
## Immutable Array Operations (`Arr`)
All functions accept a `readonly T[]` input and return either the original array (when unchanged) or an optimized clone.
| Function | Purpose |
| -------------------- | --------------------------------------------------------- |
| `append` | Add element at end (non-empty array optimization). |
| `prepend` | Add element at start efficiently. |
| `concat` | Smart concat – reuses original when one side empty. |
| `reverse` | Fast reversed copy (range slice optional). |
| `forEach` | Controlled traversal with optional reverse + halt state. |
| `map` / `reverseMap` | Indexed transformation forward or backward. |
| `last` | O(1) last element access (uses `.at(-1)` when available). |
| `update` | Apply `Update` logic at index (no-op preserved). |
| `mod` | Lightweight element modification via `(value)=>value'`. |
| `insert` | Insert at index. |
| `tail` / `init` | Drop first / last element. |
| `splice` | Immutable variant of native splice. |
| `copySparse` | Preserve holes in sparse arrays. |
| `mapSparse` | Transform only present indices, keeping sparsity. |
Design details:
- Uses native **copy-on-write** style helpers when available for speed.
- Avoids unnecessary cloning when an update is identity.
- Preserves array holes for internal block structures requiring sparse layout semantics.
---
## Tuple & Token Utilities
```ts
import { Entry, Token } from '@rimbu/base';
const pair: readonly [string, number] = ['age', 42];
Entry.first(pair); // 'age'
Entry.second(pair); // 42
// Shared sentinel for internal tagging / identity
if (someValue === Token) {
/* special branch */
}
```
---
## Type Utilities (`plain-object`)
Compile-time predicates for discriminating plain data objects from complex / functional structures:
| Type | Description |
| ----------------- | ---------------------------------------------------------------------------------- |
| `IsPlainObj` | True only for non-iterable, non-function object types without function properties. |
| `PlainObj` | Narrows to T if `IsPlainObj`; otherwise `never`. |
| `IsArray` | Resolves to `true` if T is a (readonly) array type. |
| `IsAny` | Detects `any`. |
| `isPlainObj(obj)` | Runtime guard for plain data objects. |
| `isIterable(obj)` | Runtime guard for `Iterable`. |
Use these when building APIs that must reject iterables or functions while retaining strong type discrimination.
---
## Error Types (`RimbuError`)
Structured error classes provide meaningful failure contexts internally and externally:
| Error Class | Trigger Scenario |
| ---------------------------------------- | ---------------------------------------------- |
| `EmptyCollectionAssumedNonEmptyError` | An operation expected a non-empty collection. |
| `ModifiedBuilderWhileLoopingOverItError` | Mutating a builder mid-iteration. |
| `InvalidStateError` | Internal invariant breach (should not happen). |
| `InvalidUsageError` | Consumer used an API incorrectly. |
Helper throw functions exist for concise signaling (`throwInvalidStateError()`, etc.). Prefer them for consistency.
---
## Installation
### Compabitity
- [`Node` ](https://nodejs.org)
- [`Bun` ](https://bun.sh/)
- `Web` 
### Package Managers
**Yarn:**
```sh
yarn add @rimbu/base
```
**npm:**
```sh
npm install @rimbu/base
```
**Bun:**
```sh
bun add @rimbu/base
```
**Deno:**
```sh
deno add npm:@rimbu/base
```
## Usage
```ts
import { Arr } from '@rimbu/base';
const arr = [1, 2, 3];
console.log(Arr.mod(arr, 1, (v) => v + 1));
// [1, 3, 3]
console.log(arr);
// [1, 2, 3]
```
## Author
Created and maintained by [Arvid Nicolaas](https://github.com/vitoke).
## Contributing
We welcome contributions! Please read our [Contributing guide](https://github.com/rimbu-org/rimbu/blob/main/CONTRIBUTING.md).
## Contributors
_Made with [contributors-img](https://contrib.rocks)._
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) for details.
---
_Source: https://npm.io/package/@rimbu/base · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._