feat: exposing ChunkedQueue

Since it's a useful data structure, exposing it
for external usage

Author: Farenheith

libs/js-tuple/src/internal/queue.ts libs/js-tuple/src/chunked-queue.tslibs/js-tuple/src/internal/queue.ts renamed to libs/js-tuple/src/chunked-queue.ts

@@ -21,7 +21,12 @@ class Block<T> {
 	}
 }
 
-export class Queue<T> {
+/**
+ * A memory-efficient FIFO queue optimized for high-throughput scenarios.
+ * Uses fixed-size array blocks to minimize memory allocations and copying.
+ * Suitable for scenarios with frequent enqueue/dequeue operations.
+ */
+export class ChunkedQueue<T> {
 	private head?: Block<T>;
 	private tail?: Block<T>;
 	private _length = 0;
@@ -30,6 +35,10 @@ export class Queue<T> {
 		this.push(item);
 	}
 
+	/**
+	 * Adds an item to the end of the queue.
+	 * @param item The item to add.
+	 */
 	push(item: T): void {
 		if (!this.tail || this.tail.isFull()) {
 			const newBlock = new Block<T>();
@@ -41,6 +50,10 @@ export class Queue<T> {
 		this._length++;
 	}
 
+	/**
+	 * Removes and returns the oldest item of the queue.
+	 * @returns The oldest item of the queue, or undefined if the queue is empty.
+	 */
 	pop(): T | undefined {
 		if (!this.head || this.head.isEmpty()) {
 			if (!this.head?.next) return undefined;
@@ -51,13 +64,23 @@ export class Queue<T> {
 		return item;
 	}
 
+	/**
+	 * Processes and removes all items from the queue.
+	 * The callback may add more items to the queue during processing,
+	 * But it needs to take care of the logic to avoid infinite loops.
+	 * @param cb Callback function to process each item.
+	 */
 	exhaust(cb: (item: T) => void): void {
 		while (this.length) {
 			const item = this.pop() as T;
 			cb(item);
 		}
 	}
 
+	/**
+	 * The number of items currently in the queue.
+	 * @returns The number of items in the queue.
+	 */
 	get length(): number {
 		return this._length;
 	}

libs/js-tuple/src/index.ts

@@ -1,3 +1,4 @@
+export * from './chunked-queue';
 export * from './nested-map';
 export * from './nested-set';
 export * from './tuple';

libs/js-tuple/src/internal/index.ts

@@ -1,4 +1,4 @@
-import { Queue } from './internal';
+import { ChunkedQueue } from './chunked-queue';
 import { IterationOptions, PartialKey, TraverseMode, YieldMode } from './types';
 
 const VAL = Symbol('value');
@@ -35,7 +35,7 @@ const EMPTY: PathArray = Object.freeze([]);
 
 function pushToStackFactory<T extends boolean>(justValue: T) {
 	return justValue
-		? (stack: StackItem[] | Queue<StackItem>, stackItem: StackItem) => {
+		? (stack: StackItem[] | ChunkedQueue<StackItem>, stackItem: StackItem) => {
 				const { node } = stackItem;
 				if (!node[MAP]?.size) return;
 				for (const sub of node[MAP].values()) {
@@ -44,7 +44,7 @@ function pushToStackFactory<T extends boolean>(justValue: T) {
 					});
 				}
 			}
-		: (stack: StackItem[] | Queue<StackItem>, stackItem: StackItem) => {
+		: (stack: StackItem[] | ChunkedQueue<StackItem>, stackItem: StackItem) => {
 				const { node, path } = stackItem;
 				if (!node[MAP]?.size) return;
 				for (const [key, sub] of node[MAP].entries()) {
@@ -126,7 +126,7 @@ const traverser = {
 			path: PathArray,
 			justValue: T,
 		): MapIterator<T extends 0 ? [K, V] : V> {
-			const queue = new Queue({ node, path });
+			const queue = new ChunkedQueue({ node, path });
 			const getValue = getValueOpt[justValue] as (
 				si: StackItem,
 			) => T extends 0 ? [K, V] : V;
@@ -525,7 +525,11 @@ export class NestedMap<K, V> {
 			base = treatKey(basePath);
 		}
 		const result = new NestedMap<K, V>();
-		const queue = new Queue({ src: sourceNode, tgt: result.#root, path: base });
+		const queue = new ChunkedQueue({
+			src: sourceNode,
+			tgt: result.#root,
+			path: base,
+		});
 		queue.exhaust(({ src, tgt, path }) => {
 			tgt[COUNT] = src[COUNT];
 			if (src[SET]) tgt[SET] = src[SET];