@hatchet-dev/typescript-sdk 1.26.2 → 1.28.0

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;
+    }),
+});

package/v1/examples/e2e-worker.js

@@ -37,13 +37,14 @@ const workflow_16 = require("./on_event/workflow");
 const workflow_17 = require("./return_exceptions/workflow");
 const workflow_18 = require("./run_details/workflow");
 const e2e_workflows_1 = require("./simple/e2e-workflows");
-const workflow_19 = require("./streaming/workflow");
-const workflow_20 = require("./timeout/workflow");
-const workflow_21 = require("./webhooks/workflow");
-const workflow_22 = require("./child_index/workflow");
-const workflow_23 = require("./support_agent/workflow");
-const workflow_24 = require("./welcome_email/workflow");
-const workflow_25 = require("./pdf_pipeline/workflow");
+const workflow_19 = require("./batch_assign/workflow");
+const workflow_20 = require("./streaming/workflow");
+const workflow_21 = require("./timeout/workflow");
+const workflow_22 = require("./webhooks/workflow");
+const workflow_23 = require("./child_index/workflow");
+const workflow_24 = require("./support_agent/workflow");
+const workflow_25 = require("./welcome_email/workflow");
+const workflow_26 = require("./pdf_pipeline/workflow");
 const workflows = [
     workflow_1.bulkChild,
     workflow_1.bulkParentWorkflow,
@@ -94,20 +95,33 @@ const workflows = [
     workflow_18.runDetailTestWorkflow,
     e2e_workflows_1.helloWorld,
     e2e_workflows_1.helloWorldDurable,
-    workflow_19.streamingTask,
-    workflow_20.timeoutTask,
-    workflow_20.refreshTimeoutTask,
-    workflow_21.webhookWorkflow,
-    workflow_22.childIndexChild,
-    workflow_22.childIndexParent,
-    workflow_22.scenarioTask,
-    workflow_22.orchestratorTask,
-    workflow_23.supportAgent,
-    workflow_23.triageTicket,
-    workflow_23.generateReply,
-    workflow_23.escalateTicket,
-    workflow_24.welcomeEmail,
-    workflow_25.pdfPipeline,
+    workflow_20.streamingTask,
+    workflow_21.timeoutTask,
+    workflow_21.refreshTimeoutTask,
+    workflow_22.webhookWorkflow,
+    workflow_23.childIndexChild,
+    workflow_23.childIndexParent,
+    workflow_23.scenarioTask,
+    workflow_23.orchestratorTask,
+    workflow_24.supportAgent,
+    workflow_24.triageTicket,
+    workflow_24.generateReply,
+    workflow_24.escalateTicket,
+    workflow_25.welcomeEmail,
+    workflow_26.pdfPipeline,
+    workflow_19.batchSimple,
+    workflow_19.batchKeyed,
+    workflow_19.batchKeyedFailable,
+    workflow_19.batchKeyedInterval,
+    workflow_19.batchLarge,
+    workflow_19.batchSingle,
+    workflow_19.batchOrdered,
+    workflow_19.batchBroadcast,
+    workflow_19.batchCancel,
+    workflow_19.child,
+    workflow_19.childBatch,
+    workflow_19.batchChildSpawn,
+    workflow_19.batchChildBatchSpawn,
 ];
 function main() {
     return __awaiter(this, void 0, void 0, function* () {

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

@@ -8,3 +8,6 @@ export declare const idempotentTask: import("../..").TaskWorkflowDeclaration<Ide
 export declare const idempotentTaskShortWindow: import("../..").TaskWorkflowDeclaration<IdempotencyInput, {
     result: string;
 }, {}, {}, {}, {}>;
+export declare const idempotentStatusBasedTask: import("../..").TaskWorkflowDeclaration<IdempotencyInput, {
+    result: string;
+}, {}, {}, {}, {}>;

package/v1/examples/idempotency/workflow.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.idempotentTaskShortWindow = exports.idempotentTask = exports.EVENT_KEY = void 0;
+exports.idempotentStatusBasedTask = exports.idempotentTaskShortWindow = exports.idempotentTask = exports.EVENT_KEY = void 0;
 const hatchet_client_1 = require("../hatchet-client");
 exports.EVENT_KEY = 'ts-e2e:idempotency-example';
 // > idempotency
@@ -37,3 +37,16 @@ exports.idempotentTaskShortWindow = hatchet_client_1.hatchet.task({
         return { result: `Hello, world from task ${input.id}` };
     }),
 });
+// > status-based-idempotency
+exports.idempotentStatusBasedTask = hatchet_client_1.hatchet.task({
+    name: 'ts-e2e-idempotent-status-based-task',
+    idempotency: {
+        strategy: 'status',
+        expression: 'input.id',
+        fallbackTtlMs: 10000,
+    },
+    fn: (input) => __awaiter(void 0, void 0, void 0, function* () {
+        return { result: `Hello, world from task ${input.id}` };
+    }),
+});
+// !!

package/v1/task.d.ts

@@ -56,15 +56,69 @@ export type TTLBasedIdempotencyConfig = BaseIdempotencyConfig & {
      */
     ttlMs: number;
 };
+/**
+ * Status-based idempotency: keeps the idempotency key alive until the associated run
+ * reaches a terminal status. `fallbackTtlMs` caps how long the key can live before it's evicted.
+ */
+export type StatusBasedIdempotencyConfig = BaseIdempotencyConfig & {
+    strategy: 'status';
+    /**
+     * Fallback time-to-live (in milliseconds): the longest the idempotency key can live
+     * before it's evicted, even if the run has not reached a terminal status.
+     */
+    fallbackTtlMs: number;
+};
 /**
  * Union of all supported idempotency configurations.
  */
-export type IdempotencyConfig = TTLBasedIdempotencyConfig;
+export type IdempotencyConfig = TTLBasedIdempotencyConfig | StatusBasedIdempotencyConfig;
 export declare class NonRetryableError extends Error {
     constructor(message?: string);
 }
 export type TaskFn<I extends InputType = UnknownInputType, O extends OutputType = void, C = Context<I>> = (input: I, ctx: C) => O | Promise<O>;
 export type DurableTaskFn<I extends InputType = UnknownInputType, O extends OutputType = void> = TaskFn<I, O, DurableContext<I>>;
+/**
+ * Configures a task as a batch task: concurrent runs are buffered and dispatched together
+ * as a single execution once maxSize is reached, maxInterval elapses, or (if groupKey is
+ * set) once groupMaxRuns concurrent batches per group are exceeded.
+ *
+ * Preview: batch tasks are in beta and may change in future releases.
+ */
+export type BatchTaskConfig = {
+    /**
+     * Maximum number of items buffered before the batch is flushed. Must be positive.
+     */
+    maxSize: number;
+    /**
+     * (optional) maximum time to wait before flushing a partially-filled batch.
+     * go duration format (e.g., "1s", "5m", "1h").
+     */
+    maxInterval?: Duration;
+    /**
+     * (optional) CEL expression evaluated against each item's input to partition items into
+     * independent batches, e.g. "input.group". When unset, all items buffered for the task
+     * share a single batch.
+     */
+    groupKey?: string;
+    /**
+     * (optional) maximum number of concurrent batches per group.
+     */
+    groupMaxRuns?: number;
+    /**
+     * (optional) when true, the handler returns a single value that is broadcast as the
+     * result to every member of the batch, instead of a Record keyed by batch member id.
+     *
+     * default: false
+     */
+    broadcastOutput?: boolean;
+};
+/**
+ * The function signature for a batch task's handler. `input` maps each buffered run's
+ * task-run external id (its "batch member id") to that run's input. Unless
+ * `batch.broadcastOutput` is set, the handler must return a Record with the exact same
+ * key set, mapping each id to that run's output.
+ */
+export type BatchTaskFn<I extends InputType = UnknownInputType, O extends OutputType = void> = (input: Record<string, I>, ctx: Context<Record<string, I>>) => O | Promise<O>;
 /**
  * Options for creating a hatchet task which is an atomic unit of work in a workflow.
  * @template I The input type for the task function.
@@ -156,6 +210,13 @@ export type CreateBaseTaskOpts<I extends InputType = UnknownInputType, O extends
     slotCost?: number;
     /** @internal */
     slotRequests?: Record<string, number>;
+    /**
+     * (optional) configures this task as a batch task. Not available on durable tasks.
+     * retries is always forced to 0 when batch is set.
+     *
+     * Preview: batch tasks are in beta and may change in future releases.
+     */
+    batch?: BatchTaskConfig;
 };
 export type CreateWorkflowTaskOpts<I extends InputType = UnknownInputType, O extends OutputType = void, C extends TaskFn<I, O> | DurableTaskFn<I, O> = TaskFn<I, O>> = CreateBaseTaskOpts<I, O, C> & {
     /**
@@ -221,7 +282,7 @@ export type CreateWorkflowTaskOpts<I extends InputType = UnknownInputType, O ext
  * @template I The input type for the task function.
  * @template O The return type of the task function (can be inferred from the return value of fn).
  */
-export type CreateWorkflowDurableTaskOpts<I extends InputType = UnknownInputType, O extends OutputType = void, C extends DurableTaskFn<I, O> = DurableTaskFn<I, O>> = Omit<CreateWorkflowTaskOpts<I, O, C>, 'slotCost'> & {
+export type CreateWorkflowDurableTaskOpts<I extends InputType = UnknownInputType, O extends OutputType = void, C extends DurableTaskFn<I, O> = DurableTaskFn<I, O>> = Omit<CreateWorkflowTaskOpts<I, O, C>, 'slotCost' | 'batch'> & {
     /**
      * Eviction policy for the durable task. Controls TTL-based eviction and capacity-based eviction.
      * Defaults to the built-in eviction policy when omitted or `undefined`.

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.26.2";
+export declare const HATCHET_VERSION = "1.28.0";

package/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HATCHET_VERSION = void 0;
-exports.HATCHET_VERSION = '1.26.2';
+exports.HATCHET_VERSION = '1.28.0';