@hatchet-dev/typescript-sdk 1.16.0 → 1.17.0

package/util/errors/eviction-not-supported-error.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvictionNotSupportedError = void 0;
+const v1_1 = require("../../v1");
+const hatchet_error_1 = __importDefault(require("./hatchet-error"));
+class EvictionNotSupportedError extends hatchet_error_1.default {
+    constructor(engineVersion) {
+        const versionInfo = engineVersion ? ` (engine ${engineVersion})` : '';
+        super(`Durable eviction is not supported by the connected engine${versionInfo}. ` +
+            `Please upgrade your Hatchet engine to ${v1_1.MinEngineVersion.DURABLE_EVICTION} or later.`);
+        this.name = 'EvictionNotSupportedError';
+        this.engineVersion = engineVersion;
+    }
+}
+exports.EvictionNotSupportedError = EvictionNotSupportedError;

package/util/errors/non-determinism-error.d.ts

@@ -0,0 +1,7 @@
+import HatchetError from './hatchet-error';
+export declare class NonDeterminismError extends HatchetError {
+    taskExternalId: string;
+    invocationCount: number;
+    nodeId: number;
+    constructor(taskExternalId: string, invocationCount: number, nodeId: number, message: string);
+}

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

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonDeterminismError = void 0;
+const hatchet_error_1 = __importDefault(require("./hatchet-error"));
+class NonDeterminismError extends hatchet_error_1.default {
+    constructor(taskExternalId, invocationCount, nodeId, message) {
+        const detail = message
+            ? 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`);
+        this.name = 'NonDeterminismError';
+        this.taskExternalId = taskExternalId;
+        this.invocationCount = invocationCount;
+        this.nodeId = nodeId;
+    }
+}
+exports.NonDeterminismError = NonDeterminismError;

package/util/errors/task-run-terminated-error.d.ts

@@ -0,0 +1,6 @@
+export type TaskRunTerminationReason = 'cancelled' | 'evicted';
+export declare class TaskRunTerminatedError extends Error {
+    readonly reason: TaskRunTerminationReason;
+    constructor(reason: TaskRunTerminationReason, message?: string);
+}
+export declare function isTaskRunTerminatedError(err: unknown): err is TaskRunTerminatedError;

package/util/errors/task-run-terminated-error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskRunTerminatedError = void 0;
+exports.isTaskRunTerminatedError = isTaskRunTerminatedError;
+class TaskRunTerminatedError extends Error {
+    constructor(reason, message) {
+        super(message !== null && message !== void 0 ? message : reason);
+        this.name = 'TaskRunTerminatedError';
+        this.reason = reason;
+    }
+}
+exports.TaskRunTerminatedError = TaskRunTerminatedError;
+function isTaskRunTerminatedError(err) {
+    return err instanceof TaskRunTerminatedError;
+}

package/util/hatchet-promise/hatchet-promise.d.ts

@@ -1,6 +1,7 @@
 /** Canonical reasons when cancelling a HatchetPromise (e.g. worker shutdown). */
 export declare enum CancellationReason {
-    CANCELLED_BY_WORKER = "Cancelled by worker"
+    CANCELLED_BY_WORKER = "Cancelled by worker",
+    EVICTED_BY_WORKER = "Evicted by worker"
 }
 declare class HatchetPromise<T> {
     cancel: (reason?: CancellationReason) => void;

package/util/hatchet-promise/hatchet-promise.js

@@ -1,17 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CancellationReason = void 0;
+const task_run_terminated_error_1 = require("../errors/task-run-terminated-error");
 /** Canonical reasons when cancelling a HatchetPromise (e.g. worker shutdown). */
 var CancellationReason;
 (function (CancellationReason) {
     CancellationReason["CANCELLED_BY_WORKER"] = "Cancelled by worker";
+    CancellationReason["EVICTED_BY_WORKER"] = "Evicted by worker";
 })(CancellationReason || (exports.CancellationReason = CancellationReason = {}));
+const reasonToTermination = {
+    [CancellationReason.CANCELLED_BY_WORKER]: 'cancelled',
+    [CancellationReason.EVICTED_BY_WORKER]: 'evicted',
+};
 class HatchetPromise {
     constructor(promise) {
         this.cancel = (_reason) => { };
         this.inner = Promise.resolve(promise);
         this.promise = new Promise((resolve, reject) => {
-            this.cancel = reject;
+            this.cancel = (reason) => {
+                const termination = reason ? reasonToTermination[reason] : 'cancelled';
+                reject(new task_run_terminated_error_1.TaskRunTerminatedError(termination, reason));
+            };
             this.inner.then(resolve).catch(reject);
         });
     }

package/util/sleep.d.ts

@@ -1,13 +1,14 @@
+import { Duration } from '../v1/client/duration';
 /**
  * Sleeps for a given number of milliseconds without blocking the event loop
  *
  * WARNING: This is not a durable sleep. It will not be honored if the worker is
  * restarted or crashes.
  *
- * @param ms - The number of milliseconds to sleep
+ * @param duration - The number of milliseconds to sleep, or a Duration (e.g. "5s", \{ seconds: 5 \})
  * @param signal - Optional AbortSignal; if aborted, the promise rejects with Error('Cancelled').
  *                 Use in task handlers so cancellation can interrupt long sleeps.
  * @returns A promise that resolves after the given number of milliseconds (or rejects on abort)
  */
-declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+declare function sleep(duration: number | Duration, signal?: AbortSignal): Promise<void>;
 export default sleep;

package/util/sleep.js

@@ -1,27 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const duration_1 = require("../v1/client/duration");
 /**
  * Sleeps for a given number of milliseconds without blocking the event loop
  *
  * WARNING: This is not a durable sleep. It will not be honored if the worker is
  * restarted or crashes.
  *
- * @param ms - The number of milliseconds to sleep
+ * @param duration - The number of milliseconds to sleep, or a Duration (e.g. "5s", \{ seconds: 5 \})
  * @param signal - Optional AbortSignal; if aborted, the promise rejects with Error('Cancelled').
  *                 Use in task handlers so cancellation can interrupt long sleeps.
  * @returns A promise that resolves after the given number of milliseconds (or rejects on abort)
  */
-function sleep(ms, signal) {
+function sleep(duration, signal) {
+    const timeout = typeof duration === 'number' ? duration : (0, duration_1.durationToMs)(duration);
     if (!signal) {
         return new Promise((resolve) => {
-            setTimeout(resolve, ms);
+            setTimeout(resolve, timeout);
         });
     }
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             signal.removeEventListener('abort', onAbort);
             resolve();
-        }, ms);
+        }, timeout);
         const onAbort = () => {
             clearTimeout(timer);
             reject(new Error('Cancelled'));

package/v1/client/admin.d.ts

@@ -1,9 +1,9 @@
 import { ClientConfig } from '../../clients/hatchet-client/client-config';
 import WorkflowRunRef from '../../util/workflow-run-ref';
-import { Priority, RateLimitDuration, RunsClient } from './..';
+import { Priority, RateLimitDuration, RunsClient, WorkerLabelComparator } from './..';
 import { RunListenerClient } from '../../clients/listeners/run-listener/child-listener-client';
 import { Api } from '../../clients/rest/generated/Api';
-import { WorkerLabelComparator, WorkflowServiceClient } from '../../protoc/workflows';
+import { WorkflowServiceClient } from '../../protoc/workflows';
 import { AdminServiceClient, CreateWorkflowVersionRequest } from '../../protoc/v1/workflows';
 import { Logger } from '../../util/logger';
 type DesiredWorkerLabelOpt = {

package/v1/client/client.js

@@ -304,7 +304,7 @@ class HatchetClient {
      */
     get durableListener() {
         if (!this._durableListener) {
-            this._durableListener = new durable_listener_client_1.DurableListenerClient(this._config, (0, grpc_helpers_1.channelFactory)(this._config, this._credentials), this._clientFactory, this.api);
+            this._durableListener = new durable_listener_client_1.DurableListenerClient(this._config, (0, grpc_helpers_1.channelFactory)(this._config, this._credentials), this._clientFactory);
         }
         return this._durableListener;
     }

package/v1/client/duration.d.ts

@@ -3,5 +3,15 @@ type MinutesDuration = `${number}m`;
 type HoursDuration = `${number}h`;
 type TwoUnitDurations = `${number}h${number}m` | `${number}h${number}s` | `${number}m${number}s`;
 type ThreeUnitDurations = `${number}h${number}m${number}s`;
-export type Duration = SecondsDuration | MinutesDuration | HoursDuration | TwoUnitDurations | ThreeUnitDurations;
+type DurationString = SecondsDuration | MinutesDuration | HoursDuration | TwoUnitDurations | ThreeUnitDurations;
+export interface DurationObject {
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+/** A number is treated as milliseconds. */
+export type Duration = DurationString | DurationObject | number;
+/** Normalizes a Duration to Go-style string format (e.g. "1h30m5s"). */
+export declare function durationToString(d: Duration): string;
+export declare function durationToMs(d: Duration): number;
 export {};

package/v1/client/duration.js

@@ -1,2 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.durationToString = durationToString;
+exports.durationToMs = durationToMs;
+const DURATION_RE = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/;
+/** Normalizes a Duration to Go-style string format (e.g. "1h30m5s"). */
+function durationToString(d) {
+    if (typeof d === 'string')
+        return d;
+    if (typeof d === 'number') {
+        const totalSeconds = Math.floor(d / 1000);
+        const h = Math.floor(totalSeconds / 3600);
+        const m = Math.floor((totalSeconds % 3600) / 60);
+        const s = totalSeconds % 60;
+        let out = '';
+        if (h)
+            out += `${h}h`;
+        if (m)
+            out += `${m}m`;
+        if (s || !out)
+            out += `${s}s`;
+        return out;
+    }
+    let s = '';
+    if (d.hours)
+        s += `${d.hours}h`;
+    if (d.minutes)
+        s += `${d.minutes}m`;
+    if (d.seconds)
+        s += `${d.seconds}s`;
+    return s || '0s';
+}
+function durationToMs(d) {
+    var _a, _b, _c;
+    if (typeof d === 'number')
+        return d;
+    if (typeof d === 'object') {
+        return (((_a = d.hours) !== null && _a !== void 0 ? _a : 0) * 3600 + ((_b = d.minutes) !== null && _b !== void 0 ? _b : 0) * 60 + ((_c = d.seconds) !== null && _c !== void 0 ? _c : 0)) * 1000;
+    }
+    const match = d.match(DURATION_RE);
+    if (!match) {
+        throw new Error(`Invalid duration string: "${d}". Expected format like "1h30m5s", "10m", "30s".`);
+    }
+    const [, h, m, s] = match;
+    return ((parseInt(h !== null && h !== void 0 ? h : '0', 10) * 3600 + parseInt(m !== null && m !== void 0 ? m : '0', 10) * 60 + parseInt(s !== null && s !== void 0 ? s : '0', 10)) * 1000);
+}

package/v1/client/features/runs.d.ts

@@ -106,10 +106,23 @@ export declare class RunsClient {
     private prepareFilter;
     private prepareListFilter;
     /**
-     * Creates a run reference for a task or workflow run by its ID.
-     * @param id - The ID of the run to create a reference for.
-     * @returns A promise that resolves to the run reference.
+     * Restore an evicted durable task so it can resume execution.
+     * @param taskExternalId - The external ID of the evicted task.
      */
+    restoreTask(taskExternalId: string): Promise<import("axios").AxiosResponse<import("../../../clients/rest/generated/data-contracts").V1RestoreTaskResponse, any, {}>>;
+    /**
+     * Fork (reset) a durable task from a specific node, triggering re-execution from that point.
+     * @param taskExternalId - The external ID of the durable task to reset.
+     * @param nodeId - The node ID to replay from.
+     */
+    branchDurableTask(taskExternalId: string, nodeId: number, branchId?: number): Promise<import("axios").AxiosResponse<import("../../../clients/rest/generated/data-contracts").V1BranchDurableTaskResponse, any, {}>>;
+    /**
+     * Resolve the task external ID for a workflow run. For runs with multiple tasks,
+     * returns the first task's external ID.
+     * @param workflowRunId - The workflow run ID to look up.
+     * @returns The task external ID.
+     */
+    getTaskExternalId(workflowRunId: string): Promise<string>;
     runRef<T extends Record<string, any> = any>(id: string): WorkflowRunRef<T>;
     /**
      * Subscribes to a stream of events for a task or workflow run by its ID.

package/v1/client/features/runs.js

@@ -147,10 +147,45 @@ class RunsClient {
         });
     }
     /**
-     * Creates a run reference for a task or workflow run by its ID.
-     * @param id - The ID of the run to create a reference for.
-     * @returns A promise that resolves to the run reference.
+     * Restore an evicted durable task so it can resume execution.
+     * @param taskExternalId - The external ID of the evicted task.
      */
+    restoreTask(taskExternalId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.api.v1TaskRestore(taskExternalId);
+        });
+    }
+    /**
+     * Fork (reset) a durable task from a specific node, triggering re-execution from that point.
+     * @param taskExternalId - The external ID of the durable task to reset.
+     * @param nodeId - The node ID to replay from.
+     */
+    branchDurableTask(taskExternalId_1, nodeId_1) {
+        return __awaiter(this, arguments, void 0, function* (taskExternalId, nodeId, branchId = 0) {
+            return this.api.v1DurableTaskBranch(this.tenantId, {
+                taskExternalId,
+                nodeId,
+                branchId,
+            });
+        });
+    }
+    /**
+     * Resolve the task external ID for a workflow run. For runs with multiple tasks,
+     * returns the first task's external ID.
+     * @param workflowRunId - The workflow run ID to look up.
+     * @returns The task external ID.
+     */
+    getTaskExternalId(workflowRunId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const run = yield this.get(workflowRunId);
+            const tasks = run === null || run === void 0 ? void 0 : run.tasks;
+            if (Array.isArray(tasks) && tasks.length > 0 && ((_a = tasks[0]) === null || _a === void 0 ? void 0 : _a.taskExternalId)) {
+                return tasks[0].taskExternalId;
+            }
+            throw new Error(`Could not find task external ID for workflow run ${workflowRunId}`);
+        });
+    }
     runRef(id) {
         return new workflow_run_ref_1.default(id, this.listener, this);
     }

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

@@ -8,23 +8,29 @@
  * @module Context
  */
 import { Priority, RunOpts, TaskWorkflowDeclaration, BaseWorkflowDeclaration as WorkflowV1 } from '../../declaration';
-import { JsonObject } from '@bufbuild/protobuf';
 import { Action } from '../../../clients/dispatcher/action-listener';
 import { Logger, LogLevel } from '../../../util/logger';
 import WorkflowRunRef from '../../../util/workflow-run-ref';
 import { Conditions } from '../../conditions';
 import { CreateWorkflowDurableTaskOpts, CreateWorkflowTaskOpts } from '../../task';
-import { OutputType } from '../../types';
+import { JsonObject, OutputType } from '../../types';
 import { HatchetClient } from '../..';
 import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
 import { NextStep } from '../../../legacy/step';
+import { DurableListenerClient } from '../../../clients/listeners/durable-listener/durable-listener-client';
+import { z } from 'zod';
 import { InternalWorker } from './worker-internal';
 import { Duration } from '../duration';
+import { DurableEvictionManager } from './eviction/eviction-manager';
 type TriggerData = Record<string, Record<string, any>>;
 type ChildRunOpts = RunOpts & {
     key?: string;
     sticky?: boolean;
 };
+export interface SleepResult {
+    /** The sleep duration in milliseconds. */
+    durationMs: number;
+}
 type LogExtra = {
     extra?: any;
     error?: Error;
@@ -207,7 +213,30 @@ export declare class Context<T, K = {}> {
      * @returns A promise that resolves when the data has been streamed.
      */
     putStream(data: string | Uint8Array): Promise<void>;
-    private spawnOptions;
+    protected spawnOptions(workflow: string | WorkflowV1<any, any>, options?: ChildRunOpts): {
+        workflowName: string;
+        opts: {
+            parentId: string;
+            parentTaskRunExternalId: string;
+            childIndex: number;
+            childKey: string | undefined;
+            desiredWorkerId: string | undefined;
+            _standaloneTaskName: string | undefined;
+            additionalMetadata?: {
+                [x: string]: string;
+            };
+            priority?: Priority;
+            sticky?: boolean;
+            returnExceptions?: boolean;
+            desiredWorkerLabels?: Record<string, {
+                value: string | number;
+                required?: boolean;
+                weight?: number;
+                comparator?: import("../..").WorkerLabelComparator;
+            }>;
+            key?: string;
+        };
+    };
     private spawn;
     private spawnBulk;
     /**
@@ -323,14 +352,26 @@ export declare class Context<T, K = {}> {
  * It extends the Context class and includes additional methods for durable execution like sleepFor and waitFor.
  */
 export declare class DurableContext<T, K = {}> extends Context<T, K> {
-    waitKey: number;
+    private _durableListener;
+    private _evictionManager;
+    private _engineVersion;
+    private _waitKey;
+    constructor(action: Action, v1: HatchetClient, worker: InternalWorker, durableListener: DurableListenerClient, evictionManager?: DurableEvictionManager, engineVersion?: string);
+    get supportsEviction(): boolean;
+    get durableListener(): DurableListenerClient;
+    /**
+     * The invocation count for the current durable task. Used for deduplication across replays.
+     */
+    get invocationCount(): number;
+    private get _actionKey();
+    private withEvictionWait;
     /**
      * 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 when the sleep duration has elapsed.
+     * @returns A promise that resolves with a SleepResult when the sleep duration has elapsed.
      */
-    sleepFor(duration: Duration, readableDataKey?: string): Promise<Record<string, any>>;
+    sleepFor(duration: Duration, readableDataKey?: 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.
@@ -338,5 +379,59 @@ export declare class DurableContext<T, K = {}> extends Context<T, K> {
      * @returns A promise that resolves with the event that satisfied the conditions.
      */
     waitFor(conditions: Conditions | Conditions[]): 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.
+     *
+     * For more complicated conditions, use `ctx.waitFor` directly.
+     *
+     * @param key - The event key to wait for.
+     * @param expression - An optional CEL expression to filter events.
+     * @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): Promise<z.infer<T>>;
+    waitForEvent(key: string, expression?: string): Promise<Record<string, any>>;
+    /**
+     * Durably sleep until a specific timestamp.
+     * Uses the memoized `now()` to compute the remaining duration, then delegates to `sleepFor`.
+     *
+     * @param wakeAt - The timestamp to sleep until.
+     * @returns A SleepResult containing the actual duration slept.
+     */
+    sleepUntil(wakeAt: Date): Promise<SleepResult>;
+    /**
+     * Get the current timestamp, memoized across replays. Returns the same Date on every replay of the same task run.
+     * @returns The memoized current timestamp.
+     */
+    now(): Promise<Date>;
+    private _waitForPreEviction;
+    private _buildTriggerOpts;
+    /**
+     * Spawns a child workflow through the durable event log, waits for the child to complete.
+     * @param workflow - The workflow to spawn.
+     * @param input - The input data for the child workflow.
+     * @param options - Options for spawning the child workflow.
+     * @returns The result of the child workflow.
+     */
+    spawnChild<Q extends JsonObject, P extends OutputType>(workflow: string | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input?: Q, options?: ChildRunOpts): Promise<P>;
+    /**
+     * Spawns multiple child workflows through the durable event log, waits for all to complete.
+     * @param children - An array of objects containing the workflow, input, and options for each child.
+     * @returns A list of results from the child workflows.
+     */
+    spawnChildren<Q extends JsonObject, P extends OutputType>(children: Array<{
+        workflow: string | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>;
+        input: Q;
+        options?: ChildRunOpts;
+    }>): Promise<P[]>;
+    /**
+     * Memoize a function by storing its result in durable storage. Avoids recomputation on replay.
+     *
+     * @param fn - The async function to compute the value.
+     * @param deps - Dependency values that form the memoization key.
+     * @returns The memoized value, either from durable storage or freshly computed.
+     */
+    private memo;
 }
 export {};