@d-zero/dealer 1.3.2 → 1.4.0

package/dist/deal.d.ts

@@ -1,14 +1,44 @@
 import type { DealerOptions } from './dealer.js';
 import type { LanesOptions } from './lanes.js';
+import type { DelayOptions } from '@d-zero/shared/delay';
 export type DealOptions = DealerOptions & LanesOptions & {
     readonly header?: DealHeader;
     readonly debug?: boolean;
+    readonly interval?: number | DelayOptions;
 };
 export type DealHeader = (progress: number, done: number, total: number, limit: number) => string;
 /**
+ * Processes items in parallel with coordinated logging and optional interval delays.
  *
- * @param items
- * @param setup
- * @param options
+ * ## Architecture
+ *
+ * ### Execution Flow
+ * 1. `dealer.play()` initiates parallel processing
+ * 2. For each worker:
+ *    - `start()` function is called (item is started)
+ *    - **Interval delay executes** (if `options.interval` is specified)
+ *      - Wait log is output via `delay()` callback with `%countdown()` format
+ *      - This happens **after** the item starts but **before** its first output
+ *    - Actual processing begins (first `update()` call from user code)
+ *
+ * ### Interval Delay
+ * - Interval delay is executed **inside** the `start()` function, not before it
+ * - This ensures the item is started first, then waits before producing output
+ * - Wait log is automatically displayed using `%countdown()` format
+ * - The delay duration is determined synchronously before the delay starts
+ *
+ * ### Line Header Management
+ * - `setLineHeader()` allows setting a prefix string for all log lines of an item
+ * - Once set, all subsequent `update()` calls automatically prepend the line header
+ * - This enables consistent formatting across multiple log updates
+ *
+ * ### Wait Logging
+ * - 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
  */
-export declare function deal<T extends WeakKey>(items: readonly T[], setup: (process: T, update: (log: string) => void, index: number) => 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) => Promise<() => void | Promise<void>> | (() => void | Promise<void>), options?: DealOptions): Promise<void>;

package/dist/deal.js

@@ -1,11 +1,40 @@
+import { delay } from '@d-zero/shared/delay';
 import { Dealer } from './dealer.js';
 import { Lanes } from './lanes.js';
 const DEBUG_ID = Number.MIN_SAFE_INTEGER;
 /**
+ * Processes items in parallel with coordinated logging and optional interval delays.
  *
- * @param items
- * @param setup
- * @param options
+ * ## Architecture
+ *
+ * ### Execution Flow
+ * 1. `dealer.play()` initiates parallel processing
+ * 2. For each worker:
+ *    - `start()` function is called (item is started)
+ *    - **Interval delay executes** (if `options.interval` is specified)
+ *      - Wait log is output via `delay()` callback with `%countdown()` format
+ *      - This happens **after** the item starts but **before** its first output
+ *    - Actual processing begins (first `update()` call from user code)
+ *
+ * ### Interval Delay
+ * - Interval delay is executed **inside** the `start()` function, not before it
+ * - This ensures the item is started first, then waits before producing output
+ * - Wait log is automatically displayed using `%countdown()` format
+ * - The delay duration is determined synchronously before the delay starts
+ *
+ * ### Line Header Management
+ * - `setLineHeader()` allows setting a prefix string for all log lines of an item
+ * - Once set, all subsequent `update()` calls automatically prepend the line header
+ * - This enables consistent formatting across multiple log updates
+ *
+ * ### Wait Logging
+ * - 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
  */
 export async function deal(items, setup, options) {
     const dealer = new Dealer(items, options);
@@ -16,9 +45,16 @@ export async function deal(items, setup, options) {
         });
     }
     await dealer.setup(async (process, index) => {
-        const update = (log) => lanes.update(index, log);
-        const start = await setup(process, update, index);
+        let lineHeader = '';
+        const setLineHeader = (header) => {
+            lineHeader = header;
+        };
+        const update = (log) => lanes.update(index, lineHeader + log);
+        const start = await setup(process, update, index, setLineHeader);
         return async () => {
+            await delay(options?.interval ?? 0, (determinedInterval) => {
+                update(`Waiting interval: %countdown(${determinedInterval},${index}_interval)%ms`);
+            });
             await start();
             lanes.delete(index);
         };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/dealer",
-	"version": "1.3.2",
+	"version": "1.4.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,7 +23,8 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
+		"@d-zero/shared": "0.13.0",
 		"ansi-colors": "4.1.3"
 	},
-	"gitHead": "1218a023e62c79efeece6350d561f2e1906be7ea"
+	"gitHead": "85abd39686d2ce02c7b8db071437464d212dd982"
 }