effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/MutableList.d.ts

@@ -5,26 +5,16 @@
  *
  * **Example** (Creating and consuming a mutable list)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
- * // Create a mutable list
  * const list: MutableList.MutableList<number> = MutableList.make()
- *
- * // Add elements
  * MutableList.append(list, 1)
  * MutableList.append(list, 2)
  * MutableList.prepend(list, 0)
  *
- * // Access properties
- * console.log(list.length) // 3
- * console.log(list.head?.array) // Contains elements from head bucket
- * console.log(list.tail?.array) // Contains elements from tail bucket
- *
- * // Take elements
- * console.log(MutableList.take(list)) // 0
- * console.log(MutableList.take(list)) // 1
- * console.log(MutableList.take(list)) // 2
+ * MutableList.takeAll(list) // => [0, 1, 2]
+ * list.length // => 0
  * ```
  *
  * @category models
@@ -39,36 +29,6 @@ export interface MutableList<in out A> {
  * The MutableList namespace contains type definitions and utilities for working
  * with mutable linked lists.
  *
- * **Example** (Typing queue processors)
- *
- * ```ts
- * import { MutableList } from "effect"
- *
- * // Type annotation using the namespace
- * const processQueue = (queue: MutableList.MutableList<string>) => {
- *   while (queue.length > 0) {
- *     const item = MutableList.take(queue)
- *     if (item !== MutableList.Empty) {
- *       console.log("Processing:", item)
- *     }
- *   }
- * }
- *
- * // Using the namespace for type definitions
- * const createProcessor = <T>(): {
- *   queue: MutableList.MutableList<T>
- *   add: (item: T) => void
- *   process: () => Array<T>
- * } => {
- *   const queue = MutableList.make<T>()
- *   return {
- *     queue,
- *     add: (item) => MutableList.append(queue, item),
- *     process: () => MutableList.takeAll(queue)
- *   }
- * }
- * ```
- *
  * @since 2.0.0
  */
 export declare namespace MutableList {
@@ -84,27 +44,19 @@ export declare namespace MutableList {
      *
      * **Example** (Inspecting buckets)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { MutableList } from "effect"
      *
      * const list = MutableList.make<number>()
      * MutableList.append(list, 1)
      * MutableList.append(list, 2)
      *
-     * // Access bucket information (for debugging or advanced usage)
-     * const inspectBucket = (
-     *   bucket: MutableList.MutableList.Bucket<number> | undefined
-     * ) => {
-     *   if (bucket) {
-     *     console.log("Bucket array:", bucket.array)
-     *     console.log("Bucket offset:", bucket.offset)
-     *     console.log("Bucket mutable:", bucket.mutable)
-     *     console.log("Has next bucket:", bucket.next !== undefined)
-     *   }
-     * }
+     * const bucket: MutableList.MutableList.Bucket<number> = list.head!
      *
-     * inspectBucket(list.head)
-     * inspectBucket(list.tail)
+     * bucket.array // => [1, 2]
+     * bucket.offset // => 0
+     * bucket.mutable // => true
+     * bucket.next === undefined // => true
      * ```
      *
      * @category models
@@ -128,32 +80,12 @@ export declare namespace MutableList {
  *
  * **Example** (Checking for empty results)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
  *
- * // Take from empty list returns Empty symbol
- * const result = MutableList.take(list)
- * console.log(result === MutableList.Empty) // true
- *
- * // Safe pattern for checking emptiness
- * const processNext = (queue: MutableList.MutableList<string>) => {
- *   const item = MutableList.take(queue)
- *   if (item === MutableList.Empty) {
- *     console.log("Queue is empty")
- *     return null
- *   }
- *   return item.toUpperCase()
- * }
- *
- * // Compare with other empty results
- * MutableList.append(list, "hello")
- * const next = MutableList.take(list)
- * console.log(next !== MutableList.Empty) // true, got "hello"
- *
- * const empty = MutableList.take(list)
- * console.log(empty === MutableList.Empty) // true, list is empty
+ * MutableList.take(list) === MutableList.Empty // => true
  * ```
  *
  * @category symbols
@@ -166,43 +98,19 @@ export declare const Empty: unique symbol;
  *
  * **Example** (Handling empty results type-safely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  *
- * // Type-safe handling of empty results
- * const takeAndDouble = (
- *   queue: MutableList.MutableList<number>
- * ): number | null => {
+ * const takeAndDouble = (queue: MutableList.MutableList<number>): number | null => {
  *   const item: number | MutableList.Empty = MutableList.take(queue)
- *
- *   if (item === MutableList.Empty) {
- *     return null
- *   }
- *
- *   // TypeScript knows item is number here
- *   return item * 2
+ *   return item === MutableList.Empty ? null : item * 2
  * }
  *
- * console.log(takeAndDouble(list)) // null (empty list)
- *
+ * takeAndDouble(list) // => null
  * MutableList.append(list, 5)
- * console.log(takeAndDouble(list)) // 10
- *
- * // Type guard function
- * const isEmpty = (
- *   result: number | MutableList.Empty
- * ): result is MutableList.Empty => {
- *   return result === MutableList.Empty
- * }
- *
- * const value = MutableList.take(list)
- * if (isEmpty(value)) {
- *   console.log("List is empty")
- * } else {
- *   console.log("Got value:", value)
- * }
+ * takeAndDouble(list) // => 10
  * ```
  *
  * @category symbols
@@ -214,22 +122,15 @@ export type Empty = typeof Empty;
  *
  * **Example** (Creating an empty mutable list)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
  *
- * // Add elements
+ * list.length // => 0
  * MutableList.append(list, "first")
- * MutableList.append(list, "second")
- * MutableList.prepend(list, "beginning")
- *
- * console.log(list.length) // 3
- *
- * // Take elements in FIFO order (from head)
- * console.log(MutableList.take(list)) // "beginning"
- * console.log(MutableList.take(list)) // "first"
- * console.log(MutableList.take(list)) // "second"
+ * MutableList.take(list) // => "first"
+ * list.length // => 0
  * ```
  *
  * @category constructors
@@ -242,27 +143,16 @@ export declare const make: <A>() => MutableList<A>;
  *
  * **Example** (Appending elements)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
- *
- * // Append elements one by one
  * MutableList.append(list, 1)
  * MutableList.append(list, 2)
  * MutableList.append(list, 3)
  *
- * console.log(list.length) // 3
- *
- * // Elements are taken from head (FIFO)
- * console.log(MutableList.take(list)) // 1
- * console.log(MutableList.take(list)) // 2
- * console.log(MutableList.take(list)) // 3
- *
- * // High-throughput usage
- * for (let i = 0; i < 10000; i++) {
- *   MutableList.append(list, i)
- * }
+ * MutableList.toArray(list) // => [1, 2, 3]
+ * list.length // => 3
  * ```
  *
  * @category mutations
@@ -275,27 +165,16 @@ export declare const append: <A>(self: MutableList<A>, message: A) => void;
  *
  * **Example** (Prepending elements)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
- *
- * // Prepend elements (they'll be at the front)
+ * MutableList.append(list, "last")
  * MutableList.prepend(list, "third")
  * MutableList.prepend(list, "second")
  * MutableList.prepend(list, "first")
  *
- * console.log(list.length) // 3
- *
- * // Elements taken from head (most recently prepended first)
- * console.log(MutableList.take(list)) // "first"
- * console.log(MutableList.take(list)) // "second"
- * console.log(MutableList.take(list)) // "third"
- *
- * // Use case: priority items or stack-like behavior
- * MutableList.append(list, "normal")
- * MutableList.prepend(list, "priority") // This will be taken first
- * console.log(MutableList.take(list)) // "priority"
+ * MutableList.toArray(list) // => ["first", "second", "third", "last"]
  * ```
  *
  * @category mutations
@@ -309,25 +188,15 @@ export declare const prepend: <A>(self: MutableList<A>, message: A) => void;
  *
  * **Example** (Prepending multiple elements)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.append(list, 4)
  * MutableList.append(list, 5)
- *
- * // Prepend multiple elements
  * MutableList.prependAll(list, [1, 2, 3])
  *
- * console.log(list.length) // 5
- *
- * // Elements are taken in order: [1, 2, 3, 4, 5]
- * console.log(MutableList.takeAll(list)) // [1, 2, 3, 4, 5]
- *
- * // Works with any iterable
- * const newList = MutableList.make<string>()
- * MutableList.prependAll(newList, "hello") // Prepends each character
- * console.log(MutableList.takeAll(newList)) // ["h", "e", "l", "l", "o"]
+ * MutableList.toArray(list) // => [1, 2, 3, 4, 5]
  * ```
  *
  * @category mutations
@@ -341,32 +210,24 @@ export declare const prependAll: <A>(self: MutableList<A>, messages: Iterable<A>
  * **When to use**
  *
  * Use when prepending a trusted array directly is worth the optimized path and
- * you control whether the input may be reused.
+ * you can transfer ownership of the input when enabling mutation.
  *
  * **Gotchas**
  *
- * When mutable=true, the input array may be modified internally. Only use
- * mutable=true when you control the array lifecycle.
+ * When mutable=true, ownership of the input array transfers to the list. Do not
+ * read or modify the array afterward.
  *
- * **Example** (Prepending arrays with optional mutation)
+ * **Example** (Transferring an array when prepending)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.append(list, 4)
- *
- * // Safe usage (default mutable=false)
  * const items = [1, 2, 3]
- * MutableList.prependAllUnsafe(list, items)
- * console.log(items) // [1, 2, 3] - unchanged
- *
- * // Unsafe but efficient usage (mutable=true)
- * const mutableItems = [10, 20, 30]
- * MutableList.prependAllUnsafe(list, mutableItems, true)
- * // mutableItems may be modified internally for efficiency
+ * MutableList.prependAllUnsafe(list, items, true)
  *
- * console.log(MutableList.takeAll(list)) // [10, 20, 30, 1, 2, 3, 4]
+ * MutableList.toArray(list) // => [1, 2, 3, 4]
  * ```
  *
  * @category mutations
@@ -379,33 +240,16 @@ export declare const prependAllUnsafe: <A>(self: MutableList<A>, messages: Reado
  *
  * **Example** (Appending multiple elements)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.append(list, 1)
  * MutableList.append(list, 2)
  *
- * // Append multiple elements
- * const added = MutableList.appendAll(list, [3, 4, 5])
- * console.log(added) // 3
- * console.log(list.length) // 5
- *
- * // Elements maintain order: [1, 2, 3, 4, 5]
- * console.log(MutableList.takeAll(list)) // [1, 2, 3, 4, 5]
- *
- * // Works with any iterable
- * const newList = MutableList.make<string>()
- * MutableList.appendAll(newList, new Set(["a", "b", "c"]))
- * console.log(MutableList.takeAll(newList)) // ["a", "b", "c"]
- *
- * // Useful for bulk loading
- * const bulkList = MutableList.make<number>()
- * const count = MutableList.appendAll(
- *   bulkList,
- *   Array.from({ length: 1000 }, (_, i) => i)
- * )
- * console.log(count) // 1000
+ * MutableList.appendAll(list, [3, 4, 5]) // => 3
+ * MutableList.toArray(list) // => [1, 2, 3, 4, 5]
+ * list.length // => 5
  * ```
  *
  * @category mutations
@@ -420,37 +264,24 @@ export declare const appendAll: <A>(self: MutableList<A>, messages: Iterable<A>)
  * **When to use**
  *
  * Use when appending a trusted array directly is worth the optimized path and
- * you control whether the input may be reused.
+ * you can transfer ownership of the input when enabling mutation.
  *
  * **Gotchas**
  *
- * When mutable=true, the input array may be modified internally. Only use
- * mutable=true when you control the array lifecycle.
+ * When mutable=true, ownership of the input array transfers to the list. Do not
+ * read or modify the array afterward.
  *
- * **Example** (Appending arrays with optional mutation)
+ * **Example** (Transferring an array when appending)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.append(list, 1)
- *
- * // Safe usage (default mutable=false)
  * const items = [2, 3, 4]
- * const added = MutableList.appendAllUnsafe(list, items)
- * console.log(added) // 3
- * console.log(items) // [2, 3, 4] - unchanged
- *
- * // Unsafe but efficient usage (mutable=true)
- * const mutableItems = [5, 6, 7]
- * MutableList.appendAllUnsafe(list, mutableItems, true)
- * // mutableItems may be modified internally for efficiency
+ * MutableList.appendAllUnsafe(list, items, true) // => 3
  *
- * console.log(MutableList.takeAll(list)) // [1, 2, 3, 4, 5, 6, 7]
- *
- * // High-performance bulk operations
- * const bigArray = new Array(10000).fill(0).map((_, i) => i)
- * MutableList.appendAllUnsafe(list, bigArray, true) // Very efficient
+ * MutableList.toArray(list) // => [1, 2, 3, 4]
  * ```
  *
  * @category mutations
@@ -463,29 +294,17 @@ export declare const appendAllUnsafe: <A>(self: MutableList<A>, messages: Readon
  *
  * **Example** (Clearing a mutable list)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.appendAll(list, [1, 2, 3, 4, 5])
  *
- * console.log(list.length) // 5
- *
- * // Clear all elements
  * MutableList.clear(list)
  *
- * console.log(list.length) // 0
- * console.log(MutableList.take(list)) // Empty
- *
- * // Can still use the list after clearing
- * MutableList.append(list, 42)
- * console.log(list.length) // 1
- *
- * // Useful for resetting queues or buffers
- * function resetBuffer<T>(buffer: MutableList.MutableList<T>) {
- *   MutableList.clear(buffer)
- *   console.log("Buffer cleared and ready for reuse")
- * }
+ * MutableList.toArray(list) // => []
+ * list.length // => 0
+ * MutableList.take(list) === MutableList.Empty // => true
  * ```
  *
  * @category mutations
@@ -499,39 +318,18 @@ export declare const clear: <A>(self: MutableList<A>) => void;
  *
  * **Example** (Taking batches)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.appendAll(list, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  *
- * console.log(list.length) // 10
- *
- * // Take first 3 elements
- * const first3 = MutableList.takeN(list, 3)
- * console.log(first3) // [1, 2, 3]
- * console.log(list.length) // 7
- *
- * // Take more than available
- * const remaining = MutableList.takeN(list, 20)
- * console.log(remaining) // [4, 5, 6, 7, 8, 9, 10]
- * console.log(list.length) // 0
- *
- * // Take from empty list
- * const empty = MutableList.takeN(list, 5)
- * console.log(empty) // []
- *
- * // Batch processing pattern
- * const queue = MutableList.make<string>()
- * MutableList.appendAll(queue, ["task1", "task2", "task3", "task4", "task5"])
- *
- * while (queue.length > 0) {
- *   const batch = MutableList.takeN(queue, 2) // Process 2 at a time
- *   console.log("Processing batch:", batch)
- * }
+ * MutableList.takeN(list, 3) // => [1, 2, 3]
+ * MutableList.toArray(list) // => [4, 5, 6, 7, 8, 9, 10]
+ * list.length // => 7
  * ```
  *
- * @category elements
+ * @category mutations
  * @since 4.0.0
  */
 export declare const takeN: <A>(self: MutableList<A>, n: number) => Array<A>;
@@ -553,7 +351,7 @@ export declare const takeN: <A>(self: MutableList<A>, n: number) => Array<A>;
  * @see {@link takeN} for removing up to `n` values and returning them as an array
  * @see {@link clear} for removing every value from the list
  *
- * @category elements
+ * @category mutations
  * @since 4.0.0
  */
 export declare const takeNVoid: <A>(self: MutableList<A>, n: number) => void;
@@ -563,40 +361,17 @@ export declare const takeNVoid: <A>(self: MutableList<A>, n: number) => void;
  *
  * **Example** (Draining all elements)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
  * MutableList.appendAll(list, ["apple", "banana", "cherry"])
  *
- * console.log(list.length) // 3
- *
- * // Take all elements
- * const allItems = MutableList.takeAll(list)
- * console.log(allItems) // ["apple", "banana", "cherry"]
- * console.log(list.length) // 0
- *
- * // Useful for converting to array and clearing
- * const queue = MutableList.make<number>()
- * MutableList.appendAll(queue, [1, 2, 3, 4, 5])
- *
- * const snapshot = MutableList.takeAll(queue)
- * console.log("Queue contents:", snapshot)
- * console.log("Queue is now empty:", queue.length === 0)
- *
- * // Drain pattern for processing
- * function drainAndProcess<T>(
- *   list: MutableList.MutableList<T>,
- *   processor: (items: Array<T>) => void
- * ) {
- *   if (list.length > 0) {
- *     const items = MutableList.takeAll(list)
- *     processor(items)
- *   }
- * }
+ * MutableList.takeAll(list) // => ["apple", "banana", "cherry"]
+ * list.length // => 0
  * ```
  *
- * @category elements
+ * @category mutations
  * @since 4.0.0
  */
 export declare const takeAll: <A>(self: MutableList<A>) => Array<A>;
@@ -607,46 +382,18 @@ export declare const takeAll: <A>(self: MutableList<A>) => Array<A>;
  *
  * **Example** (Taking one element)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
  * MutableList.appendAll(list, ["first", "second", "third"])
  *
- * // Take elements one by one
- * console.log(MutableList.take(list)) // "first"
- * console.log(list.length) // 2
- *
- * console.log(MutableList.take(list)) // "second"
- * console.log(MutableList.take(list)) // "third"
- * console.log(list.length) // 0
- *
- * // Take from empty list
- * console.log(MutableList.take(list)) // Empty symbol
- *
- * // Check for empty using the Empty symbol
- * const result = MutableList.take(list)
- * if (result === MutableList.Empty) {
- *   console.log("List is empty")
- * } else {
- *   console.log("Got element:", result)
- * }
- *
- * // Consumer pattern
- * function processNext<T>(
- *   queue: MutableList.MutableList<T>,
- *   processor: (item: T) => void
- * ): boolean {
- *   const item = MutableList.take(queue)
- *   if (item !== MutableList.Empty) {
- *     processor(item)
- *     return true
- *   }
- *   return false
- * }
+ * MutableList.take(list) // => "first"
+ * MutableList.toArray(list) // => ["second", "third"]
+ * list.length // => 2
  * ```
  *
- * @category elements
+ * @category mutations
  * @since 4.0.0
  */
 export declare const take: <A>(self: MutableList<A>) => Empty | A;
@@ -661,7 +408,7 @@ export declare const take: <A>(self: MutableList<A>) => Empty | A;
  *
  * @see {@link takeN} for removing up to `n` values and returning them as an array
  *
- * @category elements
+ * @category converting
  * @since 4.0.0
  */
 export declare const toArrayN: <A>(self: MutableList<A>, n: number) => Array<A>;
@@ -676,7 +423,7 @@ export declare const toArrayN: <A>(self: MutableList<A>, n: number) => Array<A>;
  *
  * @see {@link takeAll} for converting all elements to an array and clearing the list
  *
- * @category elements
+ * @category converting
  * @since 4.0.0
  */
 export declare const toArray: <A>(self: MutableList<A>) => Array<A>;
@@ -686,39 +433,15 @@ export declare const toArray: <A>(self: MutableList<A>) => Array<A>;
  *
  * **Example** (Filtering in place)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<number>()
  * MutableList.appendAll(list, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  *
- * console.log(list.length) // 10
- *
- * // Keep only even numbers
  * MutableList.filter(list, (n) => n % 2 === 0)
  *
- * console.log(MutableList.takeAll(list)) // [2, 4, 6, 8, 10]
- *
- * // Filter with index
- * const indexed = MutableList.make<string>()
- * MutableList.appendAll(indexed, ["a", "b", "c", "d", "e"])
- *
- * // Keep elements at even indices
- * MutableList.filter(indexed, (value, index) => index % 2 === 0)
- * console.log(MutableList.takeAll(indexed)) // ["a", "c", "e"]
- *
- * // Real-world example: filtering a log queue
- * const logs = MutableList.make<{ level: string; message: string }>()
- * MutableList.appendAll(logs, [
- *   { level: "INFO", message: "App started" },
- *   { level: "ERROR", message: "Connection failed" },
- *   { level: "DEBUG", message: "Cache hit" },
- *   { level: "ERROR", message: "Timeout" }
- * ])
- *
- * // Keep only errors
- * MutableList.filter(logs, (log) => log.level === "ERROR")
- * console.log(MutableList.takeAll(logs).map((log) => log.message)) // ["Connection failed", "Timeout"]
+ * MutableList.toArray(list) // => [2, 4, 6, 8, 10]
  * ```
  *
  * @category mutations
@@ -745,37 +468,15 @@ export declare const filter: <A>(self: MutableList<A>, f: (value: A, i: number)
  *
  * **Example** (Removing matching values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableList } from "effect"
  *
  * const list = MutableList.make<string>()
  * MutableList.appendAll(list, ["apple", "banana", "apple", "cherry", "apple"])
  *
- * console.log(list.length) // 5
- *
- * // Remove all occurrences of "apple"
  * MutableList.remove(list, "apple")
  *
- * console.log(MutableList.takeAll(list)) // ["banana", "cherry"]
- *
- * // Remove non-existent value (no effect)
- * const colors = MutableList.make<string>()
- * MutableList.appendAll(colors, ["red", "blue"])
- * MutableList.remove(colors, "green")
- * console.log(MutableList.takeAll(colors)) // ["red", "blue"]
- *
- * // Real-world example: removing completed tasks
- * const tasks = MutableList.make<{ id: number; status: string }>()
- * MutableList.appendAll(tasks, [
- *   { id: 1, status: "pending" },
- *   { id: 2, status: "completed" },
- *   { id: 3, status: "pending" },
- *   { id: 4, status: "completed" }
- * ])
- *
- * // Remove completed tasks by filtering status
- * MutableList.filter(tasks, (task) => task.status !== "completed")
- * console.log(MutableList.takeAll(tasks).map((task) => task.id)) // [1, 3]
+ * MutableList.toArray(list) // => ["banana", "cherry"]
  * ```
  *
  * @category mutations