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 Since v2.0.0 Source

Constructors

make

Since v2.0.0

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

Since v4.0.0

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

Since v4.0.0

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.

Details

Finite fractional values of n are rounded down. NaN and non-positive values return an empty array.

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

Since v2.0.0

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

Since v2.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

Filters the MutableList in place, keeping only elements that satisfy the predicate. This operation modifies the list and rebuilds its internal structure for efficiency. The predicate receives each element's current index.

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

Since v2.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

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

Since v4.0.0

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.

Details

Finite fractional values of n are rounded down. NaN and non-positive values leave the list unchanged and return an empty array.

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

Since v4.0.0

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

Finite fractional values of n are rounded down. If n is NaN or non-positive, or the list is empty, the list is left unchanged. If the normalized count 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

Since v4.0.0

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