@workglow/task-graph 0.0.86 → 0.0.87

package/dist/task/BatchTask.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type DataPortSchema } from "@workglow/util";
+import { IteratorTask, IteratorTaskConfig } from "./IteratorTask";
+import type { TaskInput, TaskOutput, TaskTypeName } from "./TaskTypes";
+/**
+ * Configuration for BatchTask.
+ */
+export interface BatchTaskConfig extends IteratorTaskConfig {
+    /**
+     * Number of items per batch.
+     * @default 10
+     */
+    readonly batchSize?: number;
+    /**
+     * Whether to flatten results from all batches into a single array.
+     * When false, results are grouped by batch.
+     * @default true
+     */
+    readonly flattenResults?: boolean;
+    /**
+     * Whether to execute batches in parallel or sequentially.
+     * @default "sequential"
+     */
+    readonly batchExecutionMode?: "parallel" | "sequential";
+}
+/**
+ * BatchTask processes an array in configurable chunks/batches.
+ *
+ * This task is useful for:
+ * - Rate-limited API calls that accept multiple items
+ * - Memory-constrained processing
+ * - Progress tracking at batch granularity
+ *
+ * ## Features
+ *
+ * - Groups array into chunks of batchSize
+ * - Runs inner workflow per batch (receives array of items)
+ * - Configurable batch and within-batch execution
+ * - Optional result flattening
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Process in batches of 10
+ * workflow
+ *   .input({ documents: [...100 docs...] })
+ *   .batch({ batchSize: 10 })
+ *     .bulkEmbed()
+ *     .bulkStore()
+ *   .endBatch()
+ *
+ * // Sequential batches for rate limiting
+ * workflow
+ *   .batch({ batchSize: 5, batchExecutionMode: "sequential" })
+ *     .apiCall()
+ *   .endBatch()
+ * ```
+ *
+ * @template Input - The input type containing the array to batch
+ * @template Output - The output type (collected batch results)
+ * @template Config - The configuration type
+ */
+export declare class BatchTask<Input extends TaskInput = TaskInput, Output extends TaskOutput = TaskOutput, Config extends BatchTaskConfig = BatchTaskConfig> extends IteratorTask<Input, Output, Config> {
+    static type: TaskTypeName;
+    static category: string;
+    static title: string;
+    static description: string;
+    /**
+     * BatchTask always uses PROPERTY_ARRAY merge strategy.
+     */
+    static readonly compoundMerge: "PROPERTY_ARRAY";
+    /**
+     * Static input schema for BatchTask.
+     */
+    static inputSchema(): DataPortSchema;
+    /**
+     * Static output schema for BatchTask.
+     */
+    static outputSchema(): DataPortSchema;
+    /**
+     * Gets the batch size.
+     */
+    get batchSize(): number;
+    /**
+     * Whether to flatten results from all batches.
+     */
+    get flattenResults(): boolean;
+    /**
+     * Batch execution mode.
+     */
+    get batchExecutionMode(): "parallel" | "sequential";
+    /**
+     * Override to group items into batches instead of individual items.
+     */
+    protected getIterableItems(input: Input): unknown[];
+    /**
+     * Groups items into batches of batchSize.
+     */
+    protected groupIntoBatches(items: unknown[]): unknown[][];
+    /**
+     * Creates iteration tasks for batches.
+     * Each batch receives the array of items for that batch.
+     */
+    protected createIterationTasks(batches: unknown[]): void;
+    /**
+     * Returns the empty result for BatchTask.
+     */
+    protected getEmptyResult(): Output;
+    /**
+     * Output schema for BatchTask.
+     * Similar to MapTask - wraps inner outputs in arrays.
+     */
+    outputSchema(): DataPortSchema;
+    /**
+     * Collects and optionally flattens results from all batches.
+     */
+    protected collectResults(results: TaskOutput[]): Output;
+    /**
+     * Regenerates the graph for batch execution.
+     */
+    regenerateGraph(): void;
+}
+declare module "../task-graph/Workflow" {
+    interface Workflow {
+        /**
+         * Starts a batch loop that processes arrays in chunks.
+         * Use .endBatch() to close the loop and return to the parent workflow.
+         *
+         * @param config - Configuration for the batch loop
+         * @returns A Workflow in loop builder mode for defining the batch processing
+         *
+         * @example
+         * ```typescript
+         * workflow
+         *   .batch({ batchSize: 10 })
+         *     .bulkProcess()
+         *   .endBatch()
+         * ```
+         */
+        batch: CreateLoopWorkflow<TaskInput, TaskOutput, BatchTaskConfig>;
+        /**
+         * Ends the batch loop and returns to the parent workflow.
+         * Only callable on workflows in loop builder mode.
+         *
+         * @returns The parent workflow
+         */
+        endBatch(): Workflow;
+    }
+}
+//# sourceMappingURL=BatchTask.d.ts.map

package/dist/task/BatchTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchTask.d.ts","sourceRoot":"","sources":["../../src/task/BatchTask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQrD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,SAAS,CACpB,KAAK,SAAS,SAAS,GAAG,SAAS,EACnC,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,MAAM,SAAS,eAAe,GAAG,eAAe,CAChD,SAAQ,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;IAC3C,OAAc,IAAI,EAAE,YAAY,CAAe;IAC/C,OAAc,QAAQ,EAAE,MAAM,CAAkB;IAChD,OAAc,KAAK,EAAE,MAAM,CAAW;IACtC,OAAc,WAAW,EAAE,MAAM,CAAgD;IAEjF;;OAEG;IACH,gBAAuB,aAAa,mBAAkB;IAEtD;;OAEG;WACW,WAAW,IAAI,cAAc;IAQ3C;;OAEG;WACW,YAAY,IAAI,cAAc;IAQ5C;;OAEG;IACH,IAAoB,SAAS,IAAI,MAAM,CAEtC;IAED;;OAEG;IACH,IAAW,cAAc,IAAI,OAAO,CAEnC;IAED;;OAEG;IACH,IAAW,kBAAkB,IAAI,UAAU,GAAG,YAAY,CAEzD;IAED;;OAEG;cACgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,EAAE;IAK5D;;OAEG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE;IAWzD;;;OAGG;cACgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI;IA0BjE;;OAEG;cACgB,cAAc,IAAI,MAAM;IAc3C;;;OAGG;IACa,YAAY,IAAI,cAAc;IAQ9C;;OAEG;cACgB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM;IAqBhE;;OAEG;IACa,eAAe,IAAI,IAAI;CAqBxC;AAMD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,QAAQ;QAChB;;;;;;;;;;;;;;WAcG;QAEH,KAAK,EAAE,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;QAElE;;;;;WAKG;QACH,QAAQ,IAAI,QAAQ,CAAC;KACtB;CACF"}

package/dist/task/ForEachTask.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DataPortSchema } from "@workglow/util";
+import { IteratorTask, IteratorTaskConfig } from "./IteratorTask";
+import type { TaskInput, TaskOutput, TaskTypeName } from "./TaskTypes";
+/**
+ * Configuration for ForEachTask.
+ */
+export interface ForEachTaskConfig extends IteratorTaskConfig {
+    /**
+     * Whether to collect and return results from each iteration.
+     * When false (default), ForEachTask is optimized for side effects.
+     * When true, results are collected but not transformed.
+     * @default false
+     */
+    readonly shouldCollectResults?: boolean;
+}
+/**
+ * ForEachTask iterates over an array and runs a workflow for each element.
+ *
+ * This task is optimized for side-effect operations where the primary goal
+ * is to process each item rather than collect transformed results.
+ * For transformations that collect results, use MapTask instead.
+ *
+ * ## Features
+ *
+ * - Iterates over array input
+ * - Runs inner workflow for each element
+ * - Configurable execution modes (parallel, sequential, etc.)
+ * - Optimized for side effects (default: doesn't collect results)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Using Workflow API
+ * workflow
+ *   .input({ items: ["a", "b", "c"] })
+ *   .forEach()
+ *     .processItem()
+ *     .saveToDatabase()
+ *   .endForEach()
+ *
+ * // With sequential execution
+ * workflow
+ *   .forEach({ executionMode: "sequential" })
+ *     .processItem()
+ *   .endForEach()
+ * ```
+ *
+ * @template Input - The input type containing the array to iterate
+ * @template Output - The output type (typically empty for side-effect operations)
+ * @template Config - The configuration type
+ */
+export declare class ForEachTask<Input extends TaskInput = TaskInput, Output extends TaskOutput = TaskOutput, Config extends ForEachTaskConfig = ForEachTaskConfig> extends IteratorTask<Input, Output, Config> {
+    static type: TaskTypeName;
+    static category: string;
+    static title: string;
+    static description: string;
+    /**
+     * Static input schema for ForEachTask.
+     * Accepts any object with at least one array property.
+     */
+    static inputSchema(): DataPortSchema;
+    /**
+     * Static output schema for ForEachTask.
+     * By default, returns an empty object (side-effect focused).
+     */
+    static outputSchema(): DataPortSchema;
+    /**
+     * Whether to collect results from iterations.
+     */
+    get shouldCollectResults(): boolean;
+    /**
+     * Returns the empty result for ForEachTask.
+     * Indicates completion with zero items processed.
+     */
+    protected getEmptyResult(): Output;
+    /**
+     * Output schema for ForEachTask instance.
+     * If shouldCollectResults is enabled, wraps inner output in arrays.
+     * Otherwise, returns the simple completion status schema.
+     */
+    outputSchema(): DataPortSchema;
+    /**
+     * Collects results from all iterations.
+     * For ForEachTask, this primarily returns completion status.
+     */
+    protected collectResults(results: TaskOutput[]): Output;
+}
+declare module "../task-graph/Workflow" {
+    interface Workflow {
+        /**
+         * Starts a forEach loop that iterates over an array.
+         * Use .endForEach() to close the loop and return to the parent workflow.
+         *
+         * @param config - Configuration for the forEach loop
+         * @returns A Workflow in loop builder mode for defining the loop body
+         *
+         * @example
+         * ```typescript
+         * workflow
+         *   .forEach({ executionMode: "sequential" })
+         *     .processItem()
+         *   .endForEach()
+         * ```
+         */
+        forEach: CreateLoopWorkflow<TaskInput, TaskOutput, ForEachTaskConfig>;
+        /**
+         * Ends the forEach loop and returns to the parent workflow.
+         * Only callable on workflows in loop builder mode.
+         *
+         * @returns The parent workflow
+         */
+        endForEach(): Workflow;
+    }
+}
+//# sourceMappingURL=ForEachTask.d.ts.map

package/dist/task/ForEachTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForEachTask.d.ts","sourceRoot":"","sources":["../../src/task/ForEachTask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMrD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,WAAW,CACtB,KAAK,SAAS,SAAS,GAAG,SAAS,EACnC,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,MAAM,SAAS,iBAAiB,GAAG,iBAAiB,CACpD,SAAQ,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;IAC3C,OAAc,IAAI,EAAE,YAAY,CAAiB;IACjD,OAAc,QAAQ,EAAE,MAAM,CAAkB;IAChD,OAAc,KAAK,EAAE,MAAM,CAAc;IACzC,OAAc,WAAW,EAAE,MAAM,CAAiE;IAElG;;;OAGG;WACW,WAAW,IAAI,cAAc;IAQ3C;;;OAGG;WACW,YAAY,IAAI,cAAc;IAmB5C;;OAEG;IACH,IAAW,oBAAoB,IAAI,OAAO,CAEzC;IAED;;;OAGG;cACgB,cAAc,IAAI,MAAM;IAO3C;;;;OAIG;IACa,YAAY,IAAI,cAAc;IAU9C;;;OAGG;cACgB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM;CAYjE;AAMD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,QAAQ;QAChB;;;;;;;;;;;;;;WAcG;QACH,OAAO,EAAE,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC;QAEtE;;;;;WAKG;QACH,UAAU,IAAI,QAAQ,CAAC;KACxB;CACF"}

package/dist/task/IteratorTask.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DataPortSchema } from "@workglow/util";
+import { TaskGraph } from "../task-graph/TaskGraph";
+import { GraphAsTask, GraphAsTaskConfig } from "./GraphAsTask";
+import type { IExecuteContext } from "./ITask";
+import { IteratorTaskRunner } from "./IteratorTaskRunner";
+import type { TaskInput, TaskOutput, TaskTypeName } from "./TaskTypes";
+/**
+ * Execution mode for iterator tasks.
+ * - `parallel`: Execute all iterations concurrently (unlimited)
+ * - `parallel-limited`: Execute with a concurrency limit
+ * - `sequential`: Execute one at a time
+ * - `batched`: Execute in batches of batchSize
+ */
+export type ExecutionMode = "parallel" | "parallel-limited" | "sequential" | "batched";
+/**
+ * Configuration interface for IteratorTask.
+ * Extends GraphAsTaskConfig with iterator-specific options.
+ */
+export interface IteratorTaskConfig extends GraphAsTaskConfig {
+    /**
+     * The execution mode for iterations.
+     * @default "parallel"
+     */
+    readonly executionMode?: ExecutionMode;
+    /**
+     * Maximum number of concurrent iterations when executionMode is "parallel-limited".
+     * @default 5
+     */
+    readonly concurrencyLimit?: number;
+    /**
+     * Number of items per batch when executionMode is "batched".
+     * @default 10
+     */
+    readonly batchSize?: number;
+    /**
+     * Optional custom queue name for job queue integration.
+     * If not provided, a unique queue name will be generated.
+     */
+    readonly queueName?: string;
+    /**
+     * The name of the input port containing the array to iterate.
+     * If not provided, auto-detection will find the first array-typed port.
+     */
+    readonly iteratorPort?: string;
+}
+/**
+ * Result of detecting the iterator port from the input schema.
+ */
+interface IteratorPortInfo {
+    readonly portName: string;
+    readonly itemSchema: DataPortSchema;
+}
+/**
+ * Base class for iterator tasks that process collections of items.
+ *
+ * IteratorTask provides the foundation for loop-type tasks in the task graph.
+ * It manages a subgraph of tasks that are executed for each item in a collection,
+ * with configurable execution modes (parallel, sequential, batched, etc.).
+ *
+ * Subclasses should implement:
+ * - `getIterableItems(input)`: Extract the items to iterate over from input
+ * - Optionally override `collectResults()`: Define how to collect/merge results
+ *
+ * @template Input - The input type for the iterator task
+ * @template Output - The output type for the iterator task
+ * @template Config - The configuration type (must extend IteratorTaskConfig)
+ */
+export declare abstract class IteratorTask<Input extends TaskInput = TaskInput, Output extends TaskOutput = TaskOutput, Config extends IteratorTaskConfig = IteratorTaskConfig> extends GraphAsTask<Input, Output, Config> {
+    static type: TaskTypeName;
+    static category: string;
+    static title: string;
+    static description: string;
+    /** This task has dynamic schemas based on the inner workflow */
+    static hasDynamicSchemas: boolean;
+    /**
+     * The template subgraph that will be cloned for each iteration.
+     * This is the workflow defined between forEach() and endForEach().
+     */
+    protected _templateGraph: TaskGraph | undefined;
+    /**
+     * Cached iterator port info from schema analysis.
+     */
+    protected _iteratorPortInfo: IteratorPortInfo | undefined;
+    constructor(input?: Partial<Input>, config?: Partial<Config>);
+    _runner: IteratorTaskRunner<Input, Output, Config>;
+    /**
+     * Gets the custom iterator task runner.
+     */
+    get runner(): IteratorTaskRunner<Input, Output, Config>;
+    /**
+     * Gets the execution mode for this iterator.
+     */
+    get executionMode(): ExecutionMode;
+    /**
+     * Gets the concurrency limit for parallel-limited mode.
+     */
+    get concurrencyLimit(): number;
+    /**
+     * Gets the batch size for batched mode.
+     */
+    get batchSize(): number;
+    /**
+     * Auto-detects the iterator port from the input schema.
+     * Finds the first property with type "array" or that has an "items" property.
+     *
+     * @returns The port info or undefined if no array port found
+     */
+    protected detectIteratorPort(): IteratorPortInfo | undefined;
+    /**
+     * Gets the name of the port containing the iterable collection.
+     */
+    getIteratorPortName(): string | undefined;
+    /**
+     * Gets the schema for individual items in the collection.
+     */
+    getItemSchema(): DataPortSchema;
+    /**
+     * Extracts the items to iterate over from the input.
+     * Subclasses can override this to provide custom extraction logic.
+     *
+     * @param input - The task input
+     * @returns Array of items to iterate over
+     */
+    protected getIterableItems(input: Input): unknown[];
+    /**
+     * Sets the template graph that defines the workflow to run for each iteration.
+     * This is called by the Workflow builder when setting up the loop.
+     *
+     * Note: This does NOT call regenerateGraph() automatically because during
+     * workflow construction, input data may not be available. The graph is
+     * regenerated at execution time when actual input data is provided.
+     */
+    setTemplateGraph(graph: TaskGraph): void;
+    /**
+     * Gets the template graph.
+     */
+    getTemplateGraph(): TaskGraph | undefined;
+    /**
+     * Regenerates the subgraph based on the template and current input.
+     * This creates cloned task instances for each item in the iteration.
+     */
+    regenerateGraph(): void;
+    /**
+     * Creates task instances for each iteration item.
+     * Subclasses can override this for custom iteration behavior.
+     *
+     * @param items - The items to iterate over
+     */
+    protected createIterationTasks(items: unknown[]): void;
+    /**
+     * Clones the template graph tasks for a single iteration.
+     *
+     * @param iterationInput - The input for this iteration
+     * @param index - The iteration index
+     */
+    protected cloneTemplateForIteration(iterationInput: Record<string, unknown>, index: number): void;
+    /**
+     * Execute the iterator task.
+     * Sets up the iteration and delegates to the parent GraphAsTask execution.
+     */
+    execute(input: Input, context: IExecuteContext): Promise<Output | undefined>;
+    /**
+     * Returns the result when there are no items to iterate.
+     * Subclasses should override this to return appropriate empty results.
+     */
+    protected getEmptyResult(): Output;
+    /**
+     * Collects and merges results from all iterations.
+     * Subclasses can override this for custom result handling.
+     *
+     * @param results - Array of results from each iteration
+     * @returns Merged output
+     */
+    protected collectResults(results: TaskOutput[]): Output;
+    /**
+     * Input schema for the iterator.
+     * Returns the static schema since the iterator accepts the full array.
+     */
+    inputSchema(): DataPortSchema;
+    /**
+     * Output schema for the iterator.
+     * Subclasses should override to define their specific output structure.
+     */
+    outputSchema(): DataPortSchema;
+    /**
+     * Gets the output schema with properties wrapped in arrays.
+     * Used by MapTask and similar tasks that collect results.
+     */
+    protected getWrappedOutputSchema(): DataPortSchema;
+}
+export {};
+//# sourceMappingURL=IteratorTask.d.ts.map

package/dist/task/IteratorTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IteratorTask.d.ts","sourceRoot":"","sources":["../../src/task/IteratorTask.ts"],"names":[],"mappings":"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"}

package/dist/task/IteratorTaskRunner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphResultArray } from "../task-graph/TaskGraphRunner";
+import { GraphAsTaskRunner } from "./GraphAsTaskRunner";
+import type { ExecutionMode, IteratorTask, IteratorTaskConfig } from "./IteratorTask";
+import { RegisteredQueue } from "./TaskQueueRegistry";
+import type { TaskInput, TaskOutput } from "./TaskTypes";
+/**
+ * Custom runner for IteratorTask that handles execution mode and queue integration.
+ *
+ * This runner manages:
+ * - Dynamic queue creation based on execution mode
+ * - Concurrency limiting for parallel-limited mode
+ * - Sequential execution for sequential mode
+ * - Batch grouping for batched mode
+ */
+export declare class IteratorTaskRunner<Input extends TaskInput = TaskInput, Output extends TaskOutput = TaskOutput, Config extends IteratorTaskConfig = IteratorTaskConfig> extends GraphAsTaskRunner<Input, Output, Config> {
+    task: IteratorTask<Input, Output, Config>;
+    /**
+     * The queue used for this iterator's executions.
+     */
+    protected iteratorQueue?: RegisteredQueue<Input, Output>;
+    /**
+     * Generated queue name for this iterator instance.
+     */
+    protected iteratorQueueName?: string;
+    /**
+     * Gets or creates the queue for this iterator based on execution mode.
+     */
+    protected getOrCreateIteratorQueue(): Promise<RegisteredQueue<Input, Output> | undefined>;
+    /**
+     * Gets the concurrency level for the given execution mode.
+     */
+    protected getConcurrencyForMode(mode: ExecutionMode): number;
+    /**
+     * Creates a new queue for iterator execution.
+     */
+    protected createIteratorQueue(queueName: string, concurrency: number): Promise<RegisteredQueue<Input, Output>>;
+    /**
+     * Execute the iterator's children based on execution mode.
+     */
+    protected executeTaskChildren(input: Input): Promise<GraphResultArray<Output>>;
+    /**
+     * Execute iterations sequentially (one at a time).
+     */
+    protected executeSequential(input: Input): Promise<GraphResultArray<Output>>;
+    /**
+     * Execute iterations with a concurrency limit.
+     */
+    protected executeParallelLimited(input: Input): Promise<GraphResultArray<Output>>;
+    /**
+     * Execute iterations in batches.
+     */
+    protected executeBatched(input: Input): Promise<GraphResultArray<Output>>;
+    /**
+     * Clean up the iterator queue when done.
+     */
+    protected cleanup(): Promise<void>;
+}
+//# sourceMappingURL=IteratorTaskRunner.d.ts.map

package/dist/task/IteratorTaskRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IteratorTaskRunner.d.ts","sourceRoot":"","sources":["../../src/task/IteratorTaskRunner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAwB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAc,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAyCrE;;;;;;;;GAQG;AACH,qBAAa,kBAAkB,CAC7B,KAAK,SAAS,SAAS,GAAG,SAAS,EACnC,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,CACtD,SAAQ,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;IACxC,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAElD;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAEzD;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAMrC;;OAEG;cACa,wBAAwB,IAAI,OAAO,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAgC/F;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IAgB5D;;OAEG;cACa,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAoD1C;;OAEG;cACa,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAiBpF;;OAEG;cACa,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAoBlF;;OAEG;cACa,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IA4BvF;;OAEG;cACa,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAsC/E;;OAEG;cACa,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CASzC"}

package/dist/task/MapTask.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DataPortSchema } from "@workglow/util";
+import { IteratorTask, IteratorTaskConfig } from "./IteratorTask";
+import type { TaskInput, TaskOutput, TaskTypeName } from "./TaskTypes";
+/**
+ * Configuration for MapTask.
+ */
+export interface MapTaskConfig extends IteratorTaskConfig {
+    /**
+     * Whether to preserve the order of results matching the input order.
+     * When false, results may be in completion order (faster for parallel).
+     * @default true
+     */
+    readonly preserveOrder?: boolean;
+    /**
+     * Whether to flatten array results from each iteration.
+     * When true, if each iteration returns an array, they are concatenated.
+     * @default false
+     */
+    readonly flatten?: boolean;
+}
+/**
+ * MapTask transforms an array by running a workflow for each element and collecting results.
+ *
+ * This task is the functional-style map operation: it takes an array input,
+ * applies a transformation workflow to each element, and returns an array
+ * of transformed results.
+ *
+ * ## Features
+ *
+ * - Transforms each array element through inner workflow
+ * - Collects and returns array of results
+ * - Maintains result order by default
+ * - Configurable execution modes (parallel, sequential, etc.)
+ * - Optional flattening of nested arrays
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Transform texts to embeddings
+ * workflow
+ *   .input({ texts: ["hello", "world"] })
+ *   .map()
+ *     .textEmbedding()
+ *   .endMap()
+ *   // Result: { vectors: [Float32Array, Float32Array] }
+ *
+ * // With explicit port
+ * workflow
+ *   .map({ iteratorPort: "documents" })
+ *     .enrich()
+ *     .chunk()
+ *   .endMap()
+ * ```
+ *
+ * @template Input - The input type containing the array to transform
+ * @template Output - The output type (array of transformed results)
+ * @template Config - The configuration type
+ */
+export declare class MapTask<Input extends TaskInput = TaskInput, Output extends TaskOutput = TaskOutput, Config extends MapTaskConfig = MapTaskConfig> extends IteratorTask<Input, Output, Config> {
+    static type: TaskTypeName;
+    static category: string;
+    static title: string;
+    static description: string;
+    /**
+     * MapTask always uses PROPERTY_ARRAY merge strategy to collect results.
+     */
+    static readonly compoundMerge: "PROPERTY_ARRAY";
+    /**
+     * Static input schema for MapTask.
+     * Accepts any object with at least one array property.
+     */
+    static inputSchema(): DataPortSchema;
+    /**
+     * Static output schema for MapTask.
+     * Dynamic based on inner workflow outputs.
+     */
+    static outputSchema(): DataPortSchema;
+    /**
+     * Whether to preserve order of results.
+     */
+    get preserveOrder(): boolean;
+    /**
+     * Whether to flatten nested array results.
+     */
+    get flatten(): boolean;
+    /**
+     * Returns the empty result for MapTask.
+     * Returns empty arrays for each output property.
+     */
+    protected getEmptyResult(): Output;
+    /**
+     * Output schema for MapTask.
+     * Wraps inner workflow output properties in arrays.
+     */
+    outputSchema(): DataPortSchema;
+    /**
+     * Collects and optionally flattens results from all iterations.
+     */
+    protected collectResults(results: TaskOutput[]): Output;
+}
+declare module "../task-graph/Workflow" {
+    interface Workflow {
+        /**
+         * Starts a map loop that transforms each element in an array.
+         * Use .endMap() to close the loop and return to the parent workflow.
+         *
+         * @param config - Configuration for the map loop
+         * @returns A Workflow in loop builder mode for defining the transformation
+         *
+         * @example
+         * ```typescript
+         * workflow
+         *   .map()
+         *     .textEmbedding()
+         *   .endMap()
+         *   // Result: { vectors: [...] }
+         * ```
+         */
+        map: CreateLoopWorkflow<TaskInput, TaskOutput, MapTaskConfig>;
+        /**
+         * Ends the map loop and returns to the parent workflow.
+         * Only callable on workflows in loop builder mode.
+         *
+         * @returns The parent workflow
+         */
+        endMap(): Workflow;
+    }
+}
+//# sourceMappingURL=MapTask.d.ts.map