ts-data-forge 14.6.0 → 14.6.2

package/dist/collections/queue.mjs

@@ -1,157 +1,189 @@
-import { none } from '../functional/optional/impl/optional-none.mjs';
-import { some } from '../functional/optional/impl/optional-some.mjs';
-import '@sindresorhus/is';
-import { range } from '../iterator/range.mjs';
-import '../number/branded-types/finite-number.mjs';
-import '../number/branded-types/int.mjs';
-import '../number/branded-types/int16.mjs';
-import '../number/branded-types/int32.mjs';
-import '../number/branded-types/negative-finite-number.mjs';
-import '../number/branded-types/negative-int.mjs';
-import '../number/branded-types/negative-safe-int.mjs';
-import '../number/branded-types/non-negative-finite-number.mjs';
-import '../number/branded-types/non-negative-int16.mjs';
-import '../number/branded-types/non-negative-int32.mjs';
-import '../number/branded-types/non-positive-finite-number.mjs';
-import '../number/branded-types/non-positive-int.mjs';
-import '../number/branded-types/non-positive-safe-int.mjs';
-import '../number/branded-types/non-zero-finite-number.mjs';
-import '../number/branded-types/non-zero-int.mjs';
-import '../number/branded-types/non-zero-int16.mjs';
-import '../number/branded-types/non-zero-int32.mjs';
-import '../number/branded-types/non-zero-safe-int.mjs';
-import '../number/branded-types/non-zero-uint16.mjs';
-import '../number/branded-types/non-zero-uint32.mjs';
-import '../number/branded-types/positive-finite-number.mjs';
-import '../number/branded-types/positive-int.mjs';
-import '../number/branded-types/positive-int16.mjs';
-import '../number/branded-types/positive-int32.mjs';
-import '../number/branded-types/positive-safe-int.mjs';
-import '../number/branded-types/positive-uint16.mjs';
-import '../number/branded-types/positive-uint32.mjs';
-import '../number/branded-types/safe-int.mjs';
-import { asSafeUint } from '../number/branded-types/safe-uint.mjs';
-import '../number/branded-types/uint.mjs';
-import '../number/branded-types/uint16.mjs';
-import { asUint32 } from '../number/branded-types/uint32.mjs';
-import '../number/enum/int8.mjs';
-import '../number/enum/uint8.mjs';
-import '../number/num.mjs';
-import '../number/refined-number-utils.mjs';
-
+import { Optional } from '../functional/index.mjs';
+import { range } from '../iterator/index.mjs';
+import { asSafeUint, asUint32 } from '../number/index.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 },
-      () => 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 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
-   * 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];
+    /**
+     * @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;
     }
-    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 isEmpty() {
+        return this.#mut_size === 0;
     }
-    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();
+    /** @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 Optional.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 Optional.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;
     }
-    this.#mut_buffer[this.#mut_tail] = value;
-    this.#mut_tail = (this.#mut_tail + 1) % this.#mut_capacity;
-    this.#mut_size += 1;
-  }
 }
-const createQueue = (initialValues) => new QueueClass(initialValues);
-
-export { createQueue };
-//# sourceMappingURL=queue.mjs.map
+/**
+ * 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.
+ */
+export const createQueue = (initialValues) => new QueueClass(initialValues);
+//# sourceMappingURL=queue.mjs.map

package/dist/collections/queue.mjs.map

@@ -1 +1 @@
-{"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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"}
+{"version":3,"file":"queue.mjs","sourceRoot":"","sources":["../../src/collections/queue.mts"],"names":[],"mappings":"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"}