MutableList
Mutable lists for collecting ordered values and draining them from the front. A MutableList<A> can append values to the end, prepend values to the beginning, take one or more values from the front, inspect its contents as an array, filter values, remove values, and clear itself. All operations update the same list object in place and keep its length field current. Taking from an empty list returns the Empty symbol.
Constructors
Converting
Copies all current elements of the MutableList into a new array without modifying the list.
When to use
Use when you need a snapshot of all current elements while keeping the list unchanged.
See
takeAllfor converting all elements to an array and clearing the list
Signature
declare function toArray<A>(self: MutableList<A>): Array<A>;Copies up to n elements from the beginning of the MutableList into a new array without modifying the list.
When to use
Use when you need to inspect or snapshot a bounded prefix of the list without consuming it.
See
takeNfor removing up tonvalues and returning them as an array
Signature
declare function toArrayN<A>(self: MutableList<A>, n: number): Array<A>;Models
MutableList interface
A mutable linked list data structure optimized for high-throughput operations. MutableList provides efficient append/prepend operations and is ideal for producer-consumer patterns, queues, and streaming scenarios.
Signature
interface MutableList<in out A> {
head: Bucket<A> | undefined;
length: number;
tail: Bucket<A> | undefined;
}Mutations
Appends an element to the end of the MutableList. This operation is optimized for high-frequency usage.
Signature
declare function append<A>(self: MutableList<A>, message: A): void;Appends all elements from an iterable to the end of the MutableList. Returns the number of elements added.
Signature
declare function appendAll<A>(self: MutableList<A>, messages: Iterable<A>): number;appendAllUnsafe
Appends all elements from a ReadonlyArray to the end of the MutableList. This is an optimized version that can reuse the array when mutable=true. Returns the number of elements added.
When to use
Use when appending a trusted array directly is worth the optimized path and you can transfer ownership of the input when enabling mutation.
Gotchas
When mutable=true, ownership of the input array transfers to the list. Do not read or modify the array afterward.
Signature
declare function appendAllUnsafe<A>(self: MutableList<A>, messages: readonly Array<A>, mutable: boolean): numberRemoves all elements from the MutableList, resetting it to an empty state. This operation is highly optimized and releases all internal memory.
Signature
declare function clear<A>(self: MutableList<A>): void;Filters the MutableList in place, keeping only elements that satisfy the predicate. This operation modifies the list and rebuilds its internal structure for efficiency.
Signature
declare function filter<A>(self: MutableList<A>, f: (value: A, i: number) => boolean): void;Prepends an element to the beginning of the MutableList. This operation is optimized for high-frequency usage.
Signature
declare function prepend<A>(self: MutableList<A>, message: A): void;prependAll
Prepends all elements from an iterable to the beginning of the MutableList. The elements are added in order, so the first element in the iterable becomes the new head of the list.
Signature
declare function prependAll<A>(self: MutableList<A>, messages: Iterable<A>): void;prependAllUnsafe
Prepends all elements from a ReadonlyArray to the beginning of the MutableList. This is an optimized version that can reuse the array when mutable=true.
When to use
Use when prepending a trusted array directly is worth the optimized path and you can transfer ownership of the input when enabling mutation.
Gotchas
When mutable=true, ownership of the input array transfers to the list. Do not read or modify the array afterward.
Signature
declare function prependAllUnsafe<A>(self: MutableList<A>, messages: readonly Array<A>, mutable: boolean): voidRemoves all occurrences of a value from the MutableList using JavaScript strict equality semantics.
When to use
Use when in-place removal should use JavaScript identity/strict equality rather than Effect structural equality.
Details
The list is modified in place.
Gotchas
Values are compared with !==, so this does not use Effect structural equality.
Signature
declare function remove<A>(self: MutableList<A>, value: A): void;Takes a single element from the beginning of the MutableList. Returns the element if available, or the Empty symbol if the list is empty. The taken element is removed from the list.
Signature
declare function take<A>(self: MutableList<A>): typeof Empty | A;Takes all elements from the MutableList and returns them as an array. The list becomes empty after this operation. This is equivalent to takeN(list, list.length).
Signature
declare function takeAll<A>(self: MutableList<A>): Array<A>;Takes up to N elements from the beginning of the MutableList and returns them as an array. The taken elements are removed from the list. This operation is optimized for performance and includes zero-copy optimizations when possible.
Signature
declare function takeN<A>(self: MutableList<A>, n: number): Array<A>;Removes up to n elements from the beginning of the MutableList without returning them.
When to use
Use to discard a bounded number of values from the head of a MutableList when the removed values are not needed.
Details
If n is less than or equal to zero, or the list is empty, the list is left unchanged. If n is greater than or equal to the current length, the list is cleared.
See
Signature
declare function takeNVoid<A>(self: MutableList<A>, n: number): void;Other
MutableList
The MutableList namespace contains type definitions and utilities for working with mutable linked lists.
Symbols
Defines the unique symbol used to represent an empty result when taking elements from a MutableList. This symbol is returned by take when the list is empty, allowing for safe type checking.
When to use
Use to detect that take returned no element before handling the result as a list item.
Signature
declare const Empty: unique symbol;The type of the Empty symbol, used for type checking when taking elements from a MutableList. This provides compile-time safety when checking for empty results.
Signature
type Empty = typeof Empty;
Creates an empty MutableList.