package @rimbu/common

The @rimbu/common package provides shared equality and comparison helpers, range and index utilities, lazy and async value helpers, traversal utilities, and rich type‑level helpers used throughout the Rimbu ecosystem. Use it when you need well‑tested primitives like Eq, Comp, Range, OptLazy, AsyncOptLazy, or advanced type utilities in your own code, or when building on top of other Rimbu packages. See the Common docs and API reference for more information.

Interfaces

Name	Description
Comp<K>	An object providing methods to compare two values of type K.
ToJSON<V,D>	Utility type to convert some object to a JSON serializable format.
TraverseState	An object used to track the state of a traversal, e.g. a forEach.

Namespaces

Name	Description
AsyncOptLazy	A potentially lazy and/or asynchronous value of type T.
CollectFun	A function used in collect methods to collect values from a collection. This is basically a single-pass map and filter.
Comp	An object providing methods to compare two values of type K.
Eq	A function returning true if given v1 and v2 should be considered equal.
ErrBase	undocumented
IndexRange	A flexible range specification for numeric indices. If a start or end is defined, a tuple can be used where the second item is a boolean indicating whether that end is inclusive or exclusive.

An IndexRange can have one of the following forms:

• { amount: number }
• { start: number }
• { start: number, amount: number }
• { start: number, end: number }
• { start: number, end: [number, boolean] }
• { start: [number, boolean] }
• { start: [number, boolean], amount: number }
• { start: [number, boolean], end: number }
• { start: [number, boolean], end: [number, boolean] }
• { end: number }
• { end: [number, boolean] } | | Range | A range definition for any type of (orderable) value. If a start or end is defined, a tuple can be used where the second item is a boolean indicating whether that end is inclusive (true) or exclusive (false). A Range of type T can have one of the following forms:
• { end: T }
• { end: [T, boolean] }
• { start: T }
• { start: T, end: T }
• { start: T, end: [T, boolean] }
• { start: [T, boolean] }
• { start: [T, boolean], end: T }
• { start: [T, boolean], end: [T, boolean] } |

Functions

Err

Throws an ErrBase.ForcedError error when called.

Definition

export declare function Err(): never;

example

const emptyMap = HashMap.empty<number, string>()
emptyMap.get(5, Err);
// throws: ErrBase.ForcedError(message: 'Err: Forced to throw error')

OptLazy

Returns the value contained in an OptLazy instance of type T.

Definition

export declare function OptLazy<T, A extends any[] = []>(optLazy: OptLazy<T, A>, ...args: A): T;

Type parameters

Name	Description
T	the value type
A	(default: []) types of the argument array that can be passed in the lazy case

Parameters

Name	Type	Description
optLazy	OptLazy<T, A>	the OptLazy value of type T
args	A	when needed, the extra arguments to pass to the lazy invocation

example

OptLazy(1)              // => 1
OptLazy(() => 1)        // => 1
OptLazy(() => () => 1)  // => () => 1

OptLazyOr

Returns the value contained in an OptLazyOr instance of type T, or the given otherValue if the lazy function returns it.

Definition

export declare function OptLazyOr<T, O>(optLazyOr: OptLazyOr<T, O>, otherValue: O): T | O;

Type parameters

Name	Description
T	the value type
O	the default value type

Parameters

Name	Type	Description
optLazyOr	OptLazyOr<T, O>	a value or a function returning a value or otherwise the received value
otherValue	O	the value to return if the optLazyOr does not return its own value

example

OptLazyOr(1, 'a')               // => 1
OptLazyOr(() => 1, 'a')         // => 1
OptLazyOr((none) => none, 'a')  // => 'a'

TraverseState

Returns a new TraverseState instance, using optionally given startIndex as a start index value.

Definition

export declare function TraverseState(startIndex?: number): TraverseState;

Parameters

Name	Type	Description
startIndex	number	(default: 0) the start index to use

Update

Returns the result of given update parameter, where it can either directly give a new value, or it is a function receiving the given value, and returns a new value.

Definition

export declare function Update<T>(value: T, update: Update<T>): T;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
value	T	the current value
update	Update<T>	an Update value, either a new value or a function receiving the old value and returning a new one.

example

Update(1, 2)          // => 2
Update(1, () => 10)   // => 10
Update(1, v => v + 1) // => 2