@d-zero/dealer 1.6.4 → 1.7.0

package/README.md

@@ -38,6 +38,31 @@ await deal(
 );
 ```
 
+### キャンセル
+
+`AbortSignal`を渡すことで、処理を途中で中断できます。実行中のワーカーは完了まで待機し、新しいワーカーの起動のみが停止されます。
+
+```ts
+const controller = new AbortController();
+
+// 外部イベント（タイムアウトなど）でキャンセル
+setTimeout(() => controller.abort(), 30_000);
+
+await deal(
+	items,
+	(item, update, index) => {
+		return async () => {
+			update(`Processing item ${index}...`);
+			await item.process();
+		};
+	},
+	{
+		limit: 10,
+		signal: controller.signal,
+	},
+);
+```
+
 ### deal関数
 
 コレクションを並列処理し、ログを順次出力します。
@@ -95,6 +120,7 @@ type DealOptions<T = unknown> = DealerOptions<T> &
 
 - `limit?: number`: 同時実行数の制限(デフォルト: 10)
 - `onPush?: (item: T) => boolean`: `push()`時のフィルタ関数。`false`を返すとそのアイテムは拒否される(例: 重複排除)
+- `signal?: AbortSignal`: 処理のキャンセルに使用する`AbortSignal`。シグナルがabortされると新しいワーカーの起動を停止し、実行中のワーカーの完了を待ってから終了する
 - `header?: DealHeader`: 進捗ヘッダーを生成する関数
 - `debug?: boolean`: デバッグログを表示するかどうか
 - `interval?: number | DelayOptions`: 各処理の間隔(ミリ秒またはDelayOptions)
@@ -141,6 +167,7 @@ constructor(items: readonly T[], options?: DealerOptions<T>)
 - `items`: 処理対象のアイテム
 - `options.limit`: 同時実行数の制限(デフォルト: 10)
 - `options.onPush`: `push()`時のフィルタ関数
+- `options.signal`: 処理のキャンセルに使用する`AbortSignal`
 
 #### メソッド
 
@@ -184,7 +211,7 @@ dealer.progress((progress, done, total, limit) => {
 
 ##### async push(...items: T[])
 
-実行中にアイテムをキューに追加します。追加されたアイテムには`setup()`で設定した初期化関数が自動適用されます。完了後の呼び出しは無視されます。
+実行中にアイテムをキューに追加します。追加されたアイテムには`setup()`で設定した初期化関数が自動適用されます。処理完了後または`signal`がabort済みの場合、呼び出しは無視されます。
 
 ```ts
 await dealer.push(newItem1, newItem2);

package/dist/deal.d.ts

@@ -1,11 +1,26 @@
 import type { DealerOptions } from './dealer.js';
 import type { LanesOptions } from './lanes.js';
 import type { DelayOptions } from '@d-zero/shared/delay';
+/**
+ * {@link deal} 関数のオプション。
+ * {@link DealerOptions} と {@link LanesOptions} を合成し、
+ * ヘッダー・デバッグ・インターバルの設定を追加したもの。
+ * @template T - 処理対象アイテムの型
+ */
 export type DealOptions<T = unknown> = DealerOptions<T> & LanesOptions & {
     readonly header?: DealHeader;
     readonly debug?: boolean;
     readonly interval?: number | DelayOptions;
 };
+/**
+ * 進捗情報をヘッダー文字列に変換するコールバック型。
+ * 返却文字列にはアニメーション変数（`%earth%`, `%dots%` など）を含めることができる。
+ * @param progress - 進捗率（0〜1）
+ * @param done - 完了したアイテム数
+ * @param total - 総アイテム数
+ * @param limit - 同時実行数制限
+ * @returns ヘッダーとして表示する文字列
+ */
 export type DealHeader = (progress: number, done: number, total: number, limit: number) => string;
 /**
  * Processes items in parallel with coordinated logging and optional interval delays.
@@ -36,9 +51,20 @@ export type DealHeader = (progress: number, done: number, total: number, limit:
  * - All wait logs (including interval delay) are output via `delay()` callback
  * - This ensures the determined interval (even for random delays) is used for countdown
  * - The `%countdown()` function displays remaining time based on the actual delay duration
- * @param items - Collection of items to process
- * @param setup - Function that initializes each item and returns a start function
- * @param options - Configuration options including interval delay
- * @returns Promise that resolves when all items are processed
+ *
+ * ### Cancellation via AbortSignal
+ * - Pass `signal` option with an `AbortSignal` to enable cancellation
+ * - When the signal is aborted:
+ *   1. No new workers will be launched
+ *   2. Currently running workers will continue until they complete
+ *   3. `push()` calls after abort are silently ignored
+ *   4. The returned Promise resolves after all running workers finish
+ * - If the signal is already aborted before `play()`, the Promise resolves immediately
+ *   without processing any items
+ * @template T - 処理対象アイテムの型（WeakKey 制約）
+ * @param items - 処理対象のアイテムのコレクション
+ * @param setup - 各アイテムを初期化し、開始関数を返すコールバック
+ * @param options - 並列処理・ログ出力・インターバルの設定オプション
+ * @returns 全アイテムの処理完了またはキャンセル完了時に解決する Promise
  */
 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<T>): Promise<void>;

package/dist/deal.js

@@ -31,10 +31,21 @@ const DEBUG_ID = Number.MIN_SAFE_INTEGER;
  * - All wait logs (including interval delay) are output via `delay()` callback
  * - This ensures the determined interval (even for random delays) is used for countdown
  * - The `%countdown()` function displays remaining time based on the actual delay duration
- * @param items - Collection of items to process
- * @param setup - Function that initializes each item and returns a start function
- * @param options - Configuration options including interval delay
- * @returns Promise that resolves when all items are processed
+ *
+ * ### Cancellation via AbortSignal
+ * - Pass `signal` option with an `AbortSignal` to enable cancellation
+ * - When the signal is aborted:
+ *   1. No new workers will be launched
+ *   2. Currently running workers will continue until they complete
+ *   3. `push()` calls after abort are silently ignored
+ *   4. The returned Promise resolves after all running workers finish
+ * - If the signal is already aborted before `play()`, the Promise resolves immediately
+ *   without processing any items
+ * @template T - 処理対象アイテムの型（WeakKey 制約）
+ * @param items - 処理対象のアイテムのコレクション
+ * @param setup - 各アイテムを初期化し、開始関数を返すコールバック
+ * @param options - 並列処理・ログ出力・インターバルの設定オプション
+ * @returns 全アイテムの処理完了またはキャンセル完了時に解決する Promise
  */
 export async function deal(items, setup, options) {
     const dealer = new Dealer(items, options);

package/dist/dealer.d.ts

@@ -1,15 +1,67 @@
 import type { ProcessInitializer } from './types.js';
+/**
+ * {@link Dealer} のコンストラクタオプション。
+ * @template T - 処理対象アイテムの型
+ */
 export interface DealerOptions<T = unknown> {
+    /** 同時実行ワーカー数の上限。デフォルトは `10`。 */
     limit?: number;
+    /**
+     * {@link Dealer.push} 時に呼ばれるフィルタ関数。
+     * `false` を返すとそのアイテムはキューに追加されない。
+     * @param item - push されたアイテム
+     * @returns アイテムを受け入れる場合は `true`
+     */
     onPush?: (item: T) => boolean;
+    /**
+     * 処理のキャンセルに使用する `AbortSignal`。
+     * シグナルが abort されると新しいワーカーの起動を停止し、
+     * 実行中のワーカーの完了を待ってから終了する。
+     */
+    signal?: AbortSignal;
 }
+/**
+ * アイテムを並列処理するワーカープールマネージャー。
+ *
+ * 典型的な使用順序: {@link setup} → {@link finish} / {@link progress} → {@link play}。
+ * 処理中に {@link push} で動的にアイテムを追加できる。
+ * @template T - 処理対象アイテムの型（WeakKey 制約）
+ */
 export declare class Dealer<T extends WeakKey> {
     #private;
     constructor(items: readonly T[], options?: DealerOptions<T>);
+    /**
+     * デバッグログのリスナーを設定する。
+     * @param listener - デバッグメッセージを受け取るコールバック
+     */
     debug(listener: (log: string) => void): void;
+    /**
+     * 全アイテムの処理完了（またはキャンセル完了）時に呼ばれるリスナーを設定する。
+     * @param listener - 完了時に呼ばれるコールバック
+     */
     finish(listener: () => void): void;
+    /**
+     * 並列処理を開始する。
+     * {@link setup} を先に呼び出す必要がある。
+     */
     play(): void;
+    /**
+     * 進捗更新のリスナーを設定する。
+     * アイテムが完了するたびに呼び出される。
+     * @param listener - 進捗情報を受け取るコールバック
+     */
     progress(listener: (progress: number, done: number, total: number, limit: number) => void): void;
+    /**
+     * 実行中にアイテムをキューに追加する。
+     * 追加されたアイテムには {@link setup} で設定した初期化関数が自動適用される。
+     * 処理完了後または signal が abort 済みの場合、呼び出しは無視される。
+     * @param items - 追加するアイテム
+     */
     push(...items: T[]): Promise<void>;
+    /**
+     * 各アイテムの初期化関数を設定する。
+     * {@link play} を呼ぶ前に必ず呼び出すこと。
+     * @param initializer - 各アイテムを初期化し、実行関数を返すコールバック
+     */
     setup(initializer: ProcessInitializer<T>): Promise<void>;
 }

package/dist/dealer.js

@@ -1,3 +1,10 @@
+/**
+ * アイテムを並列処理するワーカープールマネージャー。
+ *
+ * 典型的な使用順序: {@link setup} → {@link finish} / {@link progress} → {@link play}。
+ * 処理中に {@link push} で動的にアイテムを追加できる。
+ * @template T - 処理対象アイテムの型（WeakKey 制約）
+ */
 export class Dealer {
     #debug = () => { };
     #done = new WeakSet();
@@ -11,27 +18,52 @@ export class Dealer {
     #onPush;
     #pendingInitCount = 0;
     #progress = () => { };
+    #signal;
     #starts = new WeakMap();
     #workers = new Set();
     constructor(items, options) {
         this.#items = [...items];
         this.#limit = options?.limit ?? 10;
         this.#onPush = options?.onPush;
+        this.#signal = options?.signal;
     }
+    /**
+     * デバッグログのリスナーを設定する。
+     * @param listener - デバッグメッセージを受け取るコールバック
+     */
     debug(listener) {
         this.#debug = listener;
     }
+    /**
+     * 全アイテムの処理完了（またはキャンセル完了）時に呼ばれるリスナーを設定する。
+     * @param listener - 完了時に呼ばれるコールバック
+     */
     finish(listener) {
         this.#finish = listener;
     }
+    /**
+     * 並列処理を開始する。
+     * {@link setup} を先に呼び出す必要がある。
+     */
     play() {
         this.#deal();
     }
+    /**
+     * 進捗更新のリスナーを設定する。
+     * アイテムが完了するたびに呼び出される。
+     * @param listener - 進捗情報を受け取るコールバック
+     */
     progress(listener) {
         this.#progress = listener;
     }
+    /**
+     * 実行中にアイテムをキューに追加する。
+     * 追加されたアイテムには {@link setup} で設定した初期化関数が自動適用される。
+     * 処理完了後または signal が abort 済みの場合、呼び出しは無視される。
+     * @param items - 追加するアイテム
+     */
     async push(...items) {
-        if (this.#finished) {
+        if (this.#finished || this.#signal?.aborted) {
             return;
         }
         for (const item of items) {
@@ -42,6 +74,11 @@ export class Dealer {
             await this.#initializeAndDispatch(item);
         }
     }
+    /**
+     * 各アイテムの初期化関数を設定する。
+     * {@link play} を呼ぶ前に必ず呼び出すこと。
+     * @param initializer - 各アイテムを初期化し、実行関数を返すコールバック
+     */
     async setup(initializer) {
         this.#initializer = initializer;
         for (const item of this.#items) {
@@ -52,6 +89,9 @@ export class Dealer {
         this.#progress(total === 0 ? 0 : this.#doneCount / total, this.#doneCount, total, this.#limit);
     }
     #deal() {
+        if (this.#finished) {
+            return;
+        }
         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);
@@ -60,6 +100,13 @@ export class Dealer {
             this.#finish();
             return;
         }
+        if (this.#signal?.aborted) {
+            if (this.#workers.size === 0) {
+                this.#finished = true;
+                this.#finish();
+            }
+            return;
+        }
         while (this.#workers.size < this.#limit) {
             const worker = this.#draw();
             if (!worker) {
@@ -95,9 +142,13 @@ export class Dealer {
             throw new Error('setup() must be called before push()');
         }
         const start = await this.#initializer(item, this.#nextIndex++);
+        this.#pendingInitCount--;
+        if (this.#signal?.aborted) {
+            this.#deal();
+            return;
+        }
         this.#starts.set(item, async () => await start());
         this.#items.push(item);
-        this.#pendingInitCount--;
         this.#deal();
     }
 }

package/dist/lanes.d.ts

@@ -1,6 +1,9 @@
 import type { Animations, FPS } from './types.js';
 type Log = readonly [id: number, message: string];
 type SortFunc = (a: Log, b: Log) => number;
+/**
+ * {@link Lanes} のコンストラクタオプション。
+ */
 export type LanesOptions = {
     readonly animations?: Animations;
     readonly fps?: FPS;
@@ -8,16 +11,46 @@ export type LanesOptions = {
     readonly sort?: SortFunc;
     readonly verbose?: boolean;
 };
+/**
+ * 複数のログラインを管理し、順序付きでターミナルに表示するクラス。
+ * verbose モードでは上書き表示ではなく追記出力を行う。
+ */
 export declare class Lanes {
     #private;
     constructor(options?: LanesOptions);
+    /**
+     * すべてのログをクリアする。verbose モードでは何もしない。
+     * @param options - クリアオプション
+     * @param options.header
+     */
     clear(options?: {
         header?: boolean;
     }): void;
+    /**
+     * ディスプレイを閉じ、リソースを解放する。
+     */
     close(): void;
+    /**
+     * 指定した ID のログを削除する。verbose モードでは何もしない。
+     * @param id - 削除するログの ID
+     */
     delete(id: number): void;
+    /**
+     * ヘッダーテキストを設定する。
+     * @param text - ヘッダーとして表示する文字列
+     */
     header(text: string): void;
+    /**
+     * 指定した ID のログを更新する。
+     * verbose モードではヘッダーとログを連結して即時出力する。
+     * @param id - 更新するログの ID
+     * @param log - ログメッセージ
+     */
     update(id: number, log: string): void;
+    /**
+     * 現在のログをソートしてターミナルに表示する。
+     * verbose モードでは何もしない。
+     */
     write(): void;
 }
 export {};

package/dist/lanes.js

@@ -1,5 +1,9 @@
 import { Display } from './display.js';
 const RESET = '\u001B[0m';
+/**
+ * 複数のログラインを管理し、順序付きでターミナルに表示するクラス。
+ * verbose モードでは上書き表示ではなく追記出力を行う。
+ */
 export class Lanes {
     #display;
     #header;
@@ -17,6 +21,11 @@ export class Lanes {
         this.#sort = options?.sort ?? this.#sort;
         this.#verbose = options?.verbose ?? false;
     }
+    /**
+     * すべてのログをクリアする。verbose モードでは何もしない。
+     * @param options - クリアオプション
+     * @param options.header
+     */
     clear(options) {
         if (this.#verbose) {
             return;
@@ -27,9 +36,16 @@ export class Lanes {
         }
         this.write();
     }
+    /**
+     * ディスプレイを閉じ、リソースを解放する。
+     */
     close() {
         this.#display.close();
     }
+    /**
+     * 指定した ID のログを削除する。verbose モードでは何もしない。
+     * @param id - 削除するログの ID
+     */
     delete(id) {
         if (this.#verbose) {
             return;
@@ -37,6 +53,10 @@ export class Lanes {
         this.#logs.delete(id);
         this.write();
     }
+    /**
+     * ヘッダーテキストを設定する。
+     * @param text - ヘッダーとして表示する文字列
+     */
     header(text) {
         this.#header = text;
         if (this.#verbose) {
@@ -44,6 +64,12 @@ export class Lanes {
         }
         this.write();
     }
+    /**
+     * 指定した ID のログを更新する。
+     * verbose モードではヘッダーとログを連結して即時出力する。
+     * @param id - 更新するログの ID
+     * @param log - ログメッセージ
+     */
     update(id, log) {
         if (this.#verbose) {
             this.#display.write(`${RESET}${this.#header}${RESET} ${log}`);
@@ -52,6 +78,10 @@ export class Lanes {
         this.#logs.set(id, log);
         this.write();
     }
+    /**
+     * 現在のログをソートしてターミナルに表示する。
+     * verbose モードでは何もしない。
+     */
     write() {
         if (this.#verbose) {
             return;

package/dist/types.d.ts

@@ -1,5 +1,20 @@
+/**
+ * アニメーション定義のマップ。
+ * キーはアニメーション名（`%name%` 形式でログ中に埋め込み可能）、
+ * 値は先頭が FPS、残りがスプライトフレームのタプル。
+ */
 export type Animations = Record<string, [fps: number, ...sprites: string[]]>;
+/**
+ * サポートされるフレームレート。
+ */
 export type FPS = 12 | 24 | 30 | 60;
+/**
+ * 各アイテムを初期化し、実行関数を返すコールバック。
+ * @template T - 処理対象アイテムの型
+ * @param process - 初期化対象のアイテム
+ * @param index - アイテムのインデックス（0始まり）
+ * @returns 処理を開始する関数を返す Promise
+ */
 export interface ProcessInitializer<T> {
     (process: T, index: number): Promise<() => Promise<void> | void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/dealer",
-	"version": "1.6.4",
+	"version": "1.7.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",
@@ -26,5 +26,5 @@
 		"@d-zero/shared": "0.20.1",
 		"ansi-colors": "4.1.3"
 	},
-	"gitHead": "a6b5eb0a0a327c003053f7c25be4c075ed319c76"
+	"gitHead": "866364294ddacc3095f65a9f8b488d40c4ccb904"
 }