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.

20 exports Added in v2.0.0 Source

Constructors

make

Added in v2.0.0 Source

Creates an empty MutableList.

Signature

declare function make<A>(): MutableList<A>

Example

(Creating an empty mutable list)

import { MutableList } from "effect"

const list = MutableList.make<string>()

list.length // => 0
MutableList.append(list, "first")
MutableList.take(list) // => "first"
list.length // => 0

Converting

toArray

Added in v4.0.0 Source

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

takeAll for converting all elements to an array and clearing the list

Signature

declare function toArray<A>(self: MutableList<A>): Array<A>

toArrayN

Added in v4.0.0 Source

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

takeN for removing up to n values and returning them as an array

Signature

declare function toArrayN<A>(self: MutableList<A>, n: number): Array<A>

Models

MutableList interface

Added in v2.0.0 Source

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;
}

Example

(Creating and consuming a mutable list)

import { MutableList } from "effect"

const list: MutableList.MutableList<number> = MutableList.make()
MutableList.append(list, 1)
MutableList.append(list, 2)
MutableList.prepend(list, 0)

MutableList.takeAll(list) // => [0, 1, 2]
list.length // => 0

Mutations

append

Added in v2.0.0 Source

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

Example

(Appending elements)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.append(list, 1)
MutableList.append(list, 2)
MutableList.append(list, 3)

MutableList.toArray(list) // => [1, 2, 3]
list.length // => 3

appendAll

Added in v4.0.0 Source

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

Example

(Appending multiple elements)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.append(list, 1)
MutableList.append(list, 2)

MutableList.appendAll(list, [3, 4, 5]) // => 3
MutableList.toArray(list) // => [1, 2, 3, 4, 5]
list.length // => 5

appendAllUnsafe

Added in v4.0.0 Source

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): number

Example

(Transferring an array when appending)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.append(list, 1)
const items = [2, 3, 4]
MutableList.appendAllUnsafe(list, items, true) // => 3

MutableList.toArray(list) // => [1, 2, 3, 4]

clear

Added in v4.0.0 Source

Removes 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

Example

(Clearing a mutable list)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.appendAll(list, [1, 2, 3, 4, 5])

MutableList.clear(list)

MutableList.toArray(list) // => []
list.length // => 0
MutableList.take(list) === MutableList.Empty // => true

filter

Added in v4.0.0 Source

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

Example

(Filtering in place)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.appendAll(list, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])

MutableList.filter(list, (n) => n % 2 === 0)

MutableList.toArray(list) // => [2, 4, 6, 8, 10]

prepend

Added in v2.0.0 Source

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

Example

(Prepending elements)

import { MutableList } from "effect"

const list = MutableList.make<string>()
MutableList.append(list, "last")
MutableList.prepend(list, "third")
MutableList.prepend(list, "second")
MutableList.prepend(list, "first")

MutableList.toArray(list) // => ["first", "second", "third", "last"]

prependAll

Added in v4.0.0 Source

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

Example

(Prepending multiple elements)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.append(list, 4)
MutableList.append(list, 5)
MutableList.prependAll(list, [1, 2, 3])

MutableList.toArray(list) // => [1, 2, 3, 4, 5]

prependAllUnsafe

Added in v4.0.0 Source

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): void

Example

(Transferring an array when prepending)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.append(list, 4)
const items = [1, 2, 3]
MutableList.prependAllUnsafe(list, items, true)

MutableList.toArray(list) // => [1, 2, 3, 4]

remove

Added in v4.0.0 Source

Removes 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

Example

(Removing matching values)

import { MutableList } from "effect"

const list = MutableList.make<string>()
MutableList.appendAll(list, ["apple", "banana", "apple", "cherry", "apple"])

MutableList.remove(list, "apple")

MutableList.toArray(list) // => ["banana", "cherry"]

take

Added in v4.0.0 Source

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

Example

(Taking one element)

import { MutableList } from "effect"

const list = MutableList.make<string>()
MutableList.appendAll(list, ["first", "second", "third"])

MutableList.take(list) // => "first"
MutableList.toArray(list) // => ["second", "third"]
list.length // => 2

takeAll

Added in v4.0.0 Source

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>

Example

(Draining all elements)

import { MutableList } from "effect"

const list = MutableList.make<string>()
MutableList.appendAll(list, ["apple", "banana", "cherry"])

MutableList.takeAll(list) // => ["apple", "banana", "cherry"]
list.length // => 0

takeN

Added in v4.0.0 Source

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>

Example

(Taking batches)

import { MutableList } from "effect"

const list = MutableList.make<number>()
MutableList.appendAll(list, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])

MutableList.takeN(list, 3) // => [1, 2, 3]
MutableList.toArray(list) // => [4, 5, 6, 7, 8, 9, 10]
list.length // => 7

takeNVoid

Added in v4.0.0 Source

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

takeN for removing up to n values and returning them as an array
clear for removing every value from the list

Signature

declare function takeNVoid<A>(self: MutableList<A>, n: number): void

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

Example

(Checking for empty results)

import { MutableList } from "effect"

const list = MutableList.make<string>()

MutableList.take(list) === MutableList.Empty // => true

Empty type

Added in v4.0.0 Source

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

Example

(Handling empty results type-safely)

import { MutableList } from "effect"

const list = MutableList.make<number>()

const takeAndDouble = (queue: MutableList.MutableList<number>): number | null => {
  const item: number | MutableList.Empty = MutableList.take(queue)
  return item === MutableList.Empty ? null : item * 2
}

takeAndDouble(list) // => null
MutableList.append(list, 5)
takeAndDouble(list) // => 10