max-priority-queue-typed 2.4.5 → 2.5.1

package/src/data-structures/queue/queue.ts

@@ -23,48 +23,6 @@ import { LinearBase } from '../base/linear-base';
  * 6. Breadth-First Search (BFS): In traversal algorithms for graphs and trees, queues store elements that are to be visited.
  * 7. Real-time Queuing: Like queuing systems in banks or supermarkets.
  * @example
- * // basic Queue creation and push operation
- *  // Create a simple Queue with initial values
- *     const queue = new Queue([1, 2, 3, 4, 5]);
- *
- *     // Verify the queue maintains insertion order
- *     console.log([...queue]); // [1, 2, 3, 4, 5];
- *
- *     // Check length
- *     console.log(queue.length); // 5;
- * @example
- * // Queue shift and peek operations
- *  const queue = new Queue<number>([10, 20, 30, 40]);
- *
- *     // Peek at the front element without removing it
- *     console.log(queue.first); // 10;
- *
- *     // Remove and get the first element (FIFO)
- *     const first = queue.shift();
- *     console.log(first); // 10;
- *
- *     // Verify remaining elements and length decreased
- *     console.log([...queue]); // [20, 30, 40];
- *     console.log(queue.length); // 3;
- * @example
- * // Queue for...of iteration and isEmpty check
- *  const queue = new Queue<string>(['A', 'B', 'C', 'D']);
- *
- *     const elements: string[] = [];
- *     for (const item of queue) {
- *       elements.push(item);
- *     }
- *
- *     // Verify all elements are iterated in order
- *     console.log(elements); // ['A', 'B', 'C', 'D'];
- *
- *     // Process all elements
- *     while (queue.length > 0) {
- *       queue.shift();
- *     }
- *
- *     console.log(queue.length); // 0;
- * @example
  * // Queue as message broker for event processing
  *  interface Message {
  *       id: string;
@@ -125,6 +83,10 @@ import { LinearBase } from '../base/linear-base';
  *
  *     // Queue should be empty after processing all messages
  *     console.log(messageQueue.length); // 0;
+ * @example
+ * // Convert queue to array
+ *  const q = new Queue<number>([10, 20, 30]);
+ *     console.log(q.toArray()); // [10, 20, 30];
  */
 export class Queue<E = any, R = any> extends LinearBase<E, R> {
   /**
@@ -195,6 +157,45 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Get the number of elements currently in the queue.
    * @remarks Time O(1), Space O(1)
    * @returns Current length.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Track queue length
+ *  const q = new Queue<number>();
+ *     console.log(q.length); // 0;
+ *     q.push(1);
+ *     q.push(2);
+ *     console.log(q.length); // 2;
    */
 
   get length(): number {
@@ -205,6 +206,43 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Get the first element (front) without removing it.
    * @remarks Time O(1), Space O(1)
    * @returns Front element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // View the front element
+ *  const q = new Queue<string>(['first', 'second', 'third']);
+ *     console.log(q.first); // 'first';
+ *     console.log(q.length); // 3;
    */
 
   get first(): E | undefined {
@@ -237,6 +275,56 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Check whether the queue is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if length is 0.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Queue for...of iteration and isEmpty check
+ *  const queue = new Queue<string>(['A', 'B', 'C', 'D']);
+ *
+ *     const elements: string[] = [];
+ *     for (const item of queue) {
+ *       elements.push(item);
+ *     }
+ *
+ *     // Verify all elements are iterated in order
+ *     console.log(elements); // ['A', 'B', 'C', 'D'];
+ *
+ *     // Process all elements
+ *     while (queue.length > 0) {
+ *       queue.shift();
+ *     }
+ *
+ *     console.log(queue.length); // 0;
    */
 
   isEmpty(): boolean {
@@ -248,6 +336,48 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(1), Space O(1)
    * @param element - Element to enqueue.
    * @returns True on success.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic Queue creation and push operation
+ *  // Create a simple Queue with initial values
+ *     const queue = new Queue([1, 2, 3, 4, 5]);
+ *
+ *     // Verify the queue maintains insertion order
+ *     console.log([...queue]); // [1, 2, 3, 4, 5];
+ *
+ *     // Check length
+ *     console.log(queue.length); // 5;
    */
 
   push(element: E): boolean {
@@ -276,6 +406,52 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Dequeue one element from the front (amortized via offset).
    * @remarks Time O(1) amortized, Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Queue shift and peek operations
+ *  const queue = new Queue<number>([10, 20, 30, 40]);
+ *
+ *     // Peek at the front element without removing it
+ *     console.log(queue.first); // 10;
+ *
+ *     // Remove and get the first element (FIFO)
+ *     const first = queue.shift();
+ *     console.log(first); // 10;
+ *
+ *     // Verify remaining elements and length decreased
+ *     console.log([...queue]); // [20, 30, 40];
+ *     console.log(queue.length); // 3;
    */
 
   shift(): E | undefined {
@@ -291,6 +467,40 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(N), Space O(1)
    * @param element - Element to remove (strict equality via Object.is).
    * @returns True if an element was removed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove specific element
+ *  const q = new Queue<number>([1, 2, 3, 2]);
+ *     q.delete(2);
+ *     console.log(q.length); // 3;
    */
 
   delete(element: E): boolean {
@@ -308,6 +518,40 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(1), Space O(1)
    * @param index - Zero-based index from the front.
    * @returns Element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Access element by index
+ *  const q = new Queue<string>(['a', 'b', 'c']);
+ *     console.log(q.at(0)); // 'a';
+ *     console.log(q.at(2)); // 'c';
    */
 
   at(index: number): E | undefined {
@@ -373,6 +617,41 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Remove all elements and reset offset.
    * @remarks Time O(1), Space O(1)
    * @returns void
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all elements
+ *  const q = new Queue<number>([1, 2, 3]);
+ *     q.clear();
+ *     console.log(q.length); // 0;
    */
 
   clear(): void {
@@ -384,6 +663,42 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Compact storage by discarding consumed head elements.
    * @remarks Time O(N), Space O(N)
    * @returns True when compaction performed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Reclaim unused memory
+ *  const q = new Queue<number>([1, 2, 3, 4, 5]);
+ *     q.shift();
+ *     q.shift();
+ *     q.compact();
+ *     console.log(q.length); // 3;
    */
 
   compact(): boolean {
@@ -421,6 +736,43 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * Deep clone this queue and its parameters.
    * @remarks Time O(N), Space O(N)
    * @returns A new queue with the same content and options.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Create independent copy
+ *  const q = new Queue<number>([1, 2, 3]);
+ *     const copy = q.clone();
+ *     copy.shift();
+ *     console.log(q.length); // 3;
+ *     console.log(copy.length); // 2;
    */
 
   clone(): this {
@@ -436,6 +788,41 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * @param predicate - Predicate (element, index, queue) → boolean to keep element.
    * @param [thisArg] - Value for `this` inside the predicate.
    * @returns A new queue with kept elements.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter elements
+ *  const q = new Queue<number>([1, 2, 3, 4, 5]);
+ *     const evens = q.filter(x => x % 2 === 0);
+ *     console.log(evens.length); // 2;
    */
 
   filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this {
@@ -458,6 +845,40 @@ export class Queue<E = any, R = any> extends LinearBase<E, R> {
    * @param [options] - Options for the output queue (e.g., toElementFn, maxLen, autoCompactRatio).
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new Queue with mapped elements.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform elements
+ *  const q = new Queue<number>([1, 2, 3]);
+ *     const doubled = q.map(x => x * 2);
+ *     console.log(doubled.toArray()); // [2, 4, 6];
    */
 
   map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: QueueOptions<EM, RM>, thisArg?: unknown): Queue<EM, RM> {