ts-data-forge 3.3.0 → 3.3.1

package/dist/collections/queue.d.mts

@@ -1,24 +1,29 @@
 import { Optional } from '../functional/index.mjs';
 /**
- * Interface for a high-performance queue with FIFO (First-In, First-Out) behavior.
+ * Interface for a high-performance queue with FIFO (First-In, First-Out)
+ * behavior.
  *
- * This interface defines a mutable queue data structure where elements are added to the back
- * and removed from the front, maintaining the order in which they were added. The implementation
- * uses a circular buffer for optimal performance, providing O(1) operations for both enqueue
- * and dequeue operations.
+ * This interface defines a mutable queue data structure where elements are
+ * added to the back and removed from the front, maintaining the order in which
+ * they were added. The implementation uses a circular buffer for optimal
+ * performance, providing O(1) operations for both enqueue and dequeue
+ * operations.
  *
  * **FIFO Behavior:**
+ *
  * - **enqueue**: Adds elements to the back of the queue
  * - **dequeue**: Removes and returns elements from the front of the queue
  * - Elements are processed in the exact order they were added
  *
  * **Performance Characteristics:**
- * - enqueue: O(1) amortized (O(n) when buffer needs resizing)
- * - dequeue: O(1) always
- * - size/isEmpty: O(1) always
+ *
+ * - Enqueue: O(1) amortized (O(n) when buffer needs resizing)
+ * - Dequeue: O(1) always
+ * - Size/isEmpty: O(1) always
  * - Memory efficient with automatic garbage collection of removed elements
  *
  * **Use Cases:**
+ *
  * - Task scheduling and job queues
  * - Breadth-first search algorithms
  * - Event processing systems
@@ -26,64 +31,137 @@ import { Optional } from '../functional/index.mjs';
  * - Buffer management for streaming data
  *
  * @template T The type of elements stored in the queue.
- *
- * @example
- * ```typescript
- * import { createQueue, Queue } from './queue';
- *
- * // Example 1: Basic FIFO operations
- * const messageQueue: Queue<string> = createQueue<string>();
- *
- * messageQueue.enqueue("first message");   // Add to back
- * messageQueue.enqueue("second message");  // Add to back
- * messageQueue.enqueue("third message");   // Add to back
- *
- * console.log(messageQueue.size); // Output: 3
- *
- * // Process messages in FIFO order
- * console.log(messageQueue.dequeue().unwrap()); // "first message" (first in, first out)
- * console.log(messageQueue.dequeue().unwrap()); // "second message"
- * console.log(messageQueue.size); // Output: 1
- *
- * // Example 2: Task processing system
- * type Task = { id: number; priority: string; action: () => void };
- * const taskQueue: Queue<Task> = createQueue<Task>();
- *
- * taskQueue.enqueue({ id: 1, priority: "high", action: () => console.log("Task 1") });
- * taskQueue.enqueue({ id: 2, priority: "low", action: () => console.log("Task 2") });
- *
- * // Process tasks in order
- * while (!taskQueue.isEmpty) {
- *   const task = taskQueue.dequeue().unwrap();
- *   console.log(`Processing task ${task.id} with ${task.priority} priority`);
- *   task.action();
- * }
- * ```
  */
 export type Queue<T> = Readonly<{
-    /** Checks if the queue is empty. */
+    /**
+     * Checks if the queue is empty.
+     *
+     * @example
+     *
+     * ```ts
+     * const queue = createQueue<number>();
+     *
+     * assert.ok(queue.isEmpty);
+     * assert(queue.size === 0);
+     *
+     * queue.enqueue(1);
+     * queue.enqueue(2);
+     *
+     * assert.notOk(queue.isEmpty);
+     * assert(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(seededQueue.size === 2);
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
+     * ```
+     */
     isEmpty: boolean;
-    /** The number of elements in the queue. */
+    /**
+     * The number of elements in the queue.
+     *
+     * @example
+     *
+     * ```ts
+     * const queue = createQueue<number>();
+     *
+     * assert.ok(queue.isEmpty);
+     * assert(queue.size === 0);
+     *
+     * queue.enqueue(1);
+     * queue.enqueue(2);
+     *
+     * assert.notOk(queue.isEmpty);
+     * assert(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(seededQueue.size === 2);
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
+     * ```
+     */
     size: SizeType.Arr;
     /**
      * Removes and returns the element at the front of the queue.
-     * @returns The element at the front of the queue, or `Optional.none` if the queue is empty.
+     *
+     * @example
+     *
+     * ```ts
+     * const queue = createQueue<number>();
+     *
+     * assert.ok(queue.isEmpty);
+     * assert(queue.size === 0);
+     *
+     * queue.enqueue(1);
+     * queue.enqueue(2);
+     *
+     * assert.notOk(queue.isEmpty);
+     * assert(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(seededQueue.size === 2);
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
+     * ```
+     *
+     * @returns The element at the front of the queue, or `Optional.none` if the
+     *   queue is empty.
      */
     dequeue: () => Optional<T>;
     /**
      * Adds an element to the back of the queue.
+     *
+     * @example
+     *
+     * ```ts
+     * const queue = createQueue<number>();
+     *
+     * assert.ok(queue.isEmpty);
+     * assert(queue.size === 0);
+     *
+     * queue.enqueue(1);
+     * queue.enqueue(2);
+     *
+     * assert.notOk(queue.isEmpty);
+     * assert(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(seededQueue.size === 2);
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('first'));
+     * assert.deepStrictEqual(seededQueue.dequeue(), Optional.some('second'));
+     * ```
+     *
      * @param value The element to add.
      */
     enqueue: (value: T) => void;
 }>;
 /**
- * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a high-performance circular buffer.
+ * 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.
+ * 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
@@ -91,100 +169,42 @@ export type Queue<T> = Readonly<{
  * - **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
  *
- * @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.
- *
  * @example
- * ```typescript
- * import { createQueue } from './queue';
- *
- * // Example 1: Basic FIFO workflow
- * const requestQueue = createQueue<string>();
- *
- * // Add requests to the queue
- * requestQueue.enqueue("GET /api/users");     // O(1)
- * requestQueue.enqueue("POST /api/orders");   // O(1)
- * requestQueue.enqueue("DELETE /api/cache");  // O(1)
- *
- * // Process requests in order
- * while (!requestQueue.isEmpty) {
- *   const request = requestQueue.dequeue().unwrap(); // O(1)
- *   console.log(`Processing: ${request}`);
- * }
- * // Output:
- * // Processing: GET /api/users
- * // Processing: POST /api/orders
- * // Processing: DELETE /api/cache
- *
- * // Example 2: High-throughput event processing
- * type Event = { timestamp: number; type: string; data: any };
- * const eventQueue = createQueue<Event>();
- *
- * // Simulate high-volume event ingestion
- * for (const i of range(10000)) {
- *   eventQueue.enqueue({
- *     timestamp: Date.now(),
- *     type: `event-${i % 5}`,
- *     data: { value: i }
- *   }); // Each enqueue is O(1) amortized
- * }
- *
- * // Process events efficiently
- * let processedCount = 0;
- * while (!eventQueue.isEmpty) {
- *   const event = eventQueue.dequeue().unwrap(); // O(1)
- *   // Process event...
- *   processedCount++;
- * }
- * console.log(`Processed ${processedCount} events`); // 10000
- *
- * // Example 3: Queue with pre-populated data
- * const priorityTasks = createQueue<string>([
- *   "Initialize system",
- *   "Load configuration",
- *   "Start services",
- *   "Begin processing"
- * ]);
- *
- * console.log(priorityTasks.size); // Output: 4
- *
- * // Execute tasks in initialization order
- * while (!priorityTasks.isEmpty) {
- *   const task = priorityTasks.dequeue().unwrap();
- *   console.log(`Executing: ${task}`);
- * }
- *
- * // Example 4: Producer-Consumer pattern
- * const workQueue = createQueue<() => Promise<void>>();
- *
- * // Producer: Add work items
- * const addWork = (workFn: () => Promise<void>) => {
- *   workQueue.enqueue(workFn);
- * };
- *
- * // Consumer: Process work items
- * const processWork = async () => {
- *   while (!workQueue.isEmpty) {
- *     const workItem = workQueue.dequeue().unwrap();
- *     await workItem();
- *   }
- * };
- *
- * // Add some work
- * addWork(async () => console.log("Work item 1"));
- * addWork(async () => console.log("Work item 2"));
- *
- * // Process the work
- * await processWork();
+ *
+ * ```ts
+ * const queue = createQueue<number>();
+ *
+ * assert.ok(queue.isEmpty);
+ * assert(queue.size === 0);
+ *
+ * queue.enqueue(1);
+ * queue.enqueue(2);
+ *
+ * assert.notOk(queue.isEmpty);
+ * assert(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(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 declare const createQueue: <T>(initialValues?: readonly T[]) => Queue<T>;
 //# sourceMappingURL=queue.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"queue.d.mts","sourceRoot":"","sources":["../../src/collections/queue.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IAEjB,2CAA2C;IAC3C,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;OAGG;IACH,OAAO,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE3B;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAAC,CAAC;AAqMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAG,gBAAgB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}
+{"version":3,"file":"queue.d.mts","sourceRoot":"","sources":["../../src/collections/queue.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAAC,CAAC;AAuJH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAG,gBAAgB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}

package/dist/collections/queue.mjs

@@ -33,12 +33,14 @@ 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.
+ * 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.
+ * 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
@@ -58,6 +60,7 @@ class QueueClass {
     static #INITIAL_CAPACITY = 8;
     /**
      * Constructs a new QueueClass instance.
+     *
      * @param initialValues Optional initial values to populate the queue.
      */
     constructor(initialValues = []) {
@@ -83,40 +86,16 @@ class QueueClass {
     /**
      * 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.
-     *
-     * @example
-     * ```typescript
-     * const queue = createQueue<string>();
+     * 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.
      *
-     * // Add some elements
-     * queue.enqueue("first");
-     * queue.enqueue("second");
-     * queue.enqueue("third");
+     * **Time Complexity:** O(1) - constant time operation **Space Complexity:**
+     * O(1) - no additional memory allocation
      *
-     * // Remove elements in FIFO order
-     * const first = queue.dequeue();
-     * if (first.isSome) {
-     *   console.log(first.value); // "first"
-     * }
-     *
-     * const second = queue.dequeue().unwrap(); // "second"
-     * console.log(queue.size); // 1
-     *
-     * // Safe handling of empty queue
-     * const emptyQueue = createQueue<number>();
-     * const result = emptyQueue.dequeue();
-     * if (result.isNone) {
-     *   console.log("Queue is empty");
-     * }
-     * ```
+     * @returns An Optional containing the removed element, or `Optional.none` if
+     *   the queue is empty.
      */
     dequeue() {
         if (this.isEmpty) {
@@ -132,44 +111,19 @@ class QueueClass {
     /**
      * 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.
+     * 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
+     * **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.
+     * **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.
-     *
-     * @example
-     * ```typescript
-     * const taskQueue = createQueue<string>();
-     *
-     * // Add tasks in order of arrival
-     * taskQueue.enqueue("Process order #1001");  // O(1)
-     * taskQueue.enqueue("Send notification");    // O(1)
-     * taskQueue.enqueue("Update inventory");     // O(1)
-     *
-     * console.log(taskQueue.size); // 3
-     *
-     * // Tasks will be processed in the order they were added
-     * while (!taskQueue.isEmpty) {
-     *   const task = taskQueue.dequeue().unwrap();
-     *   console.log(`Executing: ${task}`);
-     * }
-     *
-     * // High-volume enqueueing (demonstrates amortized O(1) performance)
-     * const dataQueue = createQueue<number>();
-     *
-     * for (const i of range(1000000)) {
-     *   dataQueue.enqueue(i); // Each operation is O(1) amortized
-     * }
-     *
-     * console.log(dataQueue.size); // 1000000
-     * ```
      */
     enqueue(value) {
         // Resize if buffer is full
@@ -200,13 +154,16 @@ class QueueClass {
     }
 }
 /**
- * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a high-performance circular buffer.
+ * 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.
+ * 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
@@ -214,100 +171,42 @@ class QueueClass {
  * - **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
  *
- * @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.
- *
  * @example
- * ```typescript
- * import { createQueue } from './queue';
- *
- * // Example 1: Basic FIFO workflow
- * const requestQueue = createQueue<string>();
- *
- * // Add requests to the queue
- * requestQueue.enqueue("GET /api/users");     // O(1)
- * requestQueue.enqueue("POST /api/orders");   // O(1)
- * requestQueue.enqueue("DELETE /api/cache");  // O(1)
- *
- * // Process requests in order
- * while (!requestQueue.isEmpty) {
- *   const request = requestQueue.dequeue().unwrap(); // O(1)
- *   console.log(`Processing: ${request}`);
- * }
- * // Output:
- * // Processing: GET /api/users
- * // Processing: POST /api/orders
- * // Processing: DELETE /api/cache
- *
- * // Example 2: High-throughput event processing
- * type Event = { timestamp: number; type: string; data: any };
- * const eventQueue = createQueue<Event>();
  *
- * // Simulate high-volume event ingestion
- * for (const i of range(10000)) {
- *   eventQueue.enqueue({
- *     timestamp: Date.now(),
- *     type: `event-${i % 5}`,
- *     data: { value: i }
- *   }); // Each enqueue is O(1) amortized
- * }
+ * ```ts
+ * const queue = createQueue<number>();
  *
- * // Process events efficiently
- * let processedCount = 0;
- * while (!eventQueue.isEmpty) {
- *   const event = eventQueue.dequeue().unwrap(); // O(1)
- *   // Process event...
- *   processedCount++;
- * }
- * console.log(`Processed ${processedCount} events`); // 10000
+ * assert.ok(queue.isEmpty);
+ * assert(queue.size === 0);
  *
- * // Example 3: Queue with pre-populated data
- * const priorityTasks = createQueue<string>([
- *   "Initialize system",
- *   "Load configuration",
- *   "Start services",
- *   "Begin processing"
- * ]);
+ * queue.enqueue(1);
+ * queue.enqueue(2);
  *
- * console.log(priorityTasks.size); // Output: 4
+ * assert.notOk(queue.isEmpty);
+ * assert(queue.size === 2);
+ * assert.deepStrictEqual(queue.dequeue(), Optional.some(1));
+ * assert.deepStrictEqual(queue.dequeue(), Optional.some(2));
+ * assert.deepStrictEqual(queue.dequeue(), Optional.none);
  *
- * // Execute tasks in initialization order
- * while (!priorityTasks.isEmpty) {
- *   const task = priorityTasks.dequeue().unwrap();
- *   console.log(`Executing: ${task}`);
- * }
+ * const seededQueue = createQueue(['first', 'second']);
  *
- * // Example 4: Producer-Consumer pattern
- * const workQueue = createQueue<() => Promise<void>>();
- *
- * // Producer: Add work items
- * const addWork = (workFn: () => Promise<void>) => {
- *   workQueue.enqueue(workFn);
- * };
- *
- * // Consumer: Process work items
- * const processWork = async () => {
- *   while (!workQueue.isEmpty) {
- *     const workItem = workQueue.dequeue().unwrap();
- *     await workItem();
- *   }
- * };
- *
- * // Add some work
- * addWork(async () => console.log("Work item 1"));
- * addWork(async () => console.log("Work item 2"));
- *
- * // Process the work
- * await processWork();
+ * assert(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);
 

package/dist/collections/queue.mjs.map

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