@hatchet-dev/typescript-sdk 1.21.0 → 1.21.1

package/clients/listeners/durable-listener/durable-listener-client.d.ts

@@ -41,6 +41,7 @@ export interface DurableTaskEventLogEntryResult {
 export interface WaitForEvent {
     kind: 'waitFor';
     waitForConditions: DurableEventListenerConditions;
+    label?: string;
 }
 export interface RunChildrenEvent {
     kind: 'runChildren';

package/clients/listeners/durable-listener/durable-listener-client.js

@@ -449,6 +449,7 @@ class DurableListenerClient {
                         invocationCount,
                         durableTaskExternalId,
                         waitForConditions: event.waitForConditions,
+                        label: event.label,
                     };
                     request = { waitFor: waitForReq };
                     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchet-dev/typescript-sdk",
-  "version": "1.21.0",
+  "version": "1.21.1",
   "description": "Background task orchestration & visibility for developers",
   "types": "dist/index.d.ts",
   "files": [

package/protoc/v1/dispatcher.d.ts

@@ -113,6 +113,11 @@ export interface DurableTaskWaitForRequest {
     durableTaskExternalId: string;
     /** Fields for DURABLE_TASK_TRIGGER_KIND_WAIT_FOR */
     waitForConditions?: DurableEventListenerConditions | undefined;
+    /**
+     * An optional human-readable label for this wait, displayed in the dashboard.
+     * Example: "Waiting for payment confirmation"
+     */
+    label?: string | undefined;
 }
 export interface DurableTaskRequest {
     registerWorker?: DurableTaskRequestRegisterWorker | undefined;

package/protoc/v1/dispatcher.js

@@ -1447,7 +1447,12 @@ exports.DurableTaskTriggerRunsRequest = {
     },
 };
 function createBaseDurableTaskWaitForRequest() {
-    return { invocationCount: 0, durableTaskExternalId: '', waitForConditions: undefined };
+    return {
+        invocationCount: 0,
+        durableTaskExternalId: '',
+        waitForConditions: undefined,
+        label: undefined,
+    };
 }
 exports.DurableTaskWaitForRequest = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -1460,6 +1465,9 @@ exports.DurableTaskWaitForRequest = {
         if (message.waitForConditions !== undefined) {
             condition_1.DurableEventListenerConditions.encode(message.waitForConditions, writer.uint32(26).fork()).join();
         }
+        if (message.label !== undefined) {
+            writer.uint32(34).string(message.label);
+        }
         return writer;
     },
     decode(input, length) {
@@ -1490,6 +1498,13 @@ exports.DurableTaskWaitForRequest = {
                     message.waitForConditions = condition_1.DurableEventListenerConditions.decode(reader, reader.uint32());
                     continue;
                 }
+                case 4: {
+                    if (tag !== 34) {
+                        break;
+                    }
+                    message.label = reader.string();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -1515,6 +1530,7 @@ exports.DurableTaskWaitForRequest = {
                 : isSet(object.wait_for_conditions)
                     ? condition_1.DurableEventListenerConditions.fromJSON(object.wait_for_conditions)
                     : undefined,
+            label: isSet(object.label) ? globalThis.String(object.label) : undefined,
         };
     },
     toJSON(message) {
@@ -1528,13 +1544,16 @@ exports.DurableTaskWaitForRequest = {
         if (message.waitForConditions !== undefined) {
             obj.waitForConditions = condition_1.DurableEventListenerConditions.toJSON(message.waitForConditions);
         }
+        if (message.label !== undefined) {
+            obj.label = message.label;
+        }
         return obj;
     },
     create(base) {
         return exports.DurableTaskWaitForRequest.fromPartial(base !== null && base !== void 0 ? base : {});
     },
     fromPartial(object) {
-        var _a, _b;
+        var _a, _b, _c;
         const message = createBaseDurableTaskWaitForRequest();
         message.invocationCount = (_a = object.invocationCount) !== null && _a !== void 0 ? _a : 0;
         message.durableTaskExternalId = (_b = object.durableTaskExternalId) !== null && _b !== void 0 ? _b : '';
@@ -1542,6 +1561,7 @@ exports.DurableTaskWaitForRequest = {
             object.waitForConditions !== undefined && object.waitForConditions !== null
                 ? condition_1.DurableEventListenerConditions.fromPartial(object.waitForConditions)
                 : undefined;
+        message.label = (_c = object.label) !== null && _c !== void 0 ? _c : undefined;
         return message;
     },
 };

package/util/errors/non-determinism-error.js

@@ -11,7 +11,7 @@ class NonDeterminismError extends hatchet_error_1.default {
             ? message
             : `Non-determinism detected in task ${taskExternalId} on invocation ${invocationCount} at node ${nodeId}`;
         super(`${detail}\n` +
-            `Check out our documentation for more details on expectations of durable tasks: https://docs.hatchet.run/v1/patterns/mixing-patterns`);
+            `Check out our documentation for more details on expectations of durable tasks: https://docs.hatchet.run/v1/patterns`);
         this.name = 'NonDeterminismError';
         this.taskExternalId = taskExternalId;
         this.invocationCount = invocationCount;

package/v1/client/worker/context.d.ts

@@ -31,6 +31,12 @@ export interface SleepResult {
     /** The sleep duration in milliseconds. */
     durationMs: number;
 }
+export interface SleepForOptions {
+    /** Optional key used for condition result indexing. */
+    readableDataKey?: string;
+    /** Optional human-readable wait label shown in dashboard run details. */
+    label?: string;
+}
 type LogExtra = {
     extra?: any;
     error?: Error;
@@ -371,16 +377,20 @@ export declare class DurableContext<T, K = {}> extends Context<T, K> {
      * Pauses execution for the specified duration.
      * Duration is "global" meaning it will wait in real time regardless of transient failures like worker restarts.
      * @param duration - The duration to sleep for.
+     * @param readableDataKeyOrOptions - Optional readable key string or options object containing readableDataKey and label.
+     * @param label - Optional wait label used when readableDataKey is passed as the second argument.
      * @returns A promise that resolves with a SleepResult when the sleep duration has elapsed.
      */
+    sleepFor(duration: Duration, options?: SleepForOptions): Promise<SleepResult>;
     sleepFor(duration: Duration, readableDataKey?: string): Promise<SleepResult>;
+    sleepFor(duration: Duration, readableDataKey?: string, label?: string): Promise<SleepResult>;
     /**
      * Pauses execution until the specified conditions are met.
      * Conditions are "global" meaning they will wait in real time regardless of transient failures like worker restarts.
      * @param conditions - The conditions to wait for.
      * @returns A promise that resolves with the event that satisfied the conditions.
      */
-    waitFor(conditions: Conditions | Conditions[]): Promise<Record<string, any>>;
+    waitFor(conditions: Conditions | Conditions[], label?: string): Promise<Record<string, any>>;
     /**
      * Lightweight wrapper for waiting for a user event. Allows for shorthand usage of
      * `ctx.waitFor` when specifying a user event condition.
@@ -392,8 +402,8 @@ export declare class DurableContext<T, K = {}> extends Context<T, K> {
      * @param payloadSchema - An optional Zod schema to validate and parse the event payload.
      * @returns The event payload, validated against the schema if provided.
      */
-    waitForEvent<T extends z.ZodTypeAny>(key: string, expression?: string, payloadSchema?: T, scope?: string, lookbackWindow?: Duration): Promise<z.infer<T>>;
-    waitForEvent(key: string, expression?: string, payloadSchema?: undefined, scope?: string, lookbackWindow?: Duration): Promise<Record<string, any>>;
+    waitForEvent<T extends z.ZodTypeAny>(key: string, expression?: string, payloadSchema?: T, scope?: string, lookbackWindow?: Duration, label?: string): Promise<z.infer<T>>;
+    waitForEvent(key: string, expression?: string, payloadSchema?: undefined, scope?: string, lookbackWindow?: Duration, label?: string): Promise<Record<string, any>>;
     /**
      * Durably sleep until a specific timestamp.
      * Uses the memoized `now()` to compute the remaining duration, then delegates to `sleepFor`.

package/v1/client/worker/context.js

@@ -683,15 +683,12 @@ class DurableContext extends Context {
             }
         });
     }
-    /**
-     * Pauses execution for the specified duration.
-     * Duration is "global" meaning it will wait in real time regardless of transient failures like worker restarts.
-     * @param duration - The duration to sleep for.
-     * @returns A promise that resolves with a SleepResult when the sleep duration has elapsed.
-     */
-    sleepFor(duration, readableDataKey) {
+    sleepFor(duration, readableDataKeyOrOptions, label) {
         return __awaiter(this, void 0, void 0, function* () {
-            const res = yield this.waitFor({ sleepFor: duration, readableDataKey });
+            const opts = typeof readableDataKeyOrOptions === 'string'
+                ? { readableDataKey: readableDataKeyOrOptions, label }
+                : (readableDataKeyOrOptions !== null && readableDataKeyOrOptions !== void 0 ? readableDataKeyOrOptions : {});
+            const res = yield this.waitFor({ sleepFor: duration, readableDataKey: opts.readableDataKey }, opts.label);
             const matches = res['CREATE'] || {};
             const [firstMatch] = Object.values(matches);
             if (!firstMatch || firstMatch.length === 0) {
@@ -718,7 +715,7 @@ class DurableContext extends Context {
      * @param conditions - The conditions to wait for.
      * @returns A promise that resolves with the event that satisfied the conditions.
      */
-    waitFor(conditions) {
+    waitFor(conditions, label) {
         return __awaiter(this, void 0, void 0, function* () {
             this.throwIfCancelled();
             if (!this.supportsEviction) {
@@ -732,6 +729,7 @@ class DurableContext extends Context {
                     sleepConditions: pbConditions.sleepConditions,
                     userEventConditions: pbConditions.userEventConditions,
                 },
+                label,
             });
             const resourceId = rendered
                 .map((c) => c.base.readableDataKey)
@@ -743,7 +741,7 @@ class DurableContext extends Context {
             }));
         });
     }
-    waitForEvent(key, expression, payloadSchema, scope, lookbackWindow) {
+    waitForEvent(key, expression, payloadSchema, scope, lookbackWindow, label) {
         return __awaiter(this, void 0, void 0, function* () {
             const now = yield this.now();
             const considerEventsSince = lookbackWindow
@@ -754,7 +752,7 @@ class DurableContext extends Context {
                 expression,
                 scope,
                 considerEventsSince,
-            });
+            }, label);
             // The engine returns an object like:
             // {"CREATE": {"signal_key_1": [{"id": ..., "data": {...}}]}}
             // Since we have a single match, the list will only have one item.

package/v1/examples/__e2e__/harness.js

@@ -71,9 +71,14 @@ function poll(fn_1, _a) {
     return __awaiter(this, arguments, void 0, function* (fn, { timeoutMs = 30000, intervalMs = 100, shouldStop, label = 'poll', }) {
         const start = Date.now();
         while (true) {
-            const value = yield fn();
-            if (shouldStop(value)) {
-                return value;
+            try {
+                const value = yield fn();
+                if (shouldStop(value)) {
+                    return value;
+                }
+            }
+            catch (_b) {
+                // retry on transient errors
             }
             if (Date.now() - start > timeoutMs) {
                 throw new Error(`Timed out waiting for ${label} after ${timeoutMs}ms`);

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

@@ -54,10 +54,13 @@ export declare const durableReplayReset: import("../..").TaskWorkflowDeclaration
 }, {}, {}, {}, {}>;
 export declare const LOOKBACK_WINDOW: "1m";
 export declare const waitForEventLookback: import("../..").TaskWorkflowDeclaration<{
-    scope: string;
+    userId: number;
 }, {
     elapsed: number;
-    event: any;
+    event: {
+        order: string;
+        user_id: number;
+    };
 }, {}, {}, {}, {}>;
 export declare const waitForOrEventLookback: import("../..").TaskWorkflowDeclaration<{
     scope: string;

package/v1/examples/durable/workflow.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.durableSpawnDag = exports.dagChildWorkflow = exports.memoNowCaching = exports.waitForTwoEventsSecondPushedFirst = exports.waitForOrEventLookback = exports.waitForEventLookback = exports.LOOKBACK_WINDOW = exports.durableReplayReset = exports.REPLAY_RESET_MEMOIZED_MAX_SECONDS = exports.REPLAY_RESET_SLEEP_SECONDS = exports.durableNonDeterminism = exports.durableWithExplicitSpawn = exports.durableSleepEventSpawn = exports.durableWithBulkSpawn = exports.durableWithSpawn = exports.spawnChildTask = exports.waitForSleepTwice = exports.durableWorkflow = exports.SLEEP_TIME = exports.SLEEP_TIME_SECONDS = exports.EVENT_KEY = void 0;
+const zod_1 = require("zod");
 const conditions_1 = require("../../conditions");
 const non_determinism_error_1 = require("../../../util/errors/non-determinism-error");
 const sleep_1 = __importDefault(require("../../../util/sleep"));
@@ -37,7 +38,7 @@ exports.durableWorkflow.durableTask({
     executionTimeout: '10m',
     fn: (_input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
         console.log('Waiting for sleep');
-        const sleepResult = yield ctx.sleepFor(exports.SLEEP_TIME);
+        const sleepResult = yield ctx.sleepFor(exports.SLEEP_TIME, { label: 'waiting for sleep' });
         console.log('Sleep finished');
         console.log('Waiting for event');
         const event = yield ctx.waitForEvent(exports.EVENT_KEY, 'true');
@@ -225,12 +226,18 @@ exports.durableReplayReset = hatchet_client_1.hatchet.durableTask({
     }),
 });
 exports.LOOKBACK_WINDOW = '1m';
+const lookbackEventPayloadSchema = zod_1.z.object({
+    order: zod_1.z.string(),
+    user_id: zod_1.z.number(),
+});
 exports.waitForEventLookback = hatchet_client_1.hatchet.durableTask({
     name: 'wait-for-event-lookback',
     executionTimeout: '10m',
     fn: (input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
         const start = Date.now();
-        const event = yield ctx.waitForEvent(exports.EVENT_KEY, undefined, undefined, input.scope, exports.LOOKBACK_WINDOW);
+        // > Wait for event with lookback
+        const event = yield ctx.waitForEvent('user:create', `input.user_id == ${input.userId}`, lookbackEventPayloadSchema, `user_id:${input.userId}`, '1m');
+        // !!
         return {
             elapsed: (Date.now() - start) / 1000,
             event,

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

@@ -1,7 +1,11 @@
 export declare const EVENT_KEY = "user:update";
+export declare const SCOPE = "user-1234";
 export declare const durableEvent: import("../..").TaskWorkflowDeclaration<import("../..").JsonObject, {
     Value: string;
 }, {}, {}, {}, {}>;
 export declare const durableEventWithFilter: import("../..").TaskWorkflowDeclaration<import("../..").JsonObject, {
     Value: string;
 }, {}, {}, {}, {}>;
+export declare const durableEventWithLookback: import("../..").TaskWorkflowDeclaration<import("../..").JsonObject, {
+    Value: string;
+}, {}, {}, {}, {}>;

package/v1/examples/durable_event/workflow.js

@@ -9,9 +9,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.durableEventWithFilter = exports.durableEvent = exports.EVENT_KEY = void 0;
+exports.durableEventWithLookback = exports.durableEventWithFilter = exports.durableEvent = exports.SCOPE = exports.EVENT_KEY = void 0;
 const hatchet_client_1 = require("../hatchet-client");
 exports.EVENT_KEY = 'user:update';
+exports.SCOPE = 'user-1234';
 // > Durable Event
 exports.durableEvent = hatchet_client_1.hatchet.durableTask({
     name: 'durable-event',
@@ -39,3 +40,16 @@ exports.durableEventWithFilter = hatchet_client_1.hatchet.durableTask({
     }),
 });
 // !!
+// > Durable Event With Lookback
+exports.durableEventWithLookback = hatchet_client_1.hatchet.durableTask({
+    name: 'durable-event-with-lookback',
+    executionTimeout: '10m',
+    fn: (_, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+        const res = yield ctx.waitForEvent(exports.EVENT_KEY, undefined, undefined, exports.SCOPE, '1m');
+        console.log('res', res);
+        return {
+            Value: 'done',
+        };
+    }),
+});
+// !!

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

@@ -1,3 +1,10 @@
-export declare const affinityExampleTask: import("../..").TaskWorkflowDeclaration<import("../..").UnknownInputType, {
-    worker_id: string | undefined;
-}, {}, {}, {}, {}>;
+type AffinityOutput = {
+    affinity_t1: {
+        worker_id: string | undefined;
+    };
+    affinity_t2: {
+        worker_id: string | undefined;
+    };
+};
+export declare const affinityExampleTask: import("../..").WorkflowDeclaration<{}, AffinityOutput, {}>;
+export {};

package/v1/examples/runtime_affinity/workflow.js

@@ -11,8 +11,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.affinityExampleTask = void 0;
 const hatchet_client_1 = require("../hatchet-client");
-exports.affinityExampleTask = hatchet_client_1.hatchet.task({
-    name: 'affinity-example-task',
+exports.affinityExampleTask = hatchet_client_1.hatchet.workflow({
+    name: 'runtime_affinity_workflow',
+});
+const affinityT1 = exports.affinityExampleTask.task({
+    name: 'affinity_t1',
+    fn: (input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+        return { worker_id: ctx.worker.id() };
+    }),
+});
+exports.affinityExampleTask.task({
+    name: 'affinity_t2',
+    parents: [affinityT1],
     fn: (input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
         return { worker_id: ctx.worker.id() };
     }),

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.21.0";
+export declare const HATCHET_VERSION = "1.21.1";

package/version.js

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