ts-data-forge 9.0.0 → 10.0.0

package/dist/collections/queue.mjs

@@ -39,190 +39,118 @@ import '../number/enum/uint8.mjs';
 import '../number/num.mjs';
 import '../number/refined-number-utils.mjs';
 
-/**
- * Class implementation for a queue with FIFO (First-In, First-Out) behavior
- * using a circular buffer. This implementation provides O(1) enqueue and
- * dequeue operations by using a fixed-size buffer with head and tail pointers
- * that wrap around when they reach the buffer boundary.
- *
- * The circular buffer automatically resizes when it becomes full, ensuring that
- * the queue can grow to accommodate any number of elements while maintaining
- * efficient operations.
- *
- * @template T The type of elements in the queue.
- * @implements Queue
- */
 class QueueClass {
-    /** @internal Initial capacity for new queues. */
-    static #INITIAL_CAPACITY = 8;
-    /** @internal Circular buffer to store queue elements. */
-    #mut_buffer;
-    /** @internal Index of the first element (front of queue). */
-    #mut_head;
-    /** @internal Index where the next element will be added (back of queue). */
-    #mut_tail;
-    /** @internal Current number of elements in the queue. */
-    #mut_size;
-    /** @internal Current capacity of the buffer. */
-    #mut_capacity;
-    /**
-     * Constructs a new QueueClass instance.
-     *
-     * @param initialValues Optional initial values to populate the queue.
-     */
-    constructor(initialValues = []) {
-        const initialCapacity = asUint32(Math.max(QueueClass.#INITIAL_CAPACITY, initialValues.length * 2));
-        this.#mut_buffer = Array.from({ length: initialCapacity }, () => undefined);
-        this.#mut_head = 0;
-        this.#mut_tail = 0;
-        this.#mut_size = 0;
-        this.#mut_capacity = initialCapacity;
-        // Add initial values
-        for (const value of initialValues) {
-            this.enqueue(value);
-        }
+  /** @internal Initial capacity for new queues. */
+  static #INITIAL_CAPACITY = 8;
+  /** @internal Circular buffer to store queue elements. */
+  #mut_buffer;
+  /** @internal Index of the first element (front of queue). */
+  #mut_head;
+  /** @internal Index where the next element will be added (back of queue). */
+  #mut_tail;
+  /** @internal Current number of elements in the queue. */
+  #mut_size;
+  /** @internal Current capacity of the buffer. */
+  #mut_capacity;
+  /**
+   * Constructs a new QueueClass instance.
+   *
+   * @param initialValues Optional initial values to populate the queue.
+   */
+  constructor(initialValues = []) {
+    const initialCapacity = asUint32(
+      Math.max(QueueClass.#INITIAL_CAPACITY, initialValues.length * 2)
+    );
+    this.#mut_buffer = Array.from(
+      { length: initialCapacity },
+      () => void 0
+    );
+    this.#mut_head = 0;
+    this.#mut_tail = 0;
+    this.#mut_size = 0;
+    this.#mut_capacity = initialCapacity;
+    for (const value of initialValues) {
+      this.enqueue(value);
     }
-    /**
-     * @internal
-     * Resizes the circular buffer when it becomes full.
-     * Doubles the capacity and reorganizes elements to maintain queue order.
-     */
-    #resize() {
-        const newCapacity = asUint32(this.#mut_capacity * 2);
-        const newBuffer = Array.from({ length: newCapacity }, () => undefined);
-        // Copy elements in order from head to tail
-        for (const i of range(asSafeUint(this.#mut_size))) {
-            const sourceIndex = (this.#mut_head + i) % this.#mut_capacity;
-            newBuffer[i] = this.#mut_buffer[sourceIndex];
-        }
-        this.#mut_buffer = newBuffer;
-        this.#mut_head = 0;
-        this.#mut_tail = this.#mut_size;
-        this.#mut_capacity = newCapacity;
+  }
+  /**
+   * @internal
+   * Resizes the circular buffer when it becomes full.
+   * Doubles the capacity and reorganizes elements to maintain queue order.
+   */
+  #resize() {
+    const newCapacity = asUint32(this.#mut_capacity * 2);
+    const newBuffer = Array.from(
+      { length: newCapacity },
+      () => void 0
+    );
+    for (const i of range(asSafeUint(this.#mut_size))) {
+      const sourceIndex = (this.#mut_head + i) % this.#mut_capacity;
+      newBuffer[i] = this.#mut_buffer[sourceIndex];
     }
-    /** @inheritdoc */
-    get isEmpty() {
-        return this.#mut_size === 0;
+    this.#mut_buffer = newBuffer;
+    this.#mut_head = 0;
+    this.#mut_tail = this.#mut_size;
+    this.#mut_capacity = newCapacity;
+  }
+  /** @inheritdoc */
+  get isEmpty() {
+    return this.#mut_size === 0;
+  }
+  /** @inheritdoc */
+  get size() {
+    return asUint32(this.#mut_size);
+  }
+  /**
+   * Removes and returns the element at the front of the queue (FIFO).
+   *
+   * This operation removes the element that was added earliest (first-in) and
+   * returns it. If the queue is empty, returns `Optional.none`. The operation
+   * is guaranteed to be O(1) and does not require any array shifting or
+   * copying.
+   *
+   * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
+   * O(1) - no additional memory allocation
+   *
+   * @returns An Optional containing the removed element, or `Optional.none` if
+   *   the queue is empty.
+   */
+  dequeue() {
+    if (this.isEmpty) {
+      return none;
     }
-    /** @inheritdoc */
-    get size() {
-        return asUint32(this.#mut_size);
-    }
-    /**
-     * Removes and returns the element at the front of the queue (FIFO).
-     *
-     * This operation removes the element that was added earliest (first-in) and
-     * returns it. If the queue is empty, returns `Optional.none`. The operation
-     * is guaranteed to be O(1) and does not require any array shifting or
-     * copying.
-     *
-     * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
-     * O(1) - no additional memory allocation
-     *
-     * @returns An Optional containing the removed element, or `Optional.none` if
-     *   the queue is empty.
-     */
-    dequeue() {
-        if (this.isEmpty) {
-            return none;
-        }
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const element = this.#mut_buffer[this.#mut_head];
-        this.#mut_buffer[this.#mut_head] = undefined; // Clear reference for garbage collection
-        this.#mut_head = (this.#mut_head + 1) % this.#mut_capacity;
-        this.#mut_size -= 1;
-        return some(element);
-    }
-    /**
-     * Adds an element to the back of the queue (FIFO).
-     *
-     * This operation adds the element to the end of the queue, where it will be
-     * the last to be dequeued (first-in, first-out ordering). The operation is
-     * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
-     * when the buffer needs resizing.
-     *
-     * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
-     * needed **Space Complexity:** O(1) - constant additional memory per element
-     *
-     * **Buffer Resizing:** When the internal buffer becomes full, it
-     * automatically doubles in size and reorganizes elements to maintain the
-     * circular buffer structure.
-     *
-     * @param value The element to add to the back of the queue.
-     */
-    enqueue(value) {
-        // Resize if buffer is full
-        if (this.#mut_size === this.#mut_capacity) {
-            this.#resize();
-        }
-        this.#mut_buffer[this.#mut_tail] = value;
-        this.#mut_tail = (this.#mut_tail + 1) % this.#mut_capacity;
-        this.#mut_size += 1;
+    const element = this.#mut_buffer[this.#mut_head];
+    this.#mut_buffer[this.#mut_head] = void 0;
+    this.#mut_head = (this.#mut_head + 1) % this.#mut_capacity;
+    this.#mut_size -= 1;
+    return some(element);
+  }
+  /**
+   * Adds an element to the back of the queue (FIFO).
+   *
+   * This operation adds the element to the end of the queue, where it will be
+   * the last to be dequeued (first-in, first-out ordering). The operation is
+   * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
+   * when the buffer needs resizing.
+   *
+   * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
+   * needed **Space Complexity:** O(1) - constant additional memory per element
+   *
+   * **Buffer Resizing:** When the internal buffer becomes full, it
+   * automatically doubles in size and reorganizes elements to maintain the
+   * circular buffer structure.
+   *
+   * @param value The element to add to the back of the queue.
+   */
+  enqueue(value) {
+    if (this.#mut_size === this.#mut_capacity) {
+      this.#resize();
     }
+    this.#mut_buffer[this.#mut_tail] = value;
+    this.#mut_tail = (this.#mut_tail + 1) % this.#mut_capacity;
+    this.#mut_size += 1;
+  }
 }
-/**
- * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a
- * high-performance circular buffer.
- *
- * This factory function creates an optimized queue implementation that
- * maintains excellent performance characteristics for both enqueue and dequeue
- * operations. The underlying circular buffer automatically resizes to
- * accommodate growing workloads while providing predictable O(1) operations.
- *
- * **Implementation Features:**
- *
- * - **O(1) enqueue operations** (amortized - occasionally O(n) when resizing)
- * - **O(1) dequeue operations** (always)
- * - **Automatic buffer resizing** - starts at 8 elements, doubles when full
- * - **Memory efficient** - garbage collects removed elements immediately
- * - **Circular buffer design** - eliminates need for array shifting operations
- *
- * **Performance Benefits:**
- *
- * - No array copying during normal operations
- * - Minimal memory allocation overhead
- * - Predictable performance under high load
- * - Efficient memory usage with automatic cleanup
- *
- * @example
- *
- * ```ts
- * const queue = createQueue<number>();
- *
- * assert.isTrue(queue.isEmpty);
- *
- * assert.isTrue(queue.size === 0);
- *
- * queue.enqueue(1);
- *
- * queue.enqueue(2);
- *
- * assert.isFalse(queue.isEmpty);
- *
- * assert.isTrue(queue.size === 2);
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));
- *
- * assert.deepStrictEqual(queue.dequeue(), Optional.none);
- *
- * const seededQueue = createQueue(['first', 'second']);
- *
- * assert.isTrue(seededQueue.size === 2);
- *
- * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
- *
- * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
- * ```
- *
- * @template T The type of elements stored in the queue.
- * @param initialValues Optional array of initial elements to populate the
- *   queue. Elements will be dequeued in the same order they appear in the
- *   array. If provided, the initial buffer capacity will be at least twice the
- *   array length.
- * @returns A new Queue instance optimized for high-performance FIFO operations.
- */
 const createQueue = (initialValues) => new QueueClass(initialValues);
 
 export { createQueue };

package/dist/collections/queue.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"queue.mjs","sources":["../../src/collections/queue.mts"],"sourcesContent":[null],"names":["Optional.none","Optional.some"],"mappings":"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"}
+{"version":3,"file":"queue.mjs","sources":["../../src/collections/queue.mts"],"sourcesContent":["import { Optional } from '../functional/index.mjs';\nimport { range } from '../iterator/index.mjs';\nimport { asSafeUint, asUint32 } from '../number/index.mjs';\nimport { type SizeType } from '../types.mjs';\n\n/**\n * Interface for a high-performance queue with FIFO (First-In, First-Out)\n * behavior.\n *\n * This interface defines a mutable queue data structure where elements are\n * added to the back and removed from the front, maintaining the order in which\n * they were added. The implementation uses a circular buffer for optimal\n * performance, providing O(1) operations for both enqueue and dequeue\n * operations.\n *\n * **FIFO Behavior:**\n *\n * - **enqueue**: Adds elements to the back of the queue\n * - **dequeue**: Removes and returns elements from the front of the queue\n * - Elements are processed in the exact order they were added\n *\n * **Performance Characteristics:**\n *\n * - Enqueue: O(1) amortized (O(n) when buffer needs resizing)\n * - Dequeue: O(1) always\n * - Size/isEmpty: O(1) always\n * - Memory efficient with automatic garbage collection of removed elements\n *\n * **Use Cases:**\n *\n * - Task scheduling and job queues\n * - Breadth-first search algorithms\n * - Event processing systems\n * - Producer-consumer patterns\n * - Buffer management for streaming data\n *\n * @template T The type of elements stored in the queue.\n */\nexport type Queue<T> = Readonly<{\n  /**\n   * Checks if the queue is empty.\n   *\n   * @example\n   *\n   * ```ts\n   * const queue = createQueue<number>();\n   *\n   * assert.isTrue(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 0);\n   *\n   * queue.enqueue(1);\n   *\n   * queue.enqueue(2);\n   *\n   * assert.isFalse(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 2);\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.none);\n   *\n   * const seededQueue = createQueue(['first', 'second']);\n   *\n   * assert.isTrue(seededQueue.size === 2);\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));\n   * ```\n   */\n  isEmpty: boolean;\n\n  /**\n   * The number of elements in the queue.\n   *\n   * @example\n   *\n   * ```ts\n   * const queue = createQueue<number>();\n   *\n   * assert.isTrue(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 0);\n   *\n   * queue.enqueue(1);\n   *\n   * queue.enqueue(2);\n   *\n   * assert.isFalse(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 2);\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.none);\n   *\n   * const seededQueue = createQueue(['first', 'second']);\n   *\n   * assert.isTrue(seededQueue.size === 2);\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));\n   * ```\n   */\n  size: SizeType.Arr;\n\n  /**\n   * Removes and returns the element at the front of the queue.\n   *\n   * @example\n   *\n   * ```ts\n   * const queue = createQueue<number>();\n   *\n   * assert.isTrue(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 0);\n   *\n   * queue.enqueue(1);\n   *\n   * queue.enqueue(2);\n   *\n   * assert.isFalse(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 2);\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.none);\n   *\n   * const seededQueue = createQueue(['first', 'second']);\n   *\n   * assert.isTrue(seededQueue.size === 2);\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));\n   * ```\n   *\n   * @returns The element at the front of the queue, or `Optional.none` if the\n   *   queue is empty.\n   */\n  dequeue: () => Optional<T>;\n\n  /**\n   * Adds an element to the back of the queue.\n   *\n   * @example\n   *\n   * ```ts\n   * const queue = createQueue<number>();\n   *\n   * assert.isTrue(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 0);\n   *\n   * queue.enqueue(1);\n   *\n   * queue.enqueue(2);\n   *\n   * assert.isFalse(queue.isEmpty);\n   *\n   * assert.isTrue(queue.size === 2);\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));\n   *\n   * assert.deepStrictEqual(queue.dequeue(), Optional.none);\n   *\n   * const seededQueue = createQueue(['first', 'second']);\n   *\n   * assert.isTrue(seededQueue.size === 2);\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));\n   *\n   * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));\n   * ```\n   *\n   * @param value The element to add.\n   */\n  enqueue: (value: T) => void;\n}>;\n\n/**\n * Class implementation for a queue with FIFO (First-In, First-Out) behavior\n * using a circular buffer. This implementation provides O(1) enqueue and\n * dequeue operations by using a fixed-size buffer with head and tail pointers\n * that wrap around when they reach the buffer boundary.\n *\n * The circular buffer automatically resizes when it becomes full, ensuring that\n * the queue can grow to accommodate any number of elements while maintaining\n * efficient operations.\n *\n * @template T The type of elements in the queue.\n * @implements Queue\n */\nclass QueueClass<T> implements Queue<T> {\n  /** @internal Initial capacity for new queues. */\n  static readonly #INITIAL_CAPACITY = 8;\n\n  /** @internal Circular buffer to store queue elements. */\n  #mut_buffer: (T | undefined)[];\n\n  /** @internal Index of the first element (front of queue). */\n  #mut_head: number;\n\n  /** @internal Index where the next element will be added (back of queue). */\n  #mut_tail: number;\n\n  /** @internal Current number of elements in the queue. */\n  #mut_size: number;\n\n  /** @internal Current capacity of the buffer. */\n  #mut_capacity: number;\n\n  /**\n   * Constructs a new QueueClass instance.\n   *\n   * @param initialValues Optional initial values to populate the queue.\n   */\n  constructor(initialValues: readonly T[] = []) {\n    const initialCapacity = asUint32(\n      Math.max(QueueClass.#INITIAL_CAPACITY, initialValues.length * 2),\n    );\n\n    this.#mut_buffer = Array.from<unknown, T | undefined>(\n      { length: initialCapacity },\n      () => undefined,\n    );\n\n    this.#mut_head = 0;\n\n    this.#mut_tail = 0;\n\n    this.#mut_size = 0;\n\n    this.#mut_capacity = initialCapacity;\n\n    // Add initial values\n    for (const value of initialValues) {\n      this.enqueue(value);\n    }\n  }\n\n  /**\n   * @internal\n   * Resizes the circular buffer when it becomes full.\n   * Doubles the capacity and reorganizes elements to maintain queue order.\n   */\n  #resize(): void {\n    const newCapacity = asUint32(this.#mut_capacity * 2);\n\n    const newBuffer = Array.from<unknown, T | undefined>(\n      { length: newCapacity },\n      () => undefined,\n    );\n\n    // Copy elements in order from head to tail\n    for (const i of range(asSafeUint(this.#mut_size))) {\n      const sourceIndex = (this.#mut_head + i) % this.#mut_capacity;\n\n      newBuffer[i] = this.#mut_buffer[sourceIndex];\n    }\n\n    this.#mut_buffer = newBuffer;\n\n    this.#mut_head = 0;\n\n    this.#mut_tail = this.#mut_size;\n\n    this.#mut_capacity = newCapacity;\n  }\n\n  /** @inheritdoc */\n  get isEmpty(): boolean {\n    return this.#mut_size === 0;\n  }\n\n  /** @inheritdoc */\n  get size(): SizeType.Arr {\n    return asUint32(this.#mut_size);\n  }\n\n  /**\n   * Removes and returns the element at the front of the queue (FIFO).\n   *\n   * This operation removes the element that was added earliest (first-in) and\n   * returns it. If the queue is empty, returns `Optional.none`. The operation\n   * is guaranteed to be O(1) and does not require any array shifting or\n   * copying.\n   *\n   * **Time Complexity:** O(1) - constant time operation **Space Complexity:**\n   * O(1) - no additional memory allocation\n   *\n   * @returns An Optional containing the removed element, or `Optional.none` if\n   *   the queue is empty.\n   */\n  dequeue(): Optional<T> {\n    if (this.isEmpty) {\n      return Optional.none;\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    const element = this.#mut_buffer[this.#mut_head]!;\n\n    this.#mut_buffer[this.#mut_head] = undefined; // Clear reference for garbage collection\n\n    this.#mut_head = (this.#mut_head + 1) % this.#mut_capacity;\n\n    this.#mut_size -= 1;\n\n    return Optional.some(element);\n  }\n\n  /**\n   * Adds an element to the back of the queue (FIFO).\n   *\n   * This operation adds the element to the end of the queue, where it will be\n   * the last to be dequeued (first-in, first-out ordering). The operation is\n   * amortized O(1), meaning it's O(1) for most operations with occasional O(n)\n   * when the buffer needs resizing.\n   *\n   * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is\n   * needed **Space Complexity:** O(1) - constant additional memory per element\n   *\n   * **Buffer Resizing:** When the internal buffer becomes full, it\n   * automatically doubles in size and reorganizes elements to maintain the\n   * circular buffer structure.\n   *\n   * @param value The element to add to the back of the queue.\n   */\n  enqueue(value: T): void {\n    // Resize if buffer is full\n    if (this.#mut_size === this.#mut_capacity) {\n      this.#resize();\n    }\n\n    this.#mut_buffer[this.#mut_tail] = value;\n\n    this.#mut_tail = (this.#mut_tail + 1) % this.#mut_capacity;\n\n    this.#mut_size += 1;\n  }\n}\n\n/**\n * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a\n * high-performance circular buffer.\n *\n * This factory function creates an optimized queue implementation that\n * maintains excellent performance characteristics for both enqueue and dequeue\n * operations. The underlying circular buffer automatically resizes to\n * accommodate growing workloads while providing predictable O(1) operations.\n *\n * **Implementation Features:**\n *\n * - **O(1) enqueue operations** (amortized - occasionally O(n) when resizing)\n * - **O(1) dequeue operations** (always)\n * - **Automatic buffer resizing** - starts at 8 elements, doubles when full\n * - **Memory efficient** - garbage collects removed elements immediately\n * - **Circular buffer design** - eliminates need for array shifting operations\n *\n * **Performance Benefits:**\n *\n * - No array copying during normal operations\n * - Minimal memory allocation overhead\n * - Predictable performance under high load\n * - Efficient memory usage with automatic cleanup\n *\n * @example\n *\n * ```ts\n * const queue = createQueue<number>();\n *\n * assert.isTrue(queue.isEmpty);\n *\n * assert.isTrue(queue.size === 0);\n *\n * queue.enqueue(1);\n *\n * queue.enqueue(2);\n *\n * assert.isFalse(queue.isEmpty);\n *\n * assert.isTrue(queue.size === 2);\n *\n * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));\n *\n * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));\n *\n * assert.deepStrictEqual(queue.dequeue(), Optional.none);\n *\n * const seededQueue = createQueue(['first', 'second']);\n *\n * assert.isTrue(seededQueue.size === 2);\n *\n * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));\n *\n * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));\n * ```\n *\n * @template T The type of elements stored in the queue.\n * @param initialValues Optional array of initial elements to populate the\n *   queue. Elements will be dequeued in the same order they appear in the\n *   array. If provided, the initial buffer capacity will be at least twice the\n *   array length.\n * @returns A new Queue instance optimized for high-performance FIFO operations.\n */\nexport const createQueue = <T,>(initialValues?: readonly T[]): Queue<T> =>\n  new QueueClass<T>(initialValues);\n"],"names":["Optional.none","Optional.some"],"mappings":"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"}

package/dist/collections/stack.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"stack.d.mts","sourceRoot":"","sources":["../../src/collections/stack.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC1B,CAAC,CAAC;AA+IH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAG,gBAAgB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}
+{"version":3,"file":"stack.d.mts","sourceRoot":"","sources":["../../src/collections/stack.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC1B,CAAC,CAAC;AA+IH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,kBAAmB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}

package/dist/collections/stack.mjs

@@ -39,177 +39,107 @@ import '../number/enum/uint8.mjs';
 import '../number/num.mjs';
 import '../number/refined-number-utils.mjs';
 
-/**
- * Class implementation for a stack with LIFO (Last-In, First-Out) behavior
- * using a dynamic array. This implementation provides O(1) amortized push and
- * O(1) pop operations by using a resizable buffer that grows as needed.
- *
- * The underlying array automatically resizes when it becomes full, ensuring
- * that the stack can grow to accommodate any number of elements while
- * maintaining efficient operations.
- *
- * @template T The type of elements in the stack.
- * @implements Stack
- */
 class StackClass {
-    /** @internal Initial capacity for new stacks. */
-    static #INITIAL_CAPACITY = 8;
-    /** @internal Dynamic array to store stack elements. */
-    #mut_buffer;
-    /** @internal Current number of elements in the stack. */
-    #mut_size;
-    /** @internal Current capacity of the buffer. */
-    #mut_capacity;
-    /**
-     * Constructs a new StackClass instance.
-     *
-     * @param initialValues Optional initial values to populate the stack.
-     */
-    constructor(initialValues = []) {
-        const initialCapacity = asUint32(Math.max(StackClass.#INITIAL_CAPACITY, initialValues.length * 2));
-        this.#mut_buffer = Array.from({ length: initialCapacity }, () => undefined);
-        this.#mut_size = asUint32(0);
-        this.#mut_capacity = initialCapacity;
-        // Add initial values
-        for (const value of initialValues) {
-            this.push(value);
-        }
+  /** @internal Initial capacity for new stacks. */
+  static #INITIAL_CAPACITY = 8;
+  /** @internal Dynamic array to store stack elements. */
+  #mut_buffer;
+  /** @internal Current number of elements in the stack. */
+  #mut_size;
+  /** @internal Current capacity of the buffer. */
+  #mut_capacity;
+  /**
+   * Constructs a new StackClass instance.
+   *
+   * @param initialValues Optional initial values to populate the stack.
+   */
+  constructor(initialValues = []) {
+    const initialCapacity = asUint32(
+      Math.max(StackClass.#INITIAL_CAPACITY, initialValues.length * 2)
+    );
+    this.#mut_buffer = Array.from(
+      { length: initialCapacity },
+      () => void 0
+    );
+    this.#mut_size = asUint32(0);
+    this.#mut_capacity = initialCapacity;
+    for (const value of initialValues) {
+      this.push(value);
     }
-    /**
-     * @internal
-     * Resizes the buffer when it becomes full.
-     * Doubles the capacity while preserving all elements.
-     */
-    #resize() {
-        const newCapacity = asUint32(this.#mut_capacity * 2);
-        const newBuffer = Array.from({ length: newCapacity }, () => undefined);
-        // Copy existing elements
-        for (const i of range(this.#mut_size)) {
-            newBuffer[i] = this.#mut_buffer[i];
-        }
-        this.#mut_buffer = newBuffer;
-        this.#mut_capacity = newCapacity;
+  }
+  /**
+   * @internal
+   * Resizes the buffer when it becomes full.
+   * Doubles the capacity while preserving all elements.
+   */
+  #resize() {
+    const newCapacity = asUint32(this.#mut_capacity * 2);
+    const newBuffer = Array.from(
+      { length: newCapacity },
+      () => void 0
+    );
+    for (const i of range(this.#mut_size)) {
+      newBuffer[i] = this.#mut_buffer[i];
     }
-    /** @inheritdoc */
-    get isEmpty() {
-        return this.#mut_size === 0;
+    this.#mut_buffer = newBuffer;
+    this.#mut_capacity = newCapacity;
+  }
+  /** @inheritdoc */
+  get isEmpty() {
+    return this.#mut_size === 0;
+  }
+  /** @inheritdoc */
+  get size() {
+    return asUint32(this.#mut_size);
+  }
+  /**
+   * Removes and returns the element at the top of the stack (LIFO).
+   *
+   * This operation removes the element that was added most recently (last-in)
+   * and returns it. If the stack is empty, returns `Optional.none`. The
+   * operation is guaranteed to be O(1) and does not require any array resizing
+   * or memory reallocation.
+   *
+   * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
+   * O(1) - no additional memory allocation
+   *
+   * @returns An Optional containing the removed element, or `Optional.none` if
+   *   the stack is empty.
+   */
+  pop() {
+    if (this.isEmpty) {
+      return none;
     }
-    /** @inheritdoc */
-    get size() {
-        return asUint32(this.#mut_size);
-    }
-    /**
-     * Removes and returns the element at the top of the stack (LIFO).
-     *
-     * This operation removes the element that was added most recently (last-in)
-     * and returns it. If the stack is empty, returns `Optional.none`. The
-     * operation is guaranteed to be O(1) and does not require any array resizing
-     * or memory reallocation.
-     *
-     * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
-     * O(1) - no additional memory allocation
-     *
-     * @returns An Optional containing the removed element, or `Optional.none` if
-     *   the stack is empty.
-     */
-    pop() {
-        if (this.isEmpty) {
-            return none;
-        }
-        this.#mut_size = Uint32.sub(this.#mut_size, 1);
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const element = this.#mut_buffer[this.#mut_size];
-        this.#mut_buffer[this.#mut_size] = undefined; // Clear reference for garbage collection
-        return some(element);
-    }
-    /**
-     * Adds an element to the top of the stack (LIFO).
-     *
-     * This operation adds the element to the top of the stack, where it will be
-     * the first to be popped (last-in, first-out ordering). The operation is
-     * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
-     * when the buffer needs resizing.
-     *
-     * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
-     * needed **Space Complexity:** O(1) - constant additional memory per element
-     *
-     * **Buffer Resizing:** When the internal buffer becomes full, it
-     * automatically doubles in size and copies existing elements to maintain the
-     * stack structure.
-     *
-     * @param value The element to add to the top of the stack.
-     */
-    push(value) {
-        // Resize if buffer is full
-        if (this.#mut_size === this.#mut_capacity) {
-            this.#resize();
-        }
-        this.#mut_buffer[this.#mut_size] = value;
-        this.#mut_size = Uint32.add(this.#mut_size, 1);
+    this.#mut_size = Uint32.sub(this.#mut_size, 1);
+    const element = this.#mut_buffer[this.#mut_size];
+    this.#mut_buffer[this.#mut_size] = void 0;
+    return some(element);
+  }
+  /**
+   * Adds an element to the top of the stack (LIFO).
+   *
+   * This operation adds the element to the top of the stack, where it will be
+   * the first to be popped (last-in, first-out ordering). The operation is
+   * amortized O(1), meaning it's O(1) for most operations with occasional O(n)
+   * when the buffer needs resizing.
+   *
+   * **Time Complexity:** O(1) amortized - O(n) only when buffer resize is
+   * needed **Space Complexity:** O(1) - constant additional memory per element
+   *
+   * **Buffer Resizing:** When the internal buffer becomes full, it
+   * automatically doubles in size and copies existing elements to maintain the
+   * stack structure.
+   *
+   * @param value The element to add to the top of the stack.
+   */
+  push(value) {
+    if (this.#mut_size === this.#mut_capacity) {
+      this.#resize();
     }
+    this.#mut_buffer[this.#mut_size] = value;
+    this.#mut_size = Uint32.add(this.#mut_size, 1);
+  }
 }
-/**
- * Creates a new Stack instance with LIFO (Last-In, First-Out) behavior using a
- * high-performance dynamic array.
- *
- * This factory function creates an optimized stack implementation that
- * maintains excellent performance characteristics for both push and pop
- * operations. The underlying dynamic array automatically resizes to accommodate
- * growing workloads while providing predictable O(1) operations.
- *
- * **Implementation Features:**
- *
- * - **O(1) push operations** (amortized - occasionally O(n) when resizing)
- * - **O(1) pop operations** (always)
- * - **Automatic buffer resizing** - starts at 8 elements, doubles when full
- * - **Memory efficient** - garbage collects removed elements immediately
- * - **Dynamic array design** - eliminates need for complex memory management
- *
- * **Performance Benefits:**
- *
- * - No array shifting required for stack operations
- * - Minimal memory allocation overhead
- * - Predictable performance under high load
- * - Efficient memory usage with automatic cleanup
- *
- * @example
- *
- * ```ts
- * const stack = createStack<string>();
- *
- * assert.isTrue(stack.isEmpty);
- *
- * assert.isTrue(stack.size === 0);
- *
- * stack.push('first');
- *
- * // eslint-disable-next-line unicorn/prefer-single-call
- * stack.push('second');
- *
- * assert.isFalse(stack.isEmpty);
- *
- * assert.isTrue(stack.size === 2);
- *
- * assert.deepStrictEqual(stack.pop(), Optional.some('second'));
- *
- * assert.deepStrictEqual(stack.pop(), Optional.some('first'));
- *
- * assert.deepStrictEqual(stack.pop(), Optional.none);
- *
- * const seededStack = createStack([10, 20, 30]);
- *
- * assert.isTrue(seededStack.size === 3);
- *
- * assert.deepStrictEqual(seededStack.pop(), Optional.some(30));
- * ```
- *
- * @template T The type of elements stored in the stack.
- * @param initialValues Optional array of initial elements to populate the
- *   stack. Elements will be popped in reverse order of how they appear in the
- *   array (last array element will be popped first). If provided, the initial
- *   buffer capacity will be at least twice the array length.
- * @returns A new Stack instance optimized for high-performance LIFO operations.
- */
 const createStack = (initialValues) => new StackClass(initialValues);
 
 export { createStack };