@d-zero/dealer 1.5.3 → 1.6.0

package/README.md

@@ -10,16 +10,14 @@ npm install @d-zero/dealer
 
 ## API
 
+### 基本的な使い方
+
 ```ts
 import { deal } from '@d-zero/dealer';
 
-await deal(items, {
-	limit: 30,
-	header: (progress, done, total, limit) =>
-		progress === 1
-			? 'HeaderMessage: Done!'
-			: `HeaderMessage: %earth% %dots% %block% %propeller%`,
-	setup: (item, update, index) => {
+await deal(
+	items,
+	(item, update, index, setLineHeader, push) => {
 		item.setup();
 		item.addListeners((state) => {
 			update(`item(${index}): ${state}`);
@@ -30,5 +28,268 @@ await deal(items, {
 			item.cleanup();
 		};
 	},
+	{
+		limit: 30,
+		header: (progress, done, total, limit) =>
+			progress === 1
+				? 'HeaderMessage: Done!'
+				: `HeaderMessage: %earth% %dots% %block% %propeller%`,
+	},
+);
+```
+
+### deal関数
+
+コレクションを並列処理し、ログを順次出力します。
+
+#### シグネチャ
+
+```ts
+async function deal<T extends WeakKey>(
+	items: readonly T[],
+	setup: (
+		process: T,
+		update: (log: string) => void,
+		index: number,
+		setLineHeader: (lineHeader: string) => void,
+		push: (...items: T[]) => Promise<void>,
+	) => Promise<() => void | Promise<void>> | (() => void | Promise<void>),
+	options?: DealOptions,
+): Promise<void>;
+```
+
+#### パラメータ
+
+- `items`: 処理対象のアイテムのコレクション
+- `setup`: 各アイテムを初期化し、開始関数を返す関数
+  - `process`: 現在処理中のアイテム
+  - `update`: ログを更新する関数
+  - `index`: アイテムのインデックス
+  - `setLineHeader`: ログの各行にプレフィックスを設定する関数
+  - `push`: 実行中にアイテムをキューに追加する関数
+  - 戻り値: アイテムを開始する関数
+- `options`: 設定オプション
+
+#### 実行フロー
+
+1. `dealer.play()` が並列処理を開始
+2. 各ワーカーについて:
+   - `start()` 関数が呼び出される(アイテムが開始)
+   - **インターバル遅延が実行される**(options.intervalが指定されている場合)
+     - 待機ログが `%countdown()` 形式で出力される
+     - これはアイテム開始**後**、最初の出力の**前**に発生
+   - 実際の処理が始まる(ユーザーコードからの最初の `update()` 呼び出し)
+
+### DealOptions型
+
+```ts
+type DealOptions = DealerOptions &
+	LanesOptions & {
+		readonly header?: DealHeader;
+		readonly debug?: boolean;
+		readonly interval?: number | DelayOptions;
+	};
+```
+
+#### プロパティ
+
+- `limit?: number`: 同時実行数の制限(デフォルト: 10)
+- `onPush?: (item: T) => boolean`: `push()`時のフィルタ関数。`false`を返すとそのアイテムは拒否される(例: 重複排除)
+- `header?: DealHeader`: 進捗ヘッダーを生成する関数
+- `debug?: boolean`: デバッグログを表示するかどうか
+- `interval?: number | DelayOptions`: 各処理の間隔(ミリ秒またはDelayOptions)
+- `animations?: Animations`: アニメーション定義
+- `fps?: FPS`: フレームレート(12, 24, 30, 60)
+- `indent?: string`: ログのインデント文字列
+- `sort?: (a: [number, string], b: [number, string]) => number`: ログのソート関数
+- `verbose?: boolean`: 詳細ログモード
+
+### DealHeader型
+
+進捗情報をヘッダー文字列に変換する関数型です。
+
+```ts
+type DealHeader = (
+	progress: number,
+	done: number,
+	total: number,
+	limit: number,
+) => string;
+```
+
+#### パラメータ
+
+- `progress`: 進捗率(0〜1)
+- `done`: 完了したアイテム数
+- `total`: 総アイテム数
+- `limit`: 同時実行数制限
+
+#### 戻り値
+
+ヘッダーとして表示する文字列。アニメーション変数(`%earth%`, `%dots%`など)を含めることができます。
+
+### Dealerクラス
+
+並列処理を制御するクラスです。
+
+#### コンストラクタ
+
+```ts
+constructor(items: readonly T[], options?: DealerOptions)
+```
+
+- `items`: 処理対象のアイテム
+- `options.limit`: 同時実行数の制限(デフォルト: 10)
+- `options.onPush`: `push()`時のフィルタ関数
+
+#### メソッド
+
+##### debug(listener: (log: string) => void)
+
+デバッグログのリスナーを設定します。
+
+```ts
+dealer.debug((log) => {
+	console.log(`[DEBUG]: ${log}`);
+});
+```
+
+##### finish(listener: () => void)
+
+すべての処理が完了したときのリスナーを設定します。
+
+```ts
+dealer.finish(() => {
+	console.log('All done!');
+});
+```
+
+##### play()
+
+並列処理を開始します。
+
+```ts
+dealer.play();
+```
+
+##### progress(listener: (progress: number, done: number, total: number, limit: number) => void)
+
+進捗更新のリスナーを設定します。
+
+```ts
+dealer.progress((progress, done, total, limit) => {
+	console.log(`Progress: ${(progress * 100).toFixed(1)}% (${done}/${total})`);
+});
+```
+
+##### async push(...items: T[])
+
+実行中にアイテムをキューに追加します。追加されたアイテムには`setup()`で設定した初期化関数が自動適用されます。完了後の呼び出しは無視されます。
+
+```ts
+await dealer.push(newItem1, newItem2);
+```
+
+- `items`: 追加するアイテム。`onPush`が設定されている場合、`false`を返したアイテムはスキップされます。
+
+##### async setup(initializer: ProcessInitializer<T>)
+
+各アイテムの初期化関数を設定します。
+
+```ts
+await dealer.setup(async (item, index) => {
+	// 初期化処理
+	return async () => {
+		// 実行処理
+	};
 });
 ```
+
+- `initializer`: 各アイテムを初期化し、開始関数を返す関数
+  - `process`: 現在のアイテム
+  - `index`: アイテムのインデックス
+  - 戻り値: アイテムを開始する非同期関数
+
+### Lanesクラス
+
+複数のログラインを管理し、順序付きで表示するクラスです。
+
+#### コンストラクタ
+
+```ts
+constructor(options?: LanesOptions)
+```
+
+- `options.animations`: アニメーション定義
+- `options.fps`: フレームレート(12, 24, 30, 60)
+- `options.indent`: ログのインデント文字列
+- `options.sort`: ログのソート関数
+- `options.verbose`: 詳細ログモード(true の場合、ログをクリアせずに追加表示)
+
+#### メソッド
+
+##### clear(options?: { header?: boolean })
+
+すべてのログをクリアします。
+
+```ts
+lanes.clear(); // ログのみクリア
+lanes.clear({ header: true }); // ヘッダーもクリア
+```
+
+- `options.header`: ヘッダーもクリアするかどうか(デフォルト: false)
+
+注: verboseモードでは何もしません。
+
+##### close()
+
+ディスプレイを閉じます。
+
+```ts
+lanes.close();
+```
+
+##### delete(id: number)
+
+指定したIDのログを削除します。
+
+```ts
+lanes.delete(42);
+```
+
+- `id`: 削除するログのID
+
+注: verboseモードでは何もしません。
+
+##### header(text: string)
+
+ヘッダーテキストを設定します。
+
+```ts
+lanes.header('Processing items...');
+```
+
+- `text`: ヘッダーとして表示するテキスト
+
+##### update(id: number, log: string)
+
+指定したIDのログを更新します。
+
+```ts
+lanes.update(42, 'Item 42: Processing...');
+```
+
+- `id`: 更新するログのID
+- `log`: ログメッセージ
+
+注: verboseモードでは、ヘッダーとログを連結して即座に出力します。
+
+##### write()
+
+現在のログをすべて表示します。
+
+```ts
+lanes.write();
+```
+
+注: verboseモードでは何もしません。通常モードでは、ソート後のログをヘッダーと共に出力します。

package/dist/deal.d.ts

@@ -41,4 +41,4 @@ export type DealHeader = (progress: number, done: number, total: number, limit:
  * @param options - Configuration options including interval delay
  * @returns Promise that resolves when all items are processed
  */
-export declare function deal<T extends WeakKey>(items: readonly T[], setup: (process: T, update: (log: string) => void, index: number, setLineHeader: (lineHeader: string) => void) => Promise<() => void | Promise<void>> | (() => void | Promise<void>), options?: DealOptions): Promise<void>;
+export declare function deal<T extends WeakKey>(items: readonly T[], setup: (process: T, update: (log: string) => void, index: number, setLineHeader: (lineHeader: string) => void, push: (...items: T[]) => Promise<void>) => Promise<() => void | Promise<void>> | (() => void | Promise<void>), options?: DealOptions): Promise<void>;

package/dist/deal.js

@@ -50,7 +50,8 @@ export async function deal(items, setup, options) {
             lineHeader = header;
         };
         const update = (log) => lanes.update(index, lineHeader + log);
-        const start = await setup(process, update, index, setLineHeader);
+        const push = (...newItems) => dealer.push(...newItems);
+        const start = await setup(process, update, index, setLineHeader, push);
         return async () => {
             await delay(options?.interval ?? 0, (determinedInterval) => {
                 update(`Waiting interval: %countdown(${determinedInterval},${index}_interval)%ms`);

package/dist/dealer.d.ts

@@ -1,6 +1,7 @@
 import type { ProcessInitializer } from './types.js';
 export interface DealerOptions {
     limit?: number;
+    onPush?: (item: never) => boolean;
 }
 export declare class Dealer<T extends WeakKey> {
     #private;
@@ -9,5 +10,6 @@ export declare class Dealer<T extends WeakKey> {
     finish(listener: () => void): void;
     play(): void;
     progress(listener: (progress: number, done: number, total: number, limit: number) => void): void;
+    push(...items: T[]): Promise<void>;
     setup(initializer: ProcessInitializer<T>): Promise<void>;
 }

package/dist/dealer.js

@@ -3,14 +3,20 @@ export class Dealer {
     #done = new WeakSet();
     #doneCount = 0;
     #finish = () => { };
+    #finished = false;
+    #initializer = null;
     #items;
     #limit;
+    #nextIndex = 0;
+    #onPush;
+    #pendingInitCount = 0;
     #progress = () => { };
     #starts = new WeakMap();
     #workers = new Set();
     constructor(items, options) {
-        this.#items = items;
+        this.#items = [...items];
         this.#limit = options?.limit ?? 10;
+        this.#onPush = options?.onPush;
     }
     debug(listener) {
         this.#debug = listener;
@@ -24,18 +30,35 @@ export class Dealer {
     progress(listener) {
         this.#progress = listener;
     }
+    async push(...items) {
+        if (this.#finished) {
+            return;
+        }
+        for (const item of items) {
+            if (this.#onPush && !this.#onPush(item)) {
+                continue;
+            }
+            this.#pendingInitCount++;
+            await this.#initializeAndDispatch(item);
+        }
+    }
     async setup(initializer) {
-        for (const [index, item] of this.#items.entries()) {
-            const start = await initializer(item, index);
+        this.#initializer = initializer;
+        for (const item of this.#items) {
+            const start = await initializer(item, this.#nextIndex++);
             this.#starts.set(item, async () => await start());
         }
-        this.#progress(this.#doneCount / this.#items.length, this.#doneCount, this.#items.length, this.#limit);
+        const total = this.#items.length;
+        this.#progress(total === 0 ? 0 : this.#doneCount / total, this.#doneCount, total, this.#limit);
     }
     #deal() {
-        this.#debug(`Done: ${this.#doneCount}/${this.#items.length} (Limit: ${this.#limit})`);
-        this.#progress(this.#doneCount / this.#items.length, this.#doneCount, this.#items.length, this.#limit);
-        if (this.#doneCount === this.#items.length) {
+        const total = this.#items.length;
+        this.#debug(`Done: ${this.#doneCount}/${total} (Limit: ${this.#limit})`);
+        this.#progress(total === 0 ? 0 : this.#doneCount / total, this.#doneCount, total, this.#limit);
+        if (total > 0 && this.#doneCount === total && this.#pendingInitCount === 0) {
+            this.#finished = true;
             this.#finish();
+            return;
         }
         while (this.#workers.size < this.#limit) {
             const worker = this.#draw();
@@ -67,4 +90,14 @@ export class Dealer {
         }
         return null;
     }
+    async #initializeAndDispatch(item) {
+        if (!this.#initializer) {
+            throw new Error('setup() must be called before push()');
+        }
+        const start = await this.#initializer(item, this.#nextIndex++);
+        this.#starts.set(item, async () => await start());
+        this.#items.push(item);
+        this.#pendingInitCount--;
+        this.#deal();
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/dealer",
-	"version": "1.5.3",
+	"version": "1.6.0",
 	"description": "A tool that provides an API and CLI for parallel processing of collections and sequential logging to standard output",
 	"author": "D-ZERO",
 	"license": "MIT",
@@ -23,8 +23,8 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/shared": "0.17.1",
+		"@d-zero/shared": "0.18.0",
 		"ansi-colors": "4.1.3"
 	},
-	"gitHead": "c976f890ac4225e20df8fc83118f31231bd6323c"
+	"gitHead": "a6d7b36c485bbc0782375c6e1ad0d0606f423e97"
 }