@d-zero/dealer 1.6.3 → 1.6.5

package/README.md

@@ -80,6 +80,23 @@ async function deal<T extends WeakKey>(
      - これはアイテム開始**後**、最初の出力の**前**に発生
    - 実際の処理が始まる(ユーザーコードからの最初の `update()` 呼び出し)
 
+#### エラーハンドリング
+
+ワーカー（`start()`関数）がエラーを投げた場合、残りのワーカーの処理は継続されます。すべてのワーカーが完了（成功または失敗）した後、1つ以上のエラーがあれば`AggregateError`でrejectされます。
+
+```ts
+try {
+	await deal(items, setup, options);
+} catch (error) {
+	if (error instanceof AggregateError) {
+		console.error(`${error.errors.length} workers failed:`);
+		for (const e of error.errors) {
+			console.error(e);
+		}
+	}
+}
+```
+
 ### DealOptions型
 
 ```ts
@@ -101,7 +118,7 @@ type DealOptions<T = unknown> = DealerOptions<T> &
 - `animations?: Animations`: アニメーション定義
 - `fps?: FPS`: フレームレート(12, 24, 30, 60)
 - `indent?: string`: ログのインデント文字列
-- `sort?: (a: [number, string], b: [number, string]) => number`: ログのソート関数
+- `sort?: (a: readonly [number, string], b: readonly [number, string]) => number`: ログのソート関数
 - `verbose?: boolean`: 詳細ログモード
 
 ### DealHeader型
@@ -120,7 +137,7 @@ type DealHeader = (
 #### パラメータ
 
 - `progress`: 進捗率(0〜1)
-- `done`: 完了したアイテム数
+- `done`: 処理済みアイテム数（エラーで失敗したアイテムを含む）
 - `total`: 総アイテム数
 - `limit`: 同時実行数制限
 
@@ -142,6 +159,19 @@ constructor(items: readonly T[], options?: DealerOptions<T>)
 - `options.limit`: 同時実行数の制限(デフォルト: 10)
 - `options.onPush`: `push()`時のフィルタ関数
 
+#### プロパティ
+
+##### get errors(): ReadonlyArray<{ item: T; error: unknown }>
+
+ワーカーの実行中に発生したエラーの一覧を返します。各エントリにはエラーを起こしたアイテムとエラーオブジェクトが含まれます。
+
+```ts
+await runDealer(dealer);
+for (const { item, error } of dealer.errors) {
+	console.error('Failed item:', item, error);
+}
+```
+
 #### メソッド
 
 ##### debug(listener: (log: string) => void)

package/dist/deal.d.ts

@@ -1,11 +1,28 @@
 import type { DealerOptions } from './dealer.js';
 import type { LanesOptions } from './lanes.js';
 import type { DelayOptions } from '@d-zero/shared/delay';
+/**
+ * Configuration options for the {@link deal} function.
+ * Combines {@link DealerOptions} (concurrency), {@link LanesOptions} (display),
+ * and deal-specific options (header, debug, interval).
+ * @template T - The type of items being processed
+ */
 export type DealOptions<T = unknown> = DealerOptions<T> & LanesOptions & {
+    /** Function to generate the progress header string */
     readonly header?: DealHeader;
+    /** Whether to display debug log output */
     readonly debug?: boolean;
+    /** Delay between each worker start, in milliseconds or as a DelayOptions object */
     readonly interval?: number | DelayOptions;
 };
+/**
+ * Function type that converts progress information into a header string for display.
+ * @param progress - Progress ratio from 0 to 1
+ * @param done - Number of processed items (including errors)
+ * @param total - Total number of items
+ * @param limit - Concurrency limit
+ * @returns Header string to display. May include animation variables like `%earth%`, `%dots%`.
+ */
 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 +53,16 @@ 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
+ * @template T - The type of items to process, must extend WeakKey
  * @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
+ * @param setup - Function that initializes each item and returns a start function.
+ *   Receives the item, an update callback for logging, the item index,
+ *   a setLineHeader callback for log prefixes, and a push callback to add items dynamically.
+ *   Must return a start function that performs the actual work.
+ * @param options - Configuration options including concurrency limit, interval delay, and display settings
+ * @returns Promise that resolves when all items are processed successfully
+ * @throws {AggregateError} When one or more workers throw errors. All workers run to
+ *   completion regardless of individual failures. The AggregateError.errors array
+ *   contains the original errors from each failed worker.
  */
 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,17 @@ 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
+ * @template T - The type of items to process, must extend WeakKey
  * @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
+ * @param setup - Function that initializes each item and returns a start function.
+ *   Receives the item, an update callback for logging, the item index,
+ *   a setLineHeader callback for log prefixes, and a push callback to add items dynamically.
+ *   Must return a start function that performs the actual work.
+ * @param options - Configuration options including concurrency limit, interval delay, and display settings
+ * @returns Promise that resolves when all items are processed successfully
+ * @throws {AggregateError} When one or more workers throw errors. All workers run to
+ *   completion regardless of individual failures. The AggregateError.errors array
+ *   contains the original errors from each failed worker.
  */
 export async function deal(items, setup, options) {
     const dealer = new Dealer(items, options);
@@ -56,8 +63,12 @@ export async function deal(items, setup, options) {
             await delay(options?.interval ?? 0, (determinedInterval) => {
                 update(`Waiting interval: %countdown(${determinedInterval},${index}_interval)%ms`);
             });
-            await start();
-            lanes.delete(index);
+            try {
+                await start();
+            }
+            finally {
+                lanes.delete(index);
+            }
         };
     });
     if (options?.debug) {
@@ -65,10 +76,15 @@ export async function deal(items, setup, options) {
             lanes.update(DEBUG_ID, `[DEBUG]: ${log}`);
         });
     }
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         dealer.finish(() => {
             lanes.close();
-            resolve();
+            if (dealer.errors.length > 0) {
+                reject(new AggregateError(dealer.errors.map((e) => e.error), `${dealer.errors.length} worker(s) failed`));
+            }
+            else {
+                resolve();
+            }
         });
         dealer.play();
     });

package/dist/dealer.d.ts

@@ -1,15 +1,67 @@
 import type { ProcessInitializer } from './types.js';
+/**
+ * Configuration options for the {@link Dealer} class.
+ * @template T - The type of items being processed
+ */
 export interface DealerOptions<T = unknown> {
+    /** Maximum number of concurrent workers (default: 10) */
     limit?: number;
+    /** Filter function called when items are added via {@link Dealer.push}. Return `false` to reject the item. */
     onPush?: (item: T) => boolean;
 }
+/**
+ * Manages parallel processing of items with configurable concurrency limits.
+ *
+ * Items are dispatched to workers up to the configured limit. When a worker
+ * completes (successfully or with error), the next pending item is dispatched.
+ * Errors are collected and accessible via the `errors` property.
+ * @template T - The type of items to process, must extend WeakKey
+ */
 export declare class Dealer<T extends WeakKey> {
     #private;
+    /**
+     * Errors collected from failed workers during processing.
+     * @returns Array of objects containing the failed item and its error
+     */
+    get errors(): ReadonlyArray<{
+        item: T;
+        error: unknown;
+    }>;
+    /**
+     * @param items - Collection of items to process
+     * @param options - Configuration options
+     */
     constructor(items: readonly T[], options?: DealerOptions<T>);
+    /**
+     * Sets a listener for debug log messages.
+     * @param listener - Callback invoked with debug log strings
+     */
     debug(listener: (log: string) => void): void;
+    /**
+     * Sets a listener called when all items have been processed (including failures).
+     * @param listener - Callback invoked on completion
+     */
     finish(listener: () => void): void;
+    /**
+     * Starts dispatching items to workers.
+     */
     play(): void;
+    /**
+     * Sets a listener for progress updates, called each time a worker completes.
+     * @param listener - Callback receiving progress ratio (0–1), done count (including errors), total count, and concurrency limit
+     */
     progress(listener: (progress: number, done: number, total: number, limit: number) => void): void;
+    /**
+     * Adds items to the processing queue during execution.
+     * Added items are initialized using the same initializer set via {@link setup}.
+     * Calls after all processing has finished are silently ignored.
+     * @param items - Items to add. If `onPush` is configured, items returning `false` are skipped.
+     */
     push(...items: T[]): Promise<void>;
+    /**
+     * Registers the initializer function and prepares all items for processing.
+     * Must be called before {@link play}.
+     * @param initializer - Function that receives each item and its index, returning a start function
+     */
     setup(initializer: ProcessInitializer<T>): Promise<void>;
 }

package/dist/dealer.js

@@ -1,7 +1,16 @@
+/**
+ * Manages parallel processing of items with configurable concurrency limits.
+ *
+ * Items are dispatched to workers up to the configured limit. When a worker
+ * completes (successfully or with error), the next pending item is dispatched.
+ * Errors are collected and accessible via the `errors` property.
+ * @template T - The type of items to process, must extend WeakKey
+ */
 export class Dealer {
     #debug = () => { };
     #done = new WeakSet();
     #doneCount = 0;
+    #errors = [];
     #finish = () => { };
     #finished = false;
     #initializer = null;
@@ -13,23 +22,55 @@ export class Dealer {
     #progress = () => { };
     #starts = new WeakMap();
     #workers = new Set();
+    /**
+     * Errors collected from failed workers during processing.
+     * @returns Array of objects containing the failed item and its error
+     */
+    get errors() {
+        return this.#errors;
+    }
+    /**
+     * @param items - Collection of items to process
+     * @param options - Configuration options
+     */
     constructor(items, options) {
         this.#items = [...items];
         this.#limit = options?.limit ?? 10;
         this.#onPush = options?.onPush;
     }
+    /**
+     * Sets a listener for debug log messages.
+     * @param listener - Callback invoked with debug log strings
+     */
     debug(listener) {
         this.#debug = listener;
     }
+    /**
+     * Sets a listener called when all items have been processed (including failures).
+     * @param listener - Callback invoked on completion
+     */
     finish(listener) {
         this.#finish = listener;
     }
+    /**
+     * Starts dispatching items to workers.
+     */
     play() {
         this.#deal();
     }
+    /**
+     * Sets a listener for progress updates, called each time a worker completes.
+     * @param listener - Callback receiving progress ratio (0–1), done count (including errors), total count, and concurrency limit
+     */
     progress(listener) {
         this.#progress = listener;
     }
+    /**
+     * Adds items to the processing queue during execution.
+     * Added items are initialized using the same initializer set via {@link setup}.
+     * Calls after all processing has finished are silently ignored.
+     * @param items - Items to add. If `onPush` is configured, items returning `false` are skipped.
+     */
     async push(...items) {
         if (this.#finished) {
             return;
@@ -42,6 +83,11 @@ export class Dealer {
             await this.#initializeAndDispatch(item);
         }
     }
+    /**
+     * Registers the initializer function and prepares all items for processing.
+     * Must be called before {@link play}.
+     * @param initializer - Function that receives each item and its index, returning a start function
+     */
     async setup(initializer) {
         this.#initializer = initializer;
         for (const item of this.#items) {
@@ -51,6 +97,12 @@ export class Dealer {
         const total = this.#items.length;
         this.#progress(total === 0 ? 0 : this.#doneCount / total, this.#doneCount, total, this.#limit);
     }
+    #completeWorker(worker) {
+        this.#workers.delete(worker);
+        this.#done.add(worker);
+        this.#doneCount++;
+        this.#deal();
+    }
     #deal() {
         const total = this.#items.length;
         this.#debug(`Done: ${this.#doneCount}/${total} (Limit: ${this.#limit})`);
@@ -70,11 +122,13 @@ export class Dealer {
             if (!start) {
                 throw new Error(`Didn't have a starting function`);
             }
-            void start().then(() => {
-                this.#workers.delete(worker);
-                this.#done.add(worker);
-                this.#doneCount++;
-                this.#deal();
+            void start()
+                .then(() => {
+                this.#completeWorker(worker);
+            })
+                .catch((error) => {
+                this.#errors.push({ item: worker, error });
+                this.#completeWorker(worker);
             });
         }
     }

package/dist/lanes.d.ts

@@ -1,23 +1,61 @@
 import type { Animations, FPS } from './types.js';
 type Log = readonly [id: number, message: string];
 type SortFunc = (a: Log, b: Log) => number;
+/** Configuration options for the {@link Lanes} display manager. */
 export type LanesOptions = {
+    /** Custom animation definitions to override or extend built-in presets */
     readonly animations?: Animations;
+    /** Frame rate for display rendering */
     readonly fps?: FPS;
+    /** Indent string prepended to each log line */
     readonly indent?: string;
+    /** Sort function for ordering log entries by their ID */
     readonly sort?: SortFunc;
+    /** When true, logs are appended line-by-line to stdout instead of being redrawn in-place */
     readonly verbose?: boolean;
 };
+/**
+ * Manages multiple concurrent log lines with ordered display output.
+ * Each log line is identified by a numeric ID and can be independently updated or deleted.
+ */
 export declare class Lanes {
     #private;
+    /**
+     * @param options - Display configuration options
+     */
     constructor(options?: LanesOptions);
+    /**
+     * Clears all log entries. No-op in verbose mode.
+     * @param options - Pass `{ header: true }` to also clear the header
+     * @param options.header
+     */
     clear(options?: {
         header?: boolean;
     }): void;
+    /**
+     * Closes the underlying display and releases resources.
+     */
     close(): void;
+    /**
+     * Removes the log entry with the given ID. No-op in verbose mode.
+     * @param id - The log entry ID to remove
+     */
     delete(id: number): void;
+    /**
+     * Sets the header text displayed above all log lines.
+     * @param text - Header text to display
+     */
     header(text: string): void;
+    /**
+     * Updates the log entry for the given ID. In verbose mode, immediately writes the header and log to stdout.
+     * @param id - The log entry ID
+     * @param log - The log message
+     */
     update(id: number, log: string): void;
+    /**
+     * Renders all current log entries to the display. No-op in verbose mode.
+     * Entries are sorted by the configured sort function before rendering.
+     */
     write(): void;
 }
 export {};

package/dist/lanes.js

@@ -1,5 +1,9 @@
 import { Display } from './display.js';
 const RESET = '\u001B[0m';
+/**
+ * Manages multiple concurrent log lines with ordered display output.
+ * Each log line is identified by a numeric ID and can be independently updated or deleted.
+ */
 export class Lanes {
     #display;
     #header;
@@ -7,6 +11,9 @@ export class Lanes {
     #logs = new Map();
     #sort = ([a], [b]) => a - b;
     #verbose;
+    /**
+     * @param options - Display configuration options
+     */
     constructor(options) {
         this.#display = new Display({
             animations: options?.animations,
@@ -17,6 +24,11 @@ export class Lanes {
         this.#sort = options?.sort ?? this.#sort;
         this.#verbose = options?.verbose ?? false;
     }
+    /**
+     * Clears all log entries. No-op in verbose mode.
+     * @param options - Pass `{ header: true }` to also clear the header
+     * @param options.header
+     */
     clear(options) {
         if (this.#verbose) {
             return;
@@ -27,9 +39,16 @@ export class Lanes {
         }
         this.write();
     }
+    /**
+     * Closes the underlying display and releases resources.
+     */
     close() {
         this.#display.close();
     }
+    /**
+     * Removes the log entry with the given ID. No-op in verbose mode.
+     * @param id - The log entry ID to remove
+     */
     delete(id) {
         if (this.#verbose) {
             return;
@@ -37,6 +56,10 @@ export class Lanes {
         this.#logs.delete(id);
         this.write();
     }
+    /**
+     * Sets the header text displayed above all log lines.
+     * @param text - Header text to display
+     */
     header(text) {
         this.#header = text;
         if (this.#verbose) {
@@ -44,6 +67,11 @@ export class Lanes {
         }
         this.write();
     }
+    /**
+     * Updates the log entry for the given ID. In verbose mode, immediately writes the header and log to stdout.
+     * @param id - The log entry ID
+     * @param log - The log message
+     */
     update(id, log) {
         if (this.#verbose) {
             this.#display.write(`${RESET}${this.#header}${RESET} ${log}`);
@@ -52,6 +80,10 @@ export class Lanes {
         this.#logs.set(id, log);
         this.write();
     }
+    /**
+     * Renders all current log entries to the display. No-op in verbose mode.
+     * Entries are sorted by the configured sort function before rendering.
+     */
     write() {
         if (this.#verbose) {
             return;

package/dist/types.d.ts

@@ -1,5 +1,14 @@
+/** Mapping of animation names to their frame rate and sprite sequences. */
 export type Animations = Record<string, [fps: number, ...sprites: string[]]>;
+/** Supported frame rates for display rendering. */
 export type FPS = 12 | 24 | 30 | 60;
+/**
+ * Function that initializes an item and returns its start function.
+ * @template T - The type of item being initialized
+ * @param process - The item to initialize
+ * @param index - The sequential index assigned to the item
+ * @returns A start function that performs the actual processing
+ */
 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.3",
+	"version": "1.6.5",
 	"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.20.0",
+		"@d-zero/shared": "0.20.1",
 		"ansi-colors": "4.1.3"
 	},
-	"gitHead": "11ddaf830a1ac0fd8c7c3247a21c3d69d91d8fbb"
+	"gitHead": "31410767ae6beff5c5dbe21a824406a4e6716868"
 }