@rimbu/base 2.0.2 → 2.0.4

package/dist/cjs/entry.cjs

@@ -2,11 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.first = first;
 exports.second = second;
-// 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
+ */
 function first(entry) {
     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
+ */
 function second(entry) {
     return entry[1];
 }

package/dist/cjs/entry.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"entry.cjs","sourceRoot":"","sources":["../../_cjs_prepare/entry.cts"],"names":[],"mappings":";;AACA,sBAEC;AAGD,wBAEC;AARD,yCAAyC;AACzC,SAAgB,KAAK,CAAO,KAAsB;IAChD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,0CAA0C;AAC1C,SAAgB,MAAM,CAAO,KAAsB;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"entry.cjs","sourceRoot":"","sources":["../../_cjs_prepare/entry.cts"],"names":[],"mappings":";;AAOA,sBAEC;AASD,wBAEC;AApBD;;;;;;GAMG;AACH,SAAgB,KAAK,CAAO,KAAsB;IAChD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,MAAM,CAAO,KAAsB;IACjD,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/cjs/entry.d.cts

@@ -1,2 +1,16 @@
+/**
+ * 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 declare function first<K, V>(entry: readonly [K, V]): K;
+/**
+ * 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 declare function second<K, V>(entry: readonly [K, V]): V;

package/dist/cjs/index.cjs

@@ -2,9 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RimbuError = exports.Entry = exports.Arr = void 0;
 var tslib_1 = require("tslib");
+/**
+ * @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.
+ */
 exports.Arr = tslib_1.__importStar(require("./arr.cjs"));
 exports.Entry = tslib_1.__importStar(require("./entry.cjs"));
 exports.RimbuError = tslib_1.__importStar(require("./rimbu-error.cjs"));
 tslib_1.__exportStar(require("./plain-object.cjs"), exports);
+// Internal exports (may change without notice)
 tslib_1.__exportStar(require("./internal.cjs"), exports);
 //# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../_cjs_prepare/index.cts"],"names":[],"mappings":";;;;AAAA,yDAAiC;AACjC,6DAAqC;AACrC,wEAAgD;AAChD,6DAAmC;AAEnC,yDAA+B"}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../_cjs_prepare/index.cts"],"names":[],"mappings":";;;;AAAA;;;;;;;;GAQG;AACH,yDAAiC;AACjC,6DAAqC;AACrC,wEAAgD;AAChD,6DAAmC;AAEnC,+CAA+C;AAC/C,yDAA+B"}

package/dist/cjs/index.d.cts

@@ -1,3 +1,12 @@
+/**
+ * @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.cjs';
 export * as Entry from './entry.cjs';
 export * as RimbuError from './rimbu-error.cjs';

package/dist/cjs/rimbu-error.cjs

@@ -7,6 +7,9 @@ exports.throwInvalidStateError = throwInvalidStateError;
 exports.throwInvalidUsageError = throwInvalidUsageError;
 var tslib_1 = require("tslib");
 var common_1 = require("@rimbu/common");
+/**
+ * Error thrown when an operation assumes a collection is non-empty but it is empty.
+ */
 var EmptyCollectionAssumedNonEmptyError = /** @class */ (function (_super) {
     tslib_1.__extends(EmptyCollectionAssumedNonEmptyError, _super);
     function EmptyCollectionAssumedNonEmptyError() {
@@ -15,6 +18,9 @@ var EmptyCollectionAssumedNonEmptyError = /** @class */ (function (_super) {
     return EmptyCollectionAssumedNonEmptyError;
 }(common_1.ErrBase.CustomError));
 exports.EmptyCollectionAssumedNonEmptyError = EmptyCollectionAssumedNonEmptyError;
+/**
+ * Error thrown when a builder is modified while it is being iterated.
+ */
 var ModifiedBuilderWhileLoopingOverItError = /** @class */ (function (_super) {
     tslib_1.__extends(ModifiedBuilderWhileLoopingOverItError, _super);
     function ModifiedBuilderWhileLoopingOverItError() {
@@ -23,6 +29,9 @@ var ModifiedBuilderWhileLoopingOverItError = /** @class */ (function (_super) {
     return ModifiedBuilderWhileLoopingOverItError;
 }(common_1.ErrBase.CustomError));
 exports.ModifiedBuilderWhileLoopingOverItError = ModifiedBuilderWhileLoopingOverItError;
+/**
+ * Error indicating an unexpected internal state. Users are encouraged to file an issue.
+ */
 var InvalidStateError = /** @class */ (function (_super) {
     tslib_1.__extends(InvalidStateError, _super);
     function InvalidStateError() {
@@ -31,6 +40,9 @@ var InvalidStateError = /** @class */ (function (_super) {
     return InvalidStateError;
 }(common_1.ErrBase.CustomError));
 exports.InvalidStateError = InvalidStateError;
+/**
+ * Error indicating incorrect usage of the API.
+ */
 var InvalidUsageError = /** @class */ (function (_super) {
     tslib_1.__extends(InvalidUsageError, _super);
     function InvalidUsageError() {
@@ -39,15 +51,28 @@ var InvalidUsageError = /** @class */ (function (_super) {
     return InvalidUsageError;
 }(common_1.ErrBase.CustomError));
 exports.InvalidUsageError = InvalidUsageError;
+/**
+ * Throws an `EmptyCollectionAssumedNonEmptyError`.
+ */
 function throwEmptyCollectionAssumedNonEmptyError() {
     throw new EmptyCollectionAssumedNonEmptyError();
 }
+/**
+ * Throws a `ModifiedBuilderWhileLoopingOverItError`.
+ */
 function throwModifiedBuilderWhileLoopingOverItError() {
     throw new ModifiedBuilderWhileLoopingOverItError();
 }
+/**
+ * Throws an `InvalidStateError`.
+ */
 function throwInvalidStateError() {
     throw new InvalidStateError();
 }
+/**
+ * Throws an `InvalidUsageError` with the provided message.
+ * @param msg - context message describing the invalid usage
+ */
 function throwInvalidUsageError(msg) {
     throw new InvalidUsageError(msg);
 }

package/dist/cjs/rimbu-error.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"rimbu-error.cjs","sourceRoot":"","sources":["../../_cjs_prepare/rimbu-error.cts"],"names":[],"mappings":";;;AAwBA,4FAEC;AAED,kGAEC;AAED,wDAEC;AAED,wDAEC;;AAtCD,wCAAwC;AAExC;IAAyD,+DAAmB;IAC1E;QACE,OAAA,MAAK,YAAC,+CAA+C,CAAC,SAAC;IACzD,CAAC;IACH,0CAAC;AAAD,CAAC,AAJD,CAAyD,gBAAO,CAAC,WAAW,GAI3E;AAJY,kFAAmC;AAMhD;IAA4D,kEAAmB;IAC7E;QACE,OAAA,MAAK,YAAC,+DAA+D,CAAC,SAAC;IACzE,CAAC;IACH,6CAAC;AAAD,CAAC,AAJD,CAA4D,gBAAO,CAAC,WAAW,GAI9E;AAJY,wFAAsC;AAMnD;IAAuC,6CAAmB;IACxD;QACE,OAAA,MAAK,YACH,4EAA4E,CAC7E,SAAC;IACJ,CAAC;IACH,wBAAC;AAAD,CAAC,AAND,CAAuC,gBAAO,CAAC,WAAW,GAMzD;AANY,8CAAiB;AAQ9B;IAAuC,6CAAmB;IAA1D;;IAA4D,CAAC;IAAD,wBAAC;AAAD,CAAC,AAA7D,CAAuC,gBAAO,CAAC,WAAW,GAAG;AAAhD,8CAAiB;AAE9B,SAAgB,wCAAwC;IACtD,MAAM,IAAI,mCAAmC,EAAE,CAAC;AAClD,CAAC;AAED,SAAgB,2CAA2C;IACzD,MAAM,IAAI,sCAAsC,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,sBAAsB;IACpC,MAAM,IAAI,iBAAiB,EAAE,CAAC;AAChC,CAAC;AAED,SAAgB,sBAAsB,CAAC,GAAW;IAChD,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"rimbu-error.cjs","sourceRoot":"","sources":["../../_cjs_prepare/rimbu-error.cts"],"names":[],"mappings":";;;AAuCA,4FAEC;AAKD,kGAEC;AAKD,wDAEC;AAMD,wDAEC;;AA/DD,wCAAwC;AAExC;;GAEG;AACH;IAAyD,+DAAmB;IAC1E;QACE,OAAA,MAAK,YAAC,+CAA+C,CAAC,SAAC;IACzD,CAAC;IACH,0CAAC;AAAD,CAAC,AAJD,CAAyD,gBAAO,CAAC,WAAW,GAI3E;AAJY,kFAAmC;AAMhD;;GAEG;AACH;IAA4D,kEAAmB;IAC7E;QACE,OAAA,MAAK,YAAC,+DAA+D,CAAC,SAAC;IACzE,CAAC;IACH,6CAAC;AAAD,CAAC,AAJD,CAA4D,gBAAO,CAAC,WAAW,GAI9E;AAJY,wFAAsC;AAMnD;;GAEG;AACH;IAAuC,6CAAmB;IACxD;QACE,OAAA,MAAK,YACH,4EAA4E,CAC7E,SAAC;IACJ,CAAC;IACH,wBAAC;AAAD,CAAC,AAND,CAAuC,gBAAO,CAAC,WAAW,GAMzD;AANY,8CAAiB;AAQ9B;;GAEG;AACH;IAAuC,6CAAmB;IAA1D;;IAA4D,CAAC;IAAD,wBAAC;AAAD,CAAC,AAA7D,CAAuC,gBAAO,CAAC,WAAW,GAAG;AAAhD,8CAAiB;AAE9B;;GAEG;AACH,SAAgB,wCAAwC;IACtD,MAAM,IAAI,mCAAmC,EAAE,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAgB,2CAA2C;IACzD,MAAM,IAAI,sCAAsC,EAAE,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB;IACpC,MAAM,IAAI,iBAAiB,EAAE,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,GAAW;IAChD,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC"}

package/dist/cjs/rimbu-error.d.cts

@@ -1,16 +1,41 @@
 import { ErrBase } from '@rimbu/common';
+/**
+ * Error thrown when an operation assumes a collection is non-empty but it is empty.
+ */
 export declare class EmptyCollectionAssumedNonEmptyError extends ErrBase.CustomError {
     constructor();
 }
+/**
+ * Error thrown when a builder is modified while it is being iterated.
+ */
 export declare class ModifiedBuilderWhileLoopingOverItError extends ErrBase.CustomError {
     constructor();
 }
+/**
+ * Error indicating an unexpected internal state. Users are encouraged to file an issue.
+ */
 export declare class InvalidStateError extends ErrBase.CustomError {
     constructor();
 }
+/**
+ * Error indicating incorrect usage of the API.
+ */
 export declare class InvalidUsageError extends ErrBase.CustomError {
 }
+/**
+ * Throws an `EmptyCollectionAssumedNonEmptyError`.
+ */
 export declare function throwEmptyCollectionAssumedNonEmptyError(): never;
+/**
+ * Throws a `ModifiedBuilderWhileLoopingOverItError`.
+ */
 export declare function throwModifiedBuilderWhileLoopingOverItError(): never;
+/**
+ * Throws an `InvalidStateError`.
+ */
 export declare function throwInvalidStateError(): never;
+/**
+ * Throws an `InvalidUsageError` with the provided message.
+ * @param msg - context message describing the invalid usage
+ */
 export declare function throwInvalidUsageError(msg: string): never;

package/dist/cjs/token.cjs

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Token = void 0;
+/**
+ * Unique symbol used as a nominal token within the base package.
+ * Can be employed for branding or sentinel values.
+ */
 exports.Token = Symbol('Token');
 //# sourceMappingURL=token.cjs.map

package/dist/cjs/token.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"token.cjs","sourceRoot":"","sources":["../../_cjs_prepare/token.cts"],"names":[],"mappings":";;;AAAa,QAAA,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"token.cjs","sourceRoot":"","sources":["../../_cjs_prepare/token.cts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC"}

package/dist/cjs/token.d.cts

@@ -1,2 +1,9 @@
+/**
+ * Unique symbol used as a nominal token within the base package.
+ * Can be employed for branding or sentinel values.
+ */
 export declare const Token: unique symbol;
+/**
+ * Type alias representing the Token symbol.
+ */
 export type Token = typeof Token;

package/dist/esm/arr.d.mts

@@ -1,33 +1,217 @@
 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 declare function _appendNew<T>(array: readonly T[], value: T): 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 declare function _appendOld<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
+/**
+ * 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 declare const append: typeof _appendNew;
+/**
+ * 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 declare function concat<T>(first: readonly T[], second: readonly T[]): readonly T[];
+/**
+ * Internal helper to create a reversed copy using modern `toReversed` with optional slicing.
+ * @internal
+ */
 export declare function _reverseNew<T>(array: readonly T[], start?: number, end?: number): T[];
+/**
+ * Internal helper to create a reversed copy using manual iteration (legacy fallback).
+ * @internal
+ */
 export declare function _reverseOld<T>(array: readonly T[], start?: number, end?: number): T[];
+/**
+ * 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 declare const reverse: typeof _reverseNew;
+/**
+ * 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 declare function forEach<T>(array: readonly T[], f: (value: T, index: number, halt: () => void) => void, state?: TraverseState, reversed?: boolean): void;
+/**
+ * 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 declare function map<T, R>(array: readonly T[], f: (value: T, index: number) => R, indexOffset?: number): R[];
+/**
+ * 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 declare function reverseMap<T, R>(array: readonly T[], f: (value: T, index: number) => R, indexOffset?: number): R[];
+/**
+ * Internal helper to prepend a value using `toSpliced`.
+ * @internal
+ */
 export declare function _prependNew<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
+/**
+ * Internal helper to prepend a value using legacy cloning.
+ * @internal
+ */
 export declare function _prependOld<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
+/**
+ * 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 declare const prepend: typeof _prependNew;
+/**
+ * Internal helper to obtain the last element using modern `at`.
+ * @internal
+ */
 export declare function _lastNew<T>(arr: readonly T[]): T;
+/**
+ * Internal helper to obtain the last element using index arithmetic.
+ * @internal
+ */
 export declare function _lastOld<T>(arr: readonly T[]): T;
+/**
+ * Returns the last element of the array.
+ * @typeparam T - element type
+ * @param arr - the array
+ */
 export declare const last: typeof _lastNew;
+/**
+ * Internal helper implementing an immutable index update via `with`.
+ * @internal
+ */
 export declare function _updateNew<T>(arr: readonly T[], index: number, updater: Update<T>): readonly T[];
+/**
+ * Internal helper implementing an immutable index update via cloning.
+ * @internal
+ */
 export declare function _updateOld<T>(arr: readonly T[], index: number, updater: Update<T>): readonly T[];
+/**
+ * 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 declare const update: typeof _updateNew;
+/**
+ * Internal helper applying a modifier function via `with`.
+ * @internal
+ */
 export declare function _modNew<T>(arr: readonly T[], index: number, f: (value: T) => T): readonly T[];
+/**
+ * Internal helper applying a modifier function via cloning.
+ * @internal
+ */
 export declare function _modOld<T>(arr: readonly T[], index: number, f: (value: T) => T): readonly T[];
+/**
+ * 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 declare const mod: typeof _modNew;
+/**
+ * Internal helper for inserting a value using `toSpliced`.
+ * @internal
+ */
 export declare function _insertNew<T>(arr: readonly T[], index: number, value: T): T[];
+/**
+ * Internal helper for inserting a value using legacy `splice` on a clone.
+ * @internal
+ */
 export declare function _insertOld<T>(arr: readonly T[], index: number, value: T): T[];
+/**
+ * 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 declare const insert: typeof _insertNew;
+/**
+ * Returns a copy of the array without its first element.
+ * @typeparam T - element type
+ * @param arr - the source array
+ */
 export declare function tail<T>(arr: readonly T[]): T[];
+/**
+ * Returns a copy of the array without its last element.
+ * @typeparam T - element type
+ * @param arr - the source array
+ */
 export declare function init<T>(arr: readonly T[]): T[];
+/**
+ * Internal helper providing an immutable `splice` using `toSpliced`.
+ * @internal
+ */
 export declare function _spliceNew<T>(arr: readonly T[], start: number, deleteCount: number, ...items: T[]): T[];
+/**
+ * Internal helper providing an immutable `splice` via cloning.
+ * @internal
+ */
 export declare function _spliceOld<T>(arr: readonly T[], start: number, deleteCount: number, ...items: T[]): T[];
+/**
+ * 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 declare const splice: typeof _spliceNew;
+/**
+ * Returns a copy of a (potentially) sparse array preserving sparsity (skips holes).
+ * @typeparam T - element type
+ * @param arr - the source sparse array
+ */
 export declare function copySparse<T>(arr: readonly T[]): T[];
+/**
+ * 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 declare function mapSparse<T, T2>(arr: readonly T[], f: (value: T, index: number) => T2): T2[];