feat[Queue]: add Queue to es-toolkit/util

benchmarks/bundle-size/Queue.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { getBundleSize, getBundleSizeFromScript } from './utils/getBundleSize';
+
+describe('Queue bundle size', () => {
+  it('es-toolkit', async () => {
+    const bundleSize = await getBundleSize('es-toolkit', 'Queue');
+    expect(bundleSize).toMatchInlineSnapshot(`458`);
+  });
+
+  it('yocto-queue', async () => {
+    const bundleSize = await getBundleSizeFromScript(`import Queue from "yocto-queue"; console.log(Queue)`);
+    expect(bundleSize).toMatchInlineSnapshot(`543`);
+  });
+});

benchmarks/package.json

@@ -13,7 +13,8 @@
     "object-hash": "3.0.0",
     "ohash": "2.0.11",
     "remeda": "^2.39.0",
-    "vitest": "4.1.10"
+    "vitest": "4.1.10",
+    "yocto-queue": "1.2.2"
   },
   "devDependencies": {
     "@types/lodash": "4.17.20",

benchmarks/performance/Queue.bench.ts

@@ -0,0 +1,71 @@
+import { bench, describe } from 'vitest';
+import { Queue as QueueToolkit } from 'es-toolkit';
+import QueueYocto from 'yocto-queue';
+
+describe('Queue', () => {
+  bench('es-toolkit/Queue', () => {
+    const queue = new QueueToolkit<number>();
+
+    for (let i = 0; i < 10000; i++) {
+      queue.enqueue(i);
+    }
+
+    while (queue.size > 0) {
+      queue.dequeue();
+    }
+  });
+
+  bench('yocto-queue', () => {
+    const queue = new QueueYocto<number>();
+
+    for (let i = 0; i < 10000; i++) {
+      queue.enqueue(i);
+    }
+
+    while (queue.size > 0) {
+      queue.dequeue();
+    }
+  });
+
+  bench('Array#push/shift', () => {
+    const array: number[] = [];
+
+    for (let i = 0; i < 10000; i++) {
+      array.push(i);
+    }
+
+    while (array.length > 0) {
+      array.shift();
+    }
+  });
+});
+
+describe('Queue/iterate', () => {
+  const queueToolkit = new QueueToolkit<number>();
+  const queueYocto = new QueueYocto<number>();
+
+  for (let i = 0; i < 10000; i++) {
+    queueToolkit.enqueue(i);
+    queueYocto.enqueue(i);
+  }
+
+  bench('es-toolkit/Queue', () => {
+    let sum = 0;
+
+    for (const value of queueToolkit) {
+      sum += value;
+    }
+
+    return sum;
+  });
+
+  bench('yocto-queue', () => {
+    let sum = 0;
+
+    for (const value of queueYocto) {
+      sum += value;
+    }
+
+    return sum;
+  });
+});

docs/ja/reference/util/Queue.md

@@ -0,0 +1,69 @@
+# Queue
+
+先に入れた値を先に取り出す(FIFO)キューを作成します。
+
+```typescript
+const queue = new Queue<T>();
+```
+
+## 使用法
+
+### `Queue()`
+
+タスクリストや幅優先探索のように、届いた順に値を処理したいときに `Queue` を使用してください。`dequeue`、`enqueue` メソッドはキューにどれだけ値があっても高速に動作します。
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<string>();
+
+// キューの末尾に値を追加します。
+queue.enqueue('a');
+queue.enqueue('b');
+queue.enqueue('c');
+
+// キューの先頭から値を取り出します。
+queue.dequeue();
+// Returns: 'a'
+
+// 先頭の値を取り出さずに確認します。
+queue.peek();
+// Returns: 'b'
+
+queue.size;
+// Returns: 2
+```
+
+キューはイテラブルなので、`for...of` でループしたり、スプレッド構文で配列に変換したりできます。ループしても値はキューから削除されません。
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<number>();
+queue.enqueue(1);
+queue.enqueue(2);
+
+// 先頭から順にループします。
+for (const value of queue) {
+  console.log(value); // 1, 2
+}
+
+// キューを配列に変換します。
+[...queue];
+// Returns: [1, 2]
+
+queue.size;
+// Returns: 2
+```
+
+#### プロパティ
+
+- `size` (`number`): キューに入っている値の数です。
+
+#### メソッド
+
+- `enqueue` (`(value: T) => void`): キューの末尾に値を追加します。
+- `dequeue` (`() => T | undefined`): キューの先頭の値を取り出して返します。キューが空の場合は `undefined` を返します。
+- `peek` (`() => T | undefined`): キューの先頭の値を取り出さずに返します。キューが空の場合は `undefined` を返します。
+- `clear` (`() => void`): キューのすべての値を削除します。
+- `[Symbol.iterator]` (`() => Generator<T>`): 値を取り出さずに先頭から順にループするイテレーターを返します。

docs/ko/reference/util/Queue.md

@@ -0,0 +1,69 @@
+# Queue
+
+먼저 넣은 값을 먼저 꺼내는(FIFO) 큐를 만들어요.
+
+```typescript
+const queue = new Queue<T>();
+```
+
+## 사용법
+
+### `Queue()`
+
+작업 목록이나 너비 우선 탐색처럼 들어온 순서대로 값을 처리해야 할 때 `Queue`를 사용하세요. `dequeue`, `enqueue` 메서드는 큐에 값이 아무리 많아도 빠르게 동작해요.
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<string>();
+
+// 큐의 맨 뒤에 값을 넣어요.
+queue.enqueue('a');
+queue.enqueue('b');
+queue.enqueue('c');
+
+// 큐의 맨 앞에서 값을 꺼내요.
+queue.dequeue();
+// Returns: 'a'
+
+// 맨 앞의 값을 꺼내지 않고 확인해요.
+queue.peek();
+// Returns: 'b'
+
+queue.size;
+// Returns: 2
+```
+
+큐는 이터러블이라서 `for...of`로 순회하거나 전개 구문으로 배열로 바꿀 수 있어요. 순회해도 값은 큐에서 사라지지 않아요.
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<number>();
+queue.enqueue(1);
+queue.enqueue(2);
+
+// 앞에서부터 순회해요.
+for (const value of queue) {
+  console.log(value); // 1, 2
+}
+
+// 큐를 배열로 바꿔요.
+[...queue];
+// Returns: [1, 2]
+
+queue.size;
+// Returns: 2
+```
+
+#### 프로퍼티
+
+- `size` (`number`): 큐에 들어 있는 값의 개수예요.
+
+#### 메서드
+
+- `enqueue` (`(value: T) => void`): 큐의 맨 뒤에 값을 넣어요.
+- `dequeue` (`() => T | undefined`): 큐의 맨 앞에 있는 값을 꺼내서 반환해요. 큐가 비어 있으면 `undefined`를 반환해요.
+- `peek` (`() => T | undefined`): 큐의 맨 앞에 있는 값을 꺼내지 않고 반환해요. 큐가 비어 있으면 `undefined`를 반환해요.
+- `clear` (`() => void`): 큐의 모든 값을 지워요.
+- `[Symbol.iterator]` (`() => Generator<T>`): 값을 꺼내지 않고 앞에서부터 순회하는 이터레이터를 반환해요.

docs/reference/util/Queue.md

@@ -0,0 +1,69 @@
+# Queue
+
+Creates a first-in, first-out (FIFO) queue.
+
+```typescript
+const queue = new Queue<T>();
+```
+
+## Usage
+
+### `Queue()`
+
+Use `Queue` when you process items in the order they arrive, such as task lists or breadth-first search. The `dequeue` and `enqueue` methods stay fast no matter how many items are in the queue.
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<string>();
+
+// Adds items to the back of the queue.
+queue.enqueue('a');
+queue.enqueue('b');
+queue.enqueue('c');
+
+// Removes items from the front of the queue.
+queue.dequeue();
+// Returns: 'a'
+
+// Looks at the front item without removing it.
+queue.peek();
+// Returns: 'b'
+
+queue.size;
+// Returns: 2
+```
+
+The queue is iterable, so you can loop over it with `for...of` or spread it into an array. Iterating does not remove items.
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<number>();
+queue.enqueue(1);
+queue.enqueue(2);
+
+// Loops from front to back.
+for (const value of queue) {
+  console.log(value); // 1, 2
+}
+
+// Spreads the queue into an array.
+[...queue];
+// Returns: [1, 2]
+
+queue.size;
+// Returns: 2
+```
+
+#### Properties
+
+- `size` (`number`): The number of items in the queue.
+
+#### Methods
+
+- `enqueue` (`(value: T) => void`): Adds an item to the back of the queue.
+- `dequeue` (`() => T | undefined`): Removes and returns the item at the front of the queue. Returns `undefined` if the queue is empty.
+- `peek` (`() => T | undefined`): Returns the item at the front of the queue without removing it. Returns `undefined` if the queue is empty.
+- `clear` (`() => void`): Removes all items from the queue.
+- `[Symbol.iterator]` (`() => Generator<T>`): Returns an iterator over the items from front to back, without removing them.

docs/zh_hans/reference/util/Queue.md

@@ -0,0 +1,69 @@
+# Queue
+
+创建一个先进先出(FIFO)的队列。
+
+```typescript
+const queue = new Queue<T>();
+```
+
+## 用法
+
+### `Queue()`
+
+当需要按照到达顺序处理值时(例如任务列表或广度优先搜索),请使用 `Queue`。`dequeue` 和 `enqueue` 方法无论队列中有多少值都能保持快速。
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<string>();
+
+// 在队列末尾添加值。
+queue.enqueue('a');
+queue.enqueue('b');
+queue.enqueue('c');
+
+// 从队列开头取出值。
+queue.dequeue();
+// Returns: 'a'
+
+// 查看开头的值但不取出。
+queue.peek();
+// Returns: 'b'
+
+queue.size;
+// Returns: 2
+```
+
+队列是可迭代的,因此可以用 `for...of` 遍历,或用展开语法转换为数组。遍历不会从队列中移除值。
+
+```typescript
+import { Queue } from 'es-toolkit/util';
+
+const queue = new Queue<number>();
+queue.enqueue(1);
+queue.enqueue(2);
+
+// 从开头依次遍历。
+for (const value of queue) {
+  console.log(value); // 1, 2
+}
+
+// 将队列转换为数组。
+[...queue];
+// Returns: [1, 2]
+
+queue.size;
+// Returns: 2
+```
+
+#### 属性
+
+- `size` (`number`): 队列中值的数量。
+
+#### 方法
+
+- `enqueue` (`(value: T) => void`): 在队列末尾添加值。
+- `dequeue` (`() => T | undefined`): 取出并返回队列开头的值。队列为空时返回 `undefined`。
+- `peek` (`() => T | undefined`): 返回队列开头的值但不取出。队列为空时返回 `undefined`。
+- `clear` (`() => void`): 移除队列中的所有值。
+- `[Symbol.iterator]` (`() => Generator<T>`): 返回一个从开头依次遍历且不取出值的迭代器。

src/util/index.ts

@@ -4,4 +4,5 @@ export { defer } from './defer.ts';
 export { deferAsync } from './deferAsync.ts';
 export { invariant } from './invariant.ts';
 export { invariant as assert } from './invariant.ts';
+export { Queue } from './queue.ts';
 export { serialize } from './serialize/serialize.ts';