@rimbu/base 2.0.2 → 2.0.4

package/README.md

@@ -2,24 +2,179 @@
     <img src="https://github.com/rimbu-org/rimbu/raw/main/assets/rimbu_logo.svg" />
 </p>
 
-[![npm version](https://badge.fury.io/js/@rimbu%2Fbase.svg)](https://www.npmjs.com/package/@rimbu/base) [![Deno](https://shield.deno.dev/x/rimbu)](http://deno.land/x/rimbu)
+[![npm version](https://badge.fury.io/js/@rimbu%2Fbase.svg)](https://www.npmjs.com/package/@rimbu/base)
+![License](https://img.shields.io/github/license/rimbu-org/rimbu)
+![Types Included](https://img.shields.io/badge/TypeScript-ready-blue)
+![Node](https://img.shields.io/badge/Node-18+-6DA55F?logo=node.js&logoColor=white)
+![Bun](https://img.shields.io/badge/Bun-%23000000.svg)
+![ESM + CJS](https://img.shields.io/badge/modules-ESM%20%2B%20CJS-informational)
 
-![Licence](https://img.shields.io/github/license/rimbu-org/rimbu)
+</div>
 
-# @rimbu/base
+# `@rimbu/base`
 
-This package contains mostly utilities to implement the other Rimbu collections. The types are not exported by any of the other packages, but are internally used by most of them.
+**Foundational immutable array and utility primitives powering all other Rimbu collections.**
 
-Most important are the exported `Arr` methods that are used at the basis of all the block-based data structures. These methods should be as correct and efficient as possible.
+`@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.
 
-For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_ or the _[Rimbu API Docs](https://rimbu.org/api)_
+> 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<T>` 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<T>`   | True only for non-iterable, non-function object types without function properties. |
+| `PlainObj<T>`     | Narrows to T if `IsPlainObj<T>`; otherwise `never`.                                |
+| `IsArray<T>`      | Resolves to `true` if T is a (readonly) array type.                                |
+| `IsAny<T>`        | 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` ![NodeJS](https://img.shields.io/badge/node.js-6DA55F?logo=node.js&logoColor=white)](https://nodejs.org)
-- [`Deno` ![Deno JS](https://img.shields.io/badge/deno%20js-000000?logo=deno&logoColor=white)](https://deno.com/runtime)
 - [`Bun` ![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logoColor=white)](https://bun.sh/)
 - `Web` ![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?logoColor=white)
 
@@ -43,37 +198,12 @@ npm install @rimbu/base
 bun add @rimbu/base
 ```
 
-### Deno Setup
-
-Create or edit `import_map.json` in your project root:
-
-```json
-{
-  "imports": {
-    "@rimbu/": "https://deno.land/x/rimbu@x.y.z/"
-  }
-}
-```
-
-_Replace `x.y.z` with the desired version._
+**Deno:**
 
-In this way you can use relative imports from Rimbu in your code, like so:
-
-```ts
-import { List } from '@rimbu/core/mod.ts';
-import { HashMap } from '@rimbu/hashed/mod.ts';
-```
-
-Note that for sub-packages, due to conversion limitations it is needed to import the `index.ts` instead of `mod.ts`, like so:
-
-```ts
-import { HashMap } from '@rimbu/hashed/map/index.ts';
+```sh
+deno add npm:@rimbu/base
 ```
 
-To run your script (let's assume the entry point is in `src/main.ts`):
-
-`deno run --import-map import_map.json src/main.ts`
-
 ## Usage
 
 ```ts

package/dist/bun/arr.mts

@@ -1,19 +1,48 @@
 import { TraverseState, Update, type ArrayNonEmpty } from '@rimbu/common';
 
+/**
+ * Internal helper that appends a value using the modern immutable `toSpliced` API.
+ * @internal
+ * @typeparam T - the array element type
+ * @param array - the source array (not mutated)
+ * @param value - the value to append
+ * @returns a new non-empty array with the value at the end
+ */
 export function _appendNew<T>(array: readonly T[], value: T): ArrayNonEmpty<T> {
   return array.toSpliced(array.length, 0, value) as ArrayNonEmpty<T>;
 }
 
+/**
+ * Internal helper that appends a value by cloning and pushing (legacy fallback).
+ * @internal
+ * @typeparam T - the array element type
+ * @param array - the source array (not mutated)
+ * @param value - the value to append
+ * @returns a new non-empty array with the value at the end
+ */
 export function _appendOld<T>(array: readonly T[], value: T): ArrayNonEmpty<T> {
   const clone = array.slice();
   clone.push(value);
   return clone as ArrayNonEmpty<T>;
 }
 
-// Returns a copy of the array with the given value appended
+/**
+ * Returns a copy of the array with the given value appended.
+ * Chooses an implementation depending on environment capabilities.
+ * @typeparam T - the array element type
+ * @param array - the source array (not mutated)
+ * @param value - the value to append
+ * @returns a new array with the value at the end
+ */
 export const append = `toSpliced` in Array.prototype ? _appendNew : _appendOld;
 
-// Returns the concatenation of the two arrays, potentially reusing the input array if one of the arrays is empty
+/**
+ * Returns the concatenation of two arrays, reusing an input array when the other is empty.
+ * @typeparam T - the array element type
+ * @param first - the first array
+ * @param second - the second array
+ * @returns a new array containing all elements of both arrays (or one of the originals if the other is empty)
+ */
 export function concat<T>(
   first: readonly T[],
   second: readonly T[]
@@ -23,6 +52,10 @@ export function concat<T>(
   return first.concat(second);
 }
 
+/**
+ * Internal helper to create a reversed copy using modern `toReversed` with optional slicing.
+ * @internal
+ */
 export function _reverseNew<T>(
   array: readonly T[],
   start?: number,
@@ -36,6 +69,10 @@ export function _reverseNew<T>(
   return source.toReversed();
 }
 
+/**
+ * Internal helper to create a reversed copy using manual iteration (legacy fallback).
+ * @internal
+ */
 export function _reverseOld<T>(
   array: readonly T[],
   start?: number,
@@ -54,11 +91,25 @@ export function _reverseOld<T>(
   return res;
 }
 
-// Returns an copy of the array between the start and end indices, with the elements in reversed order.
+/**
+ * Returns a copy of the array (or a slice) with elements in reversed order.
+ * @typeparam T - array element type
+ * @param array - the source array
+ * @param start - optional start index (inclusive)
+ * @param end - optional end index (inclusive)
+ */
 export const reverse =
   'toReversed' in Array.prototype ? _reverseNew : _reverseOld;
 
-// Performs given function on each element of the array, in reverse order if 'reversed' is true.
+/**
+ * Performs the given function for each element of the array, optionally in reverse order.
+ * Halting is supported through the provided `TraverseState`.
+ * @typeparam T - element type
+ * @param array - the source array
+ * @param f - callback receiving (value, sequential index, halt)
+ * @param state - traversal state (created if omitted)
+ * @param reversed - whether to traverse in reverse order
+ */
 export function forEach<T>(
   array: readonly T[],
   f: (value: T, index: number, halt: () => void) => void,
@@ -85,7 +136,15 @@ export function forEach<T>(
   }
 }
 
-// Returns a copy of the array where given function is applied to each element
+/**
+ * Returns a copy of the array where the given function is applied to each element.
+ * Supports an index offset useful for composed traversals.
+ * @typeparam T - source element type
+ * @typeparam R - result element type
+ * @param array - the source array
+ * @param f - the mapping function
+ * @param indexOffset - optional start index value passed to `f`
+ */
 export function map<T, R>(
   array: readonly T[],
   f: (value: T, index: number) => R,
@@ -107,7 +166,14 @@ export function map<T, R>(
   return result;
 }
 
-// Returns a copy of the array where given functio is applied to each element in reverse order
+/**
+ * Returns a copy of the array where the given function is applied to each element in reverse order.
+ * @typeparam T - source element type
+ * @typeparam R - result element type
+ * @param array - the source array
+ * @param f - the mapping function
+ * @param indexOffset - optional index offset passed to `f`
+ */
 export function reverseMap<T, R>(
   array: readonly T[],
   f: (value: T, index: number) => R,
@@ -124,6 +190,10 @@ export function reverseMap<T, R>(
   return result;
 }
 
+/**
+ * Internal helper to prepend a value using `toSpliced`.
+ * @internal
+ */
 export function _prependNew<T>(
   array: readonly T[],
   value: T
@@ -131,6 +201,10 @@ export function _prependNew<T>(
   return array.toSpliced(0, 0, value) as ArrayNonEmpty<T>;
 }
 
+/**
+ * Internal helper to prepend a value using legacy cloning.
+ * @internal
+ */
 export function _prependOld<T>(
   array: readonly T[],
   value: T
@@ -140,21 +214,42 @@ export function _prependOld<T>(
   return clone as ArrayNonEmpty<T>;
 }
 
-// Returns a copy of the given array with the given value added at the start
+/**
+ * Returns a copy of the array with the given value inserted at the start.
+ * @typeparam T - element type
+ * @param array - the source array
+ * @param value - value to insert at index 0
+ */
 export const prepend =
   `toSpliced` in Array.prototype ? _prependNew : _prependOld;
 
+/**
+ * Internal helper to obtain the last element using modern `at`.
+ * @internal
+ */
 export function _lastNew<T>(arr: readonly T[]): T {
   return arr.at(-1)!;
 }
 
+/**
+ * Internal helper to obtain the last element using index arithmetic.
+ * @internal
+ */
 export function _lastOld<T>(arr: readonly T[]): T {
   return arr[arr.length - 1];
 }
 
-// Returns the last element of the array
+/**
+ * Returns the last element of the array.
+ * @typeparam T - element type
+ * @param arr - the array
+ */
 export const last = `at` in Array.prototype ? _lastNew : _lastOld;
 
+/**
+ * Internal helper implementing an immutable index update via `with`.
+ * @internal
+ */
 export function _updateNew<T>(
   arr: readonly T[],
   index: number,
@@ -173,6 +268,10 @@ export function _updateNew<T>(
   return arr.with(index, newValue);
 }
 
+/**
+ * Internal helper implementing an immutable index update via cloning.
+ * @internal
+ */
 export function _updateOld<T>(
   arr: readonly T[],
   index: number,
@@ -193,10 +292,20 @@ export function _updateOld<T>(
   return newArr;
 }
 
-// Returns a copy of the array where the element at given index is replaced by the given updater.
-// If the new element is the same as the old element, the original array is returned
+/**
+ * Returns a copy of the array where the element at the given index is replaced using the provided updater.
+ * If the result value is identical (by `Object.is`) the original array is returned.
+ * @typeparam T - element type
+ * @param arr - the source array
+ * @param index - the index to update
+ * @param updater - value or function update description
+ */
 export const update = `with` in Array.prototype ? _updateNew : _updateOld;
 
+/**
+ * Internal helper applying a modifier function via `with`.
+ * @internal
+ */
 export function _modNew<T>(
   arr: readonly T[],
   index: number,
@@ -216,6 +325,10 @@ export function _modNew<T>(
   return arr.with(index, newValue);
 }
 
+/**
+ * Internal helper applying a modifier function via cloning.
+ * @internal
+ */
 export function _modOld<T>(
   arr: readonly T[],
   index: number,
@@ -237,33 +350,65 @@ export function _modOld<T>(
   return newArr;
 }
 
-// Returns a copy of the array where the element at given index is replaced by applying given function.
-// If the new element is the same as the old element, the original array is returned
+/**
+ * Returns a copy of the array where the element at the given index is transformed by a modifier function.
+ * If the result value is identical (by `Object.is`) the original array is returned.
+ * @typeparam T - element type
+ * @param arr - the source array
+ * @param index - the index to modify
+ * @param f - modifier function receiving the current value
+ */
 export const mod = `with` in Array.prototype ? _modNew : _modOld;
 
+/**
+ * Internal helper for inserting a value using `toSpliced`.
+ * @internal
+ */
 export function _insertNew<T>(arr: readonly T[], index: number, value: T): T[] {
   return arr.toSpliced(index, 0, value);
 }
 
+/**
+ * Internal helper for inserting a value using legacy `splice` on a clone.
+ * @internal
+ */
 export function _insertOld<T>(arr: readonly T[], index: number, value: T): T[] {
   const clone = arr.slice();
   clone.splice(index, 0, value);
   return clone;
 }
 
-// Returns a copy of the array where at given index the given value is inserted
+/**
+ * Returns a copy of the array where at the given index the provided value is inserted.
+ * @typeparam T - element type
+ * @param arr - the source array
+ * @param index - insertion index
+ * @param value - value to insert
+ */
 export const insert = `toSpliced` in Array.prototype ? _insertNew : _insertOld;
 
-// Returns a copy of the array, without its first element
+/**
+ * Returns a copy of the array without its first element.
+ * @typeparam T - element type
+ * @param arr - the source array
+ */
 export function tail<T>(arr: readonly T[]): T[] {
   return arr.slice(1);
 }
 
-// Returns a copy of the array, without its last element
+/**
+ * Returns a copy of the array without its last element.
+ * @typeparam T - element type
+ * @param arr - the source array
+ */
 export function init<T>(arr: readonly T[]): T[] {
   return arr.slice(0, arr.length - 1);
 }
 
+/**
+ * Internal helper providing an immutable `splice` using `toSpliced`.
+ * @internal
+ */
 export function _spliceNew<T>(
   arr: readonly T[],
   start: number,
@@ -273,6 +418,10 @@ export function _spliceNew<T>(
   return arr.toSpliced(start, deleteCount, ...items);
 }
 
+/**
+ * Internal helper providing an immutable `splice` via cloning.
+ * @internal
+ */
 export function _spliceOld<T>(
   arr: readonly T[],
   start: number,
@@ -284,10 +433,21 @@ export function _spliceOld<T>(
   return clone;
 }
 
-// Immutable version of the array .splice command, always returns a new array
+/**
+ * Immutable version of the array `.splice` command, always returning a new array.
+ * @typeparam T - element type
+ * @param arr - the source array
+ * @param start - start index
+ * @param deleteCount - number of elements to delete
+ * @param items - optional items to insert
+ */
 export const splice = `toSpliced` in Array.prototype ? _spliceNew : _spliceOld;
 
-// Returns a copy of the array, where its 'sparse' property is kept (sparse = not all indices have a value)
+/**
+ * Returns a copy of a (potentially) sparse array preserving sparsity (skips holes).
+ * @typeparam T - element type
+ * @param arr - the source sparse array
+ */
 export function copySparse<T>(arr: readonly T[]): T[] {
   const clone: T[] = [];
   for (const key in arr) {
@@ -296,8 +456,13 @@ export function copySparse<T>(arr: readonly T[]): T[] {
   return clone;
 }
 
-// Returns a copy of the array with given function applied to each element, where its 'sparse' property is kept
-// (sparse = not all indices have a value)
+/**
+ * Returns a copy of a sparse array applying the given function to each present element, preserving holes.
+ * @typeparam T - source element type
+ * @typeparam T2 - result element type
+ * @param arr - the source sparse array
+ * @param f - mapping function
+ */
 export function mapSparse<T, T2>(
   arr: readonly T[],
   f: (value: T, index: number) => T2

package/dist/bun/entry.mts

@@ -1,9 +1,21 @@
-// Returns the first element of a 2-Tuple
+/**
+ * Returns the first element of a 2-tuple.
+ * @typeparam K - the first element type
+ * @typeparam V - the second element type
+ * @param entry - the tuple
+ * @returns the first element
+ */
 export function first<K, V>(entry: readonly [K, V]): K {
   return entry[0];
 }
 
-// Returns the second element of a 2-Tuple
+/**
+ * Returns the second element of a 2-tuple.
+ * @typeparam K - the first element type
+ * @typeparam V - the second element type
+ * @param entry - the tuple
+ * @returns the second element
+ */
 export function second<K, V>(entry: readonly [K, V]): V {
   return entry[1];
 }

package/dist/bun/index.mts

@@ -1,6 +1,16 @@
+/**
+ * @packageDocumentation
+ *
+ * The `@rimbu/base` package provides foundational immutable array utilities, tuple helpers,
+ * plain‑object type predicates and structured error types that power all other Rimbu collections.<br/>
+ * Use it directly when you need low‑level, performance‑aware primitives for persistent data
+ * structures without pulling in the higher‑level collection packages.<br/>
+ * See the Rimbu docs and API reference for more information.
+ */
 export * as Arr from './arr.mts';
 export * as Entry from './entry.mts';
 export * as RimbuError from './rimbu-error.mts';
 export * from './plain-object.mts';
 
+// Internal exports (may change without notice)
 export * from './internal.mts';