@hatchet-dev/typescript-sdk 1.27.0 → 1.28.0

package/v1/client/worker/worker-internal.d.ts

@@ -1,9 +1,10 @@
 import { Action, ActionKey, ActionListener } from '../../../clients/dispatcher/action-listener';
-import { StepActionEvent, StepActionEventType, GroupKeyActionEvent, GroupKeyActionEventType } from '../../../protoc/dispatcher';
+import { StepActionEvent, StepActionEventType, GroupKeyActionEvent, GroupKeyActionEventType, BatchActionEvent } from '../../../protoc/dispatcher';
 import HatchetPromise from '../../../util/hatchet-promise/hatchet-promise';
 import { CreateStepRateLimit } from '../../../protoc/workflows';
 import { Logger } from '../../../util/logger';
 import { BaseWorkflowDeclaration, WorkflowDefinition, HatchetClient } from '../..';
+import { TaskBatchConfig } from '../../../protoc/v1/workflows';
 import { CreateWorkflowTaskOpts } from '../../task';
 import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
 import { Duration } from '../duration';
@@ -70,6 +71,25 @@ export declare class InternalWorker {
      */
     handleStartStepRun(action: Action): Promise<Error | undefined>;
     getStepActionEvent(action: Action, eventType: StepActionEventType, shouldNotRetry: boolean, payload?: any, retryCount?: number): StepActionEvent;
+    /**
+     * Handles a START_BATCH action: invokes the registered batch task handler once with
+     * every buffered item, then reports completion/failure back per-member (or, for
+     * broadcast batch tasks, the same result for every member) via sendBatchActionEvent.
+     */
+    handleStartBatch(action: Action): Promise<Error | undefined>;
+    /**
+     * Reports the result of a successful batch handler invocation. result is expected to be
+     * a Record<string, any> keyed by batch member id; each member's output is serialized
+     * independently so that one member's serialization failure does not fail the whole
+     * batch.
+     */
+    private sendBatchCompleted;
+    /** Fails every member of the batch uniformly, e.g. when the handler itself throws. */
+    private sendBatchFailureForAll;
+    getBatchActionEvent(action: Action, eventType: StepActionEventType, items: {
+        taskRunExternalId: string;
+        eventPayload: string;
+    }[]): BatchActionEvent;
     getGroupKeyActionEvent(action: Action, eventType: GroupKeyActionEventType, payload?: any): GroupKeyActionEvent;
     /**
      * @important This method is instrumented by HatchetInstrumentor._patchHandleCancelStepRun.
@@ -93,6 +113,7 @@ export declare function mapSlotRequestsPb(task: {
     slotCost?: number;
 }, isDurable: boolean): Record<string, number>;
 export declare function mapRateLimitPb(limits: CreateWorkflowTaskOpts<any, any>['rateLimits']): CreateStepRateLimit[];
+export declare function mapBatchConfigPb(batch: CreateWorkflowTaskOpts<any, any>['batch']): TaskBatchConfig | undefined;
 export declare function resolveExecutionTimeout(task: {
     executionTimeout?: Duration;
     timeout?: Duration;

package/v1/client/worker/worker-internal.js

@@ -55,6 +55,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InternalWorker = void 0;
 exports.mapSlotRequestsPb = mapSlotRequestsPb;
 exports.mapRateLimitPb = mapRateLimitPb;
+exports.mapBatchConfigPb = mapBatchConfigPb;
 exports.resolveExecutionTimeout = resolveExecutionTimeout;
 exports.resolveScheduleTimeout = resolveScheduleTimeout;
 const hatchet_error_1 = __importDefault(require("../../../util/errors/hatchet-error"));
@@ -153,7 +154,13 @@ class InternalWorker {
         const newActions = workflow._tasks
             .filter((task) => !!task.fn)
             .reduce((acc, task) => {
-            acc[`${workflow.name}:${task.name.toLowerCase()}`] = (ctx) => task.fn(ctx.input, ctx);
+            const actionId = `${workflow.name}:${task.name.toLowerCase()}`;
+            if (task.batch) {
+                acc[actionId] = (ctx) => task.fn(decodeBatchItems(ctx.action.actionPayload), ctx);
+            }
+            else {
+                acc[actionId] = (ctx) => task.fn(ctx.input, ctx);
+            }
             return acc;
         }, {});
         const onFailureFn = workflow.onFailure
@@ -311,7 +318,9 @@ class InternalWorker {
                             inputs: '{}',
                             parents: (_b = (_a = task.parents) === null || _a === void 0 ? void 0 : _a.map((p) => p.name)) !== null && _b !== void 0 ? _b : [],
                             userData: '{}',
-                            retries: task.retries || ((_c = workflow.taskDefaults) === null || _c === void 0 ? void 0 : _c.retries) || 0,
+                            // Batch tasks buffer many concurrent runs into a single execution; per-item retry
+                            // semantics don't apply, so retries is always forced to 0.
+                            retries: batchOf(task) ? 0 : task.retries || ((_c = workflow.taskDefaults) === null || _c === void 0 ? void 0 : _c.retries) || 0,
                             rateLimits: mapRateLimitPb(task.rateLimits || ((_d = workflow.taskDefaults) === null || _d === void 0 ? void 0 : _d.rateLimits)),
                             workerLabels: mapWorkerLabelPb(task.desiredWorkerLabels || ((_e = workflow.taskDefaults) === null || _e === void 0 ? void 0 : _e.workerLabels)),
                             backoffFactor: ((_f = task.backoff) === null || _f === void 0 ? void 0 : _f.factor) || ((_h = (_g = workflow.taskDefaults) === null || _g === void 0 ? void 0 : _g.backoff) === null || _h === void 0 ? void 0 : _h.factor),
@@ -319,6 +328,7 @@ class InternalWorker {
                             conditions: (0, transformer_1.taskConditionsToPb)(task, this.client.config.namespace),
                             isDurable: durableTaskSet.has(task),
                             slotRequests: mapSlotRequestsPb(task, durableTaskSet.has(task)),
+                            batch: mapBatchConfigPb(batchOf(task)),
                             concurrency: task.concurrency
                                 ? Array.isArray(task.concurrency)
                                     ? task.concurrency
@@ -588,6 +598,106 @@ class InternalWorker {
             retryCount,
         };
     }
+    /**
+     * Handles a START_BATCH action: invokes the registered batch task handler once with
+     * every buffered item, then reports completion/failure back per-member (or, for
+     * broadcast batch tasks, the same result for every member) via sendBatchActionEvent.
+     */
+    handleStartBatch(action) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { actionId, taskName } = action;
+            const memberIds = batchMemberIds(action.actionPayload);
+            this.client.dispatcher
+                .sendBatchActionEvent(this.getBatchActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_STARTED, memberIds.map((id) => ({ taskRunExternalId: id, eventPayload: '' }))))
+                .catch((e) => {
+                this.logger.error(`Could not send batch started event: ${e.message}`);
+            });
+            const step = this.action_registry[actionId];
+            if (!step) {
+                this.logger.error(`Registered actions: '${Object.keys(this.action_registry).join(', ')}'`);
+                this.logger.error(`Could not find step '${actionId}'`);
+                return;
+            }
+            try {
+                const context = new context_1.Context(action, this.client, this);
+                const result = yield step(context);
+                // If the handler cancelled the batch (ctx.cancel()), a CANCELLED batch event
+                // covering every member was already sent from within cancel() itself. Don't also
+                // send a COMPLETED event for the same members afterward — matches the Python SDK's
+                // `if context.is_cancelled: return` guard in its batch runner.
+                if (context.cancelled) {
+                    return undefined;
+                }
+                yield this.sendBatchCompleted(action, result);
+                return undefined;
+            }
+            catch (e) {
+                this.logger.error((0, logger_1.taskRunLog)(taskName, actionId, `batch failed: ${e.message}`));
+                if (e.stack) {
+                    this.logger.error(e.stack);
+                }
+                yield this.sendBatchFailureForAll(action, memberIds, e);
+                return e instanceof Error ? e : new Error(String(e));
+            }
+        });
+    }
+    /**
+     * Reports the result of a successful batch handler invocation. result is expected to be
+     * a Record<string, any> keyed by batch member id; each member's output is serialized
+     * independently so that one member's serialization failure does not fail the whole
+     * batch.
+     */
+    sendBatchCompleted(action, result) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof result !== 'object' || result === null || Array.isArray(result)) {
+                yield this.sendBatchFailureForAll(action, Object.keys(result !== null && result !== void 0 ? result : {}), new Error('batch task handler did not return a valid per-member result map'));
+                return;
+            }
+            const completedItems = [];
+            const failedItems = [];
+            Object.entries(result).forEach(([id, output]) => {
+                try {
+                    completedItems.push({ taskRunExternalId: id, eventPayload: JSON.stringify(output) });
+                }
+                catch (e) {
+                    failedItems.push({
+                        taskRunExternalId: id,
+                        eventPayload: JSON.stringify({ message: e.message }),
+                    });
+                }
+            });
+            if (completedItems.length > 0) {
+                yield this.client.dispatcher.sendBatchActionEvent(this.getBatchActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_COMPLETED, completedItems));
+            }
+            if (failedItems.length > 0) {
+                yield this.client.dispatcher.sendBatchActionEvent(this.getBatchActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, failedItems));
+            }
+        });
+    }
+    /** Fails every member of the batch uniformly, e.g. when the handler itself throws. */
+    sendBatchFailureForAll(action, memberIds, error) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const payload = JSON.stringify({ message: error === null || error === void 0 ? void 0 : error.message, stack: error === null || error === void 0 ? void 0 : error.stack });
+            const items = memberIds.map((id) => ({ taskRunExternalId: id, eventPayload: payload }));
+            try {
+                yield this.client.dispatcher.sendBatchActionEvent(this.getBatchActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, items));
+            }
+            catch (e) {
+                this.logger.error(`Could not send batch failed event: ${e.message}`);
+            }
+        });
+    }
+    getBatchActionEvent(action, eventType, items) {
+        return {
+            workerId: this.name,
+            jobId: action.jobId,
+            actionId: action.actionId,
+            batchId: action.batchId,
+            eventTimestamp: new Date(),
+            eventType,
+            items,
+        };
+    }
     getGroupKeyActionEvent(action, eventType, payload = '') {
         if (!action.getGroupKeyRunId) {
             throw new hatchet_error_1.default('No group key run id provided');
@@ -807,6 +917,8 @@ class InternalWorker {
             switch (type) {
                 case dispatcher_1.ActionType.START_STEP_RUN:
                     return this.handleStartStepRun(action);
+                case dispatcher_1.ActionType.START_BATCH:
+                    return this.handleStartBatch(action);
                 case dispatcher_1.ActionType.CANCEL_STEP_RUN:
                     return this.handleCancelStepRun(action);
                 case dispatcher_1.ActionType.START_GET_GROUP_KEY:
@@ -954,6 +1066,59 @@ function mapRateLimitPb(limits) {
         };
     });
 }
+/**
+ * Decodes the buffered items of a batch task's START_BATCH action into a Record keyed by
+ * each buffered item's task-run external id, mapping to that item's input. The wire shape
+ * of actionPayload for a START_BATCH action is
+ * `{ "<taskRunExternalId>": { "payload": { "input": {...}, ... }, "workflow_run_id": "..." }, ... }`,
+ * distinct from the flat single-input shape used by START_STEP_RUN actions.
+ */
+function decodeBatchItems(actionPayload) {
+    const parsed = parseBatchPayload(actionPayload);
+    return Object.fromEntries(Object.entries(parsed).map(([id, item]) => { var _a, _b; return [id, (_b = (_a = item === null || item === void 0 ? void 0 : item.payload) === null || _a === void 0 ? void 0 : _a.input) !== null && _b !== void 0 ? _b : {}]; }));
+}
+function batchMemberIds(actionPayload) {
+    return Object.keys(parseBatchPayload(actionPayload));
+}
+function parseBatchPayload(actionPayload) {
+    if (!actionPayload) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(actionPayload);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+/** Batch tasks are only available on non-durable tasks; durable tasks never carry `batch`. */
+function batchOf(task) {
+    return 'batch' in task ? task.batch : undefined;
+}
+function mapBatchConfigPb(batch) {
+    if (!batch) {
+        return undefined;
+    }
+    if (!Number.isInteger(batch.maxSize) || batch.maxSize <= 0) {
+        throw new Error(`batch.maxSize must be a positive integer, got: ${batch.maxSize}`);
+    }
+    const batchMaxIntervalMs = batch.maxInterval !== undefined ? (0, duration_1.durationToMs)(batch.maxInterval) : undefined;
+    if (batchMaxIntervalMs !== undefined && batchMaxIntervalMs <= 0) {
+        throw new Error('batch.maxInterval must be positive when provided');
+    }
+    if (batch.groupMaxRuns !== undefined &&
+        (!Number.isInteger(batch.groupMaxRuns) || batch.groupMaxRuns <= 0)) {
+        throw new Error(`batch.groupMaxRuns must be a positive integer when provided, got: ${batch.groupMaxRuns}`);
+    }
+    return {
+        batchMaxSize: batch.maxSize,
+        batchMaxIntervalMs,
+        batchGroupKey: batch.groupKey,
+        batchGroupMaxRuns: batch.groupMaxRuns,
+        broadcastOutput: batch.broadcastOutput,
+    };
+}
 // Helper function to validate CEL expressions
 function validateCelExpression(_expr) {
     // FIXME: this is a placeholder. In a real implementation, you'd need to use a CEL parser or validator.

package/v1/declaration.d.ts

@@ -9,7 +9,7 @@ import WorkflowRunRef from '../util/workflow-run-ref';
 import { CronWorkflows, ScheduledWorkflows, V1CreateFilterRequest } from '../clients/rest/generated/data-contracts';
 import * as z from 'zod/v4';
 import { IHatchetClient } from './client/client.interface';
-import { CreateWorkflowTaskOpts, CreateOnFailureTaskOpts, TaskFn, CreateWorkflowDurableTaskOpts, CreateBaseTaskOpts, CreateOnSuccessTaskOpts, Concurrency, DurableTaskFn, WorkerLabelComparator, IdempotencyConfig } from './task';
+import { CreateWorkflowTaskOpts, CreateOnFailureTaskOpts, TaskFn, CreateWorkflowDurableTaskOpts, CreateBaseTaskOpts, CreateOnSuccessTaskOpts, Concurrency, DurableTaskFn, WorkerLabelComparator, IdempotencyConfig, BatchTaskConfig, BatchTaskFn } from './task';
 import { Duration } from './client/duration';
 import { MetricsClient } from './client/features/metrics';
 import { InputType, OutputType, UnknownInputType, JsonObject, Resolved } from './types';
@@ -159,6 +159,16 @@ export type CreateBaseWorkflowOpts = {
     idempotency?: IdempotencyConfig;
 };
 export type CreateTaskWorkflowOpts<I extends InputType = UnknownInputType, O extends OutputType = void> = CreateBaseWorkflowOpts & CreateBaseTaskOpts<I, O, TaskFn<I, O>>;
+/**
+ * Options for creating a batch task workflow. Batch tasks buffer concurrent runs and
+ * dispatch them together as a single execution; fn receives a Record keyed by each
+ * buffered run's task-run external id.
+ *
+ * Preview: batch tasks are in beta and may change in future releases.
+ */
+export type CreateBatchTaskWorkflowOpts<I extends InputType = UnknownInputType, O extends OutputType = void> = CreateBaseWorkflowOpts & CreateBaseTaskOpts<I, O, BatchTaskFn<I, O>> & {
+    batch: BatchTaskConfig;
+};
 export type CreateDurableTaskWorkflowOpts<I extends InputType = UnknownInputType, O extends OutputType = void> = CreateBaseWorkflowOpts & CreateBaseTaskOpts<I, O, DurableTaskFn<I, O>> & {
     evictionPolicy?: EvictionPolicy;
 };
@@ -434,6 +444,24 @@ export declare class WorkflowDeclaration<I extends InputType = UnknownInputType,
         name: Name;
         fn?: Fn;
     }) | TaskWorkflowDeclaration<I, TO>): CreateWorkflowTaskOpts<I, TO>;
+    /**
+     * Adds a batch task to the workflow. Batch tasks buffer concurrent runs until Hatchet
+     * flushes the batch (size reached or flush interval), then invoke the handler once with
+     * all buffered inputs keyed by each run's task-run external id. The handler must return
+     * a Record mapping each id to its output, or set `batch.broadcastOutput` to return the
+     * same result to all callers. retries is always forced to 0 for batch tasks.
+     *
+     * Preview: batch tasks are in beta and may change in future releases.
+     * @template Fn The type of the batch task function.
+     * @param options The batch task configuration options.
+     * @returns The task options that were added.
+     */
+    batchTask<Fn extends BatchTaskFn<TI, TO>, TI extends InputType = Parameters<Fn>[0] extends Record<string, infer II> ? II extends InputType ? II : UnknownInputType : UnknownInputType, TO extends OutputType = ReturnType<Fn> extends Promise<infer P> ? P extends OutputType ? P : void : ReturnType<Fn> extends OutputType ? ReturnType<Fn> : void>(options: {
+        fn: Fn;
+        batch: BatchTaskConfig;
+    } & Omit<CreateBatchTaskWorkflowOpts<TI, TO>, 'fn' | 'batch' | 'name'> & {
+        name: string;
+    }): CreateWorkflowTaskOpts<TI, TO>;
     /**
      * Adds an onFailure task to the workflow.
      * This will only run if any task in the workflow fails.
@@ -465,7 +493,7 @@ export declare class WorkflowDeclaration<I extends InputType = UnknownInputType,
      * @param options The task configuration options.
      * @returns The task options that were added.
      */
-    durableTask<Name extends string, Fn extends (Name extends keyof O ? (input: I & MiddlewareBefore, ctx: DurableContext<I & MiddlewareBefore>) => O[Name] extends OutputType ? O[Name] | Promise<O[Name]> : void : (input: I & MiddlewareBefore, ctx: DurableContext<I & MiddlewareBefore>) => void), FnReturn = ReturnType<Fn> extends Promise<infer P> ? P : ReturnType<Fn>, TO extends OutputType = Name extends keyof O ? O[Name] extends OutputType ? O[Name] : never : FnReturn extends OutputType ? FnReturn : never>(options: Omit<CreateWorkflowTaskOpts<I, TO>, 'fn' | 'slotCost'> & {
+    durableTask<Name extends string, Fn extends (Name extends keyof O ? (input: I & MiddlewareBefore, ctx: DurableContext<I & MiddlewareBefore>) => O[Name] extends OutputType ? O[Name] | Promise<O[Name]> : void : (input: I & MiddlewareBefore, ctx: DurableContext<I & MiddlewareBefore>) => void), FnReturn = ReturnType<Fn> extends Promise<infer P> ? P : ReturnType<Fn>, TO extends OutputType = Name extends keyof O ? O[Name] extends OutputType ? O[Name] : never : FnReturn extends OutputType ? FnReturn : never>(options: Omit<CreateWorkflowTaskOpts<I, TO>, 'fn' | 'slotCost' | 'batch'> & {
         name: Name;
         fn: Fn;
     }): CreateWorkflowDurableTaskOpts<I, TO>;
@@ -573,6 +601,38 @@ export declare class TaskWorkflowDeclaration<I extends InputType = UnknownInputT
 export declare function CreateTaskWorkflow<Fn extends (input: I, ctx?: any) => O | Promise<O>, I extends InputType = Parameters<Fn>[0], O extends OutputType = ReturnType<Fn> extends Promise<infer P> ? P extends OutputType ? P : void : ReturnType<Fn> extends OutputType ? ReturnType<Fn> : void>(options: {
     fn: Fn;
 } & Omit<CreateTaskWorkflowOpts<I, O>, 'fn'>, client?: IHatchetClient): TaskWorkflowDeclaration<I, O>;
+/**
+ * Creates a new batch task workflow declaration, with the handler's single return value
+ * broadcast to every member of the batch.
+ * @template Fn The type of the batch task function
+ * @param options The batch task configuration options.
+ * @param client Optional Hatchet client instance.
+ * @returns A new TaskWorkflowDeclaration with inferred types.
+ *
+ * Preview: batch tasks are in beta and may change in future releases.
+ */
+export declare function CreateBatchTaskWorkflow<Fn extends (input: Record<string, I>, ctx: Context<Record<string, I>>) => O | Promise<O>, I extends InputType = Parameters<Fn>[0] extends Record<string, infer II> ? II extends InputType ? II : UnknownInputType : UnknownInputType, O extends OutputType = ReturnType<Fn> extends Promise<infer P> ? P extends OutputType ? P : void : ReturnType<Fn> extends OutputType ? ReturnType<Fn> : void>(options: {
+    fn: Fn;
+    batch: BatchTaskConfig & {
+        broadcastOutput: true;
+    };
+} & Omit<CreateBatchTaskWorkflowOpts<I, O>, 'fn' | 'batch'>, client?: IHatchetClient): TaskWorkflowDeclaration<I, O>;
+/**
+ * Creates a new batch task workflow declaration. The handler receives a Record keyed by
+ * batch member id and must return a Record with the exact same key set.
+ * @template Fn The type of the batch task function
+ * @param options The batch task configuration options.
+ * @param client Optional Hatchet client instance.
+ * @returns A new TaskWorkflowDeclaration with inferred types.
+ *
+ * Preview: batch tasks are in beta and may change in future releases.
+ */
+export declare function CreateBatchTaskWorkflow<Fn extends (input: Record<string, I>, ctx: Context<Record<string, I>>) => Record<string, O> | Promise<Record<string, O>>, I extends InputType = Parameters<Fn>[0] extends Record<string, infer II> ? II extends InputType ? II : UnknownInputType : UnknownInputType, O extends OutputType = ReturnType<Fn> extends Promise<infer P> ? P extends Record<string, infer OO> ? OO extends OutputType ? OO : void : void : ReturnType<Fn> extends Record<string, infer OO> ? OO extends OutputType ? OO : void : void>(options: {
+    fn: Fn;
+    batch: BatchTaskConfig & {
+        broadcastOutput?: false;
+    };
+} & Omit<CreateBatchTaskWorkflowOpts<I, O>, 'fn' | 'batch'>, client?: IHatchetClient): TaskWorkflowDeclaration<I, O>;
 /**
  * Creates a new workflow instance.
  * @template I The input type for the workflow.

package/v1/declaration.js

@@ -26,11 +26,16 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskWorkflowDeclaration = exports.WorkflowDeclaration = exports.BaseWorkflowDeclaration = exports.StickyStrategy = exports.Priority = void 0;
 exports.CreateTaskWorkflow = CreateTaskWorkflow;
+exports.CreateBatchTaskWorkflow = CreateBatchTaskWorkflow;
 exports.CreateWorkflow = CreateWorkflow;
 exports.CreateDurableTaskWorkflow = CreateDurableTaskWorkflow;
+const hatchet_error_1 = __importDefault(require("../util/errors/hatchet-error"));
 const abort_error_1 = require("../util/abort-error");
 const parent_run_context_vars_1 = require("./parent-run-context-vars");
 const UNBOUND_ERR = new Error('workflow unbound to hatchet client, hint: use client.run instead');
@@ -481,6 +486,25 @@ class WorkflowDeclaration extends BaseWorkflowDeclaration {
         this.definition._tasks.push(typedOptions);
         return typedOptions;
     }
+    /**
+     * Adds a batch task to the workflow. Batch tasks buffer concurrent runs until Hatchet
+     * flushes the batch (size reached or flush interval), then invoke the handler once with
+     * all buffered inputs keyed by each run's task-run external id. The handler must return
+     * a Record mapping each id to its output, or set `batch.broadcastOutput` to return the
+     * same result to all callers. retries is always forced to 0 for batch tasks.
+     *
+     * Preview: batch tasks are in beta and may change in future releases.
+     * @template Fn The type of the batch task function.
+     * @param options The batch task configuration options.
+     * @returns The task options that were added.
+     */
+    batchTask(options) {
+        const { fn, batch } = options, rest = __rest(options, ["fn", "batch"]);
+        const wrappedFn = wrapBatchFn(fn, !!batch.broadcastOutput);
+        const typedOptions = Object.assign(Object.assign({}, rest), { fn: wrappedFn, batch });
+        this.definition._tasks.push(typedOptions);
+        return typedOptions;
+    }
     /**
      * Adds an onFailure task to the workflow.
      * This will only run if any task in the workflow fails.
@@ -692,6 +716,38 @@ exports.TaskWorkflowDeclaration = TaskWorkflowDeclaration;
 function CreateTaskWorkflow(options, client) {
     return new TaskWorkflowDeclaration(options, client);
 }
+/**
+ * Wraps a user-provided batch task handler so it always resolves to a Record keyed by
+ * batch member id, regardless of whether the handler itself uses broadcastOutput. When
+ * broadcastOutput is set, the handler's single return value is copied to every member id
+ * present in the input. Otherwise, the handler's returned Record must have exactly the
+ * same key set as the input; a mismatch throws, which fails every member of the batch
+ * uniformly (matching the behavior of an uncaught error from the handler itself).
+ */
+function wrapBatchFn(fn, broadcastOutput) {
+    return (input, ctx) => __awaiter(this, void 0, void 0, function* () {
+        const result = yield fn(input, ctx);
+        if (broadcastOutput) {
+            return Object.fromEntries(Object.keys(input).map((id) => [id, result]));
+        }
+        if (typeof result !== 'object' || result === null || Array.isArray(result)) {
+            throw new hatchet_error_1.default('batch task handler must return an object keyed by batch member id when broadcastOutput is false');
+        }
+        const inputKeys = Object.keys(input);
+        const resultKeys = Object.keys(result);
+        const missing = inputKeys.filter((k) => !resultKeys.includes(k));
+        const extra = resultKeys.filter((k) => !inputKeys.includes(k));
+        if (missing.length > 0 || extra.length > 0) {
+            throw new hatchet_error_1.default(`batch task handler result keys do not match batch member ids (missing=${missing.join(', ')}, extra=${extra.join(', ')})`);
+        }
+        return result;
+    });
+}
+function CreateBatchTaskWorkflow(options, client) {
+    const { fn, batch } = options, rest = __rest(options, ["fn", "batch"]);
+    const wrappedFn = wrapBatchFn(fn, !!batch.broadcastOutput);
+    return new TaskWorkflowDeclaration(Object.assign(Object.assign({}, rest), { fn: wrappedFn, batch, retries: 0 }), client);
+}
 /**
  * Creates a new workflow instance.
  * @template I The input type for the workflow.

package/v1/examples/batch_assign/workflow.d.ts

@@ -0,0 +1,62 @@
+type SimpleInput = {
+    message: string;
+};
+type SimpleOutput = {
+    transformed_message: string;
+};
+type KeyedInput = {
+    message: string;
+    group: string;
+};
+type KeyedFailableInput = {
+    message: string;
+    group: string | number;
+};
+type KeyedOutput = {
+    batch_key?: string;
+    batch_size?: number;
+    unique_keys?: number;
+    uppercase: string;
+};
+type LargePayloadInput = {
+    data: string;
+};
+type LargeOutput = {
+    batch_id: string;
+    received: boolean;
+    batch_size: number;
+    data_length: number;
+};
+type SingleOutput = {
+    original: string;
+    batch_size: number;
+};
+type OrderedInput = {
+    index: number;
+};
+type OrderedOutput = {
+    index: number;
+};
+type BroadcastOutput = {
+    sum: number;
+};
+type ChildOutput = {
+    message_len: number;
+};
+type ChildBatchOutput = {
+    out: Record<string, SimpleInput>;
+};
+export declare const batchSimple: import("../..").TaskWorkflowDeclaration<SimpleInput, Record<string, SimpleOutput>, {}, {}, {}, {}>;
+export declare const batchKeyed: import("../..").TaskWorkflowDeclaration<KeyedInput, Record<string, KeyedOutput>, {}, {}, {}, {}>;
+export declare const batchKeyedFailable: import("../..").TaskWorkflowDeclaration<KeyedFailableInput, Record<string, KeyedOutput>, {}, {}, {}, {}>;
+export declare const batchKeyedInterval: import("../..").TaskWorkflowDeclaration<KeyedInput, Record<string, KeyedOutput>, {}, {}, {}, {}>;
+export declare const batchLarge: import("../..").TaskWorkflowDeclaration<LargePayloadInput, Record<string, LargeOutput>, {}, {}, {}, {}>;
+export declare const batchSingle: import("../..").TaskWorkflowDeclaration<SimpleInput, Record<string, SingleOutput>, {}, {}, {}, {}>;
+export declare const batchOrdered: import("../..").TaskWorkflowDeclaration<OrderedInput, Record<string, OrderedOutput>, {}, {}, {}, {}>;
+export declare const batchBroadcast: import("../..").TaskWorkflowDeclaration<SimpleInput, BroadcastOutput, {}, {}, {}, {}>;
+export declare const batchCancel: import("../..").TaskWorkflowDeclaration<SimpleInput, {}, {}, {}, {}, {}>;
+export declare const child: import("../..").TaskWorkflowDeclaration<SimpleInput, ChildOutput, {}, {}, {}, {}>;
+export declare const childBatch: import("../..").TaskWorkflowDeclaration<SimpleInput, ChildBatchOutput, {}, {}, {}, {}>;
+export declare const batchChildSpawn: import("../..").TaskWorkflowDeclaration<SimpleInput, Record<string, ChildOutput>, {}, {}, {}, {}>;
+export declare const batchChildBatchSpawn: import("../..").TaskWorkflowDeclaration<SimpleInput, Record<string, ChildBatchOutput>, {}, {}, {}, {}>;
+export {};

package/v1/examples/batch_assign/workflow.js

@@ -0,0 +1,161 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchChildBatchSpawn = exports.batchChildSpawn = exports.childBatch = exports.child = exports.batchCancel = exports.batchBroadcast = exports.batchOrdered = exports.batchSingle = exports.batchLarge = exports.batchKeyedInterval = exports.batchKeyedFailable = exports.batchKeyed = exports.batchSimple = void 0;
+const hatchet_client_1 = require("../hatchet-client");
+exports.batchSimple = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-simple',
+    batch: { maxSize: 3, maxInterval: 200 },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = { transformed_message: input.message.toUpperCase() };
+        });
+        return out;
+    }),
+});
+exports.batchKeyed = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-keyed',
+    batch: { maxSize: 2, maxInterval: 200, groupKey: 'input.group' },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const uniqueKeys = new Set(Object.values(tasks).map((i) => i.group)).size;
+        const batchSize = Object.keys(tasks).length;
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = {
+                batch_key: input.group,
+                batch_size: batchSize,
+                unique_keys: uniqueKeys,
+                uppercase: input.message.toUpperCase(),
+            };
+        });
+        return out;
+    }),
+});
+exports.batchKeyedFailable = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-keyed-failable',
+    batch: { maxSize: 2, maxInterval: 200, groupKey: 'input.group' },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = { uppercase: input.message.toUpperCase() };
+        });
+        return out;
+    }),
+});
+exports.batchKeyedInterval = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-keyed-interval',
+    batch: { maxSize: 3, maxInterval: 150, groupKey: 'input.group' },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const uniqueKeys = new Set(Object.values(tasks).map((i) => i.group)).size;
+        const batchSize = Object.keys(tasks).length;
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = {
+                batch_key: input.group,
+                batch_size: batchSize,
+                unique_keys: uniqueKeys,
+                uppercase: input.message.toUpperCase(),
+            };
+        });
+        return out;
+    }),
+});
+exports.batchLarge = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-large',
+    batch: { maxSize: 100, maxInterval: 10000 },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const batchId = crypto.randomUUID();
+        const batchSize = Object.keys(tasks).length;
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = {
+                batch_id: batchId,
+                received: true,
+                batch_size: batchSize,
+                data_length: input.data.length,
+            };
+        });
+        return out;
+    }),
+});
+exports.batchSingle = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-single',
+    batch: { maxSize: 1, maxInterval: 100 },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const batchSize = Object.keys(tasks).length;
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = { original: input.message, batch_size: batchSize };
+        });
+        return out;
+    }),
+});
+exports.batchOrdered = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-ordered',
+    batch: { maxSize: 20, maxInterval: 2000 },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const out = {};
+        Object.entries(tasks).forEach(([id, input]) => {
+            out[id] = { index: input.index };
+        });
+        return out;
+    }),
+});
+exports.batchBroadcast = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-broadcast',
+    batch: { maxSize: 10, maxInterval: 2000, broadcastOutput: true },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const sum = Object.values(tasks).reduce((acc, i) => acc + i.message.length, 0);
+        return { sum };
+    }),
+});
+exports.batchCancel = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-cancel',
+    batch: { maxSize: 10, maxInterval: 2000, broadcastOutput: true },
+    fn: (_tasks, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+        yield ctx.cancel();
+        return {};
+    }),
+});
+exports.child = hatchet_client_1.hatchet.task({
+    name: 'batch-child',
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () { return ({ message_len: input.message.length }); }),
+});
+exports.childBatch = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-child-batch',
+    batch: { maxSize: 10, maxInterval: 60000, broadcastOutput: true },
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () { return ({ out: tasks }); }),
+});
+exports.batchChildSpawn = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-child-spawn',
+    batch: { maxSize: 10, maxInterval: 60000 },
+    executionTimeout: '60s',
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const out = {};
+        yield Promise.all(Object.keys(tasks).map((id) => __awaiter(void 0, void 0, void 0, function* () {
+            out[id] = yield exports.child.run({ message: 'blahblah' });
+        })));
+        return out;
+    }),
+});
+exports.batchChildBatchSpawn = hatchet_client_1.hatchet.batchTask({
+    name: 'batch-child-batch-spawn',
+    batch: { maxSize: 10, maxInterval: 60000 },
+    executionTimeout: '60s',
+    fn: (tasks) => __awaiter(void 0, void 0, void 0, function* () {
+        const out = {};
+        yield Promise.all(Object.keys(tasks).map((id) => __awaiter(void 0, void 0, void 0, function* () {
+            out[id] = yield exports.childBatch.run({ message: 'hello' });
+        })));
+        return out;
+    }),
+});