ts-data-forge
Version:
[](https://www.npmjs.com/package/ts-data-forge) [](https://www.npmjs.com/package/ts-data-forge) [
* 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.
*
* **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
* - Memory efficient with automatic garbage collection of removed elements
*
* **Use Cases:**
*
* - Task scheduling and job queues
* - Breadth-first search algorithms
* - Event processing systems
* - Producer-consumer patterns
* - Buffer management for streaming data
*
* @template T The type of elements stored in the queue.
*/
export type Queue<T> = Readonly<{
/**
* Checks if the queue is empty.
*
* @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'));
* ```
*/
isEmpty: boolean;
/**
* The number of elements in the queue.
*
* @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'));
* ```
*/
size: SizeType.Arr;
/**
* Removes and returns the element at the front of the queue.
*
* @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'));
* ```
*
* @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.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'));
* ```
*
* @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.
*
* 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 declare const createQueue: <T>(initialValues?: readonly T[]) => Queue<T>;
//# sourceMappingURL=queue.d.mts.map