@hatchet-dev/typescript-sdk 1.0.0-alpha1 → 1.0.0

package/step.js

@@ -45,13 +45,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.ContextWorker = exports.CreateStepSchema = exports.DesiredWorkerLabelSchema = exports.CreateRateLimitSchema = void 0;
+exports.DurableContext = exports.Context = exports.ContextWorker = exports.CreateStepSchema = exports.DesiredWorkerLabelSchema = exports.CreateRateLimitSchema = void 0;
 exports.mapRateLimit = mapRateLimit;
 /* eslint-disable max-classes-per-file */
 const hatchet_error_1 = __importDefault(require("./util/errors/hatchet-error"));
 const z = __importStar(require("zod"));
 const parse_1 = require("./util/parse");
 const workflows_1 = require("./protoc/workflows");
+const conditions_1 = require("./v1/conditions");
+const condition_1 = require("./protoc/v1/shared/condition");
+const transformer_1 = require("./v1/conditions/transformer");
 exports.CreateRateLimitSchema = z.object({
     key: z.string().optional(),
     staticKey: z.string().optional(),
@@ -93,15 +96,33 @@ class ContextWorker {
     constructor(worker) {
         this.worker = worker;
     }
+    /**
+     * Gets the ID of the worker.
+     * @returns The ID of the worker.
+     */
     id() {
         return this.worker.workerId;
     }
+    /**
+     * Checks if the worker has a registered workflow.
+     * @param workflowName - The name of the workflow to check.
+     * @returns True if the workflow is registered, otherwise false.
+     */
     hasWorkflow(workflowName) {
-        return !!this.worker.workflow_registry.find((workflow) => workflow.id === workflowName);
+        return !!this.worker.workflow_registry.find((workflow) => 'id' in workflow ? workflow.id === workflowName : workflow.name === workflowName);
     }
+    /**
+     * Gets the current state of the worker labels.
+     * @returns The labels of the worker.
+     */
     labels() {
         return this.worker.labels;
     }
+    /**
+     * Upserts the a set of labels on the worker.
+     * @param labels - The labels to upsert.
+     * @returns A promise that resolves when the labels have been upserted.
+     */
     upsertLabels(labels) {
         return this.worker.upsertLabels(labels);
     }
@@ -132,66 +153,130 @@ class Context {
             throw new hatchet_error_1.default(`Could not parse payload: ${e.message}`);
         }
     }
-    // NOTE: parentData is async since we plan on potentially making this a cacheable server call
-    parentData(task) {
+    /**
+     * Retrieves the output of a parent task.
+     * @param task - The name of the task or a CreateTaskOpts object.
+     * @returns The output of the specified parent task.
+     * @throws An error if the task output is not found.
+     *
+     */
+    parentOutput(task) {
         return __awaiter(this, void 0, void 0, function* () {
+            // NOTE: parentOutput is async since we plan on potentially making this a cacheable server call
             if (typeof task === 'string') {
                 return this.stepOutput(task);
             }
             return this.stepOutput(task.name);
         });
     }
-    // TODO deprecated
+    /**
+     * Get the output of a task.
+     * @param task - The name of the task to get the output for.
+     * @returns The output of the task.
+     * @throws An error if the task output is not found.
+     * @deprecated use ctx.parentOutput instead
+     */
     stepOutput(step) {
         if (!this.data.parents) {
-            throw new hatchet_error_1.default('Step output not found');
+            throw new hatchet_error_1.default('output not found');
         }
         if (!this.data.parents[step]) {
-            throw new hatchet_error_1.default(`Step output for '${step}' not found`);
+            throw new hatchet_error_1.default(`output for '${step}' not found`);
         }
         return this.data.parents[step];
     }
+    /**
+     * Returns errors from any task runs in the workflow.
+     * @returns A record mapping task names to error messages.
+     * @throws A warning if no errors are found (this method should be used in on-failure tasks).
+     * @deprecated use ctx.errors instead
+     */
     stepRunErrors() {
+        return this.errors();
+    }
+    /**
+     * Returns errors from any task runs in the workflow.
+     * @returns A record mapping task names to error messages.
+     * @throws A warning if no errors are found (this method should be used in on-failure tasks).
+     */
+    errors() {
         const errors = this.data.step_run_errors || {};
         if (Object.keys(errors).length === 0) {
-            this.logger.error('No step run errors found. `ctx.stepRunErrors` is intended to be run in an on-failure step, and will only work on engine versions more recent than v0.53.10');
+            this.logger.error('No run errors found. `ctx.errors` is intended to be run in an on-failure task, and will only work on engine versions more recent than v0.53.10');
         }
         return errors;
     }
+    /**
+     * Gets the dag conditional triggers for the current workflow run.
+     * @returns The triggers for the current workflow.
+     */
+    triggers() {
+        return this.data.triggers;
+    }
+    /**
+     * Determines if the workflow was triggered by an event.
+     * @returns True if the workflow was triggered by an event, otherwise false.
+     */
     triggeredByEvent() {
         var _a;
         return ((_a = this.data) === null || _a === void 0 ? void 0 : _a.triggered_by) === 'event';
     }
+    /**
+     * Gets the input data for the current workflow.
+     * @returns The input data for the workflow.
+     */
     workflowInput() {
         return this.input;
     }
+    /**
+     * Gets the name of the current workflow.
+     * @returns The name of the workflow.
+     */
     workflowName() {
         return this.action.jobName;
     }
+    /**
+     * Gets the user data associated with the workflow.
+     * @returns The user data.
+     */
     userData() {
         var _a;
         return (_a = this.data) === null || _a === void 0 ? void 0 : _a.user_data;
     }
+    /**
+     * Gets the name of the current task.
+     * @returns The name of the task.
+     * @deprecated use ctx.taskName instead
+     */
     stepName() {
+        return this.taskName();
+    }
+    /**
+     * Gets the name of the current running task.
+     * @returns The name of the task.
+     */
+    taskName() {
         return this.action.stepName;
     }
+    /**
+     * Gets the ID of the current workflow run.
+     * @returns The workflow run ID.
+     */
     workflowRunId() {
         return this.action.workflowRunId;
     }
+    /**
+     * Gets the number of times the current task has been retried.
+     * @returns The retry count.
+     */
     retryCount() {
         return this.action.retryCount;
     }
-    playground(name, defaultValue = '') {
-        if (name in this.overridesData) {
-            return this.overridesData[name];
-        }
-        this.client.dispatcher.putOverridesData({
-            stepRunId: this.action.stepRunId,
-            path: name,
-            value: JSON.stringify(defaultValue),
-        });
-        return defaultValue;
-    }
+    /**
+     * Logs a message from the current task.
+     * @param message - The message to log.
+     * @param level - The log level (optional).
+     */
     log(message, level) {
         const { stepRunId } = this.action;
         if (!stepRunId) {
@@ -202,10 +287,9 @@ class Context {
         this.client.event.putLog(stepRunId, message, level);
     }
     /**
-     * Refreshes the timeout for the current step.
+     * Refreshes the timeout for the current task.
      * @param incrementBy - The interval by which to increment the timeout.
-     *                     The interval should be specified in the format of '10s' for 10 seconds,
-     *                     '1m' for 1 minute, or '1d' for 1 day.
+     * The interval should be specified in the format of '10s' for 10 seconds, '1m' for 1 minute, or '1d' for 1 day.
      */
     refreshTimeout(incrementBy) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -218,6 +302,11 @@ class Context {
             yield this.client.dispatcher.refreshTimeout(incrementBy, stepRunId);
         });
     }
+    /**
+     * Releases a worker slot for a task run such that the worker can pick up another task.
+     * Note: this is an advanced feature that may lead to unexpected behavior if used incorrectly.
+     * @returns A promise that resolves when the slot has been released.
+     */
     releaseSlot() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.client.dispatcher.client.releaseSlot({
@@ -225,6 +314,11 @@ class Context {
             });
         });
     }
+    /**
+     * Streams data from the current task run.
+     * @param data - The data to stream (string or binary).
+     * @returns A promise that resolves when the data has been streamed.
+     */
     putStream(data) {
         return __awaiter(this, void 0, void 0, function* () {
             const { stepRunId } = this.action;
@@ -237,31 +331,31 @@ class Context {
         });
     }
     /**
-     * Enqueues multiple children workflows in parallel.
-     * @param children an array of objects containing the workflow name, input data, and options for each workflow
-     * @returns a list of workflow run references to the enqueued runs
+     * Runs multiple children workflows in parallel without waiting for their results.
+     * @param children - An array of  objects containing the workflow name, input data, and options for each workflow.
+     * @returns A list of workflow run references to the enqueued runs.
      */
-    bulkEnqueueChildren(children) {
+    bulkRunNoWaitChildren(children) {
         return this.spawnWorkflows(children);
     }
     /**
-     * Runs multiple children workflows in parallel.
-     * @param children an array of objects containing the workflow name, input data, and options for each workflow
-     * @returns a list of results from the children workflows
+     * Runs multiple children workflows in parallel and waits for all results.
+     * @param children - An array of objects containing the workflow name, input data, and options for each workflow.
+     * @returns A list of results from the children workflows.
      */
     bulkRunChildren(children) {
         return __awaiter(this, void 0, void 0, function* () {
-            const runs = yield this.bulkEnqueueChildren(children);
-            const res = runs.map((run) => run.result());
+            const runs = yield this.bulkRunNoWaitChildren(children);
+            const res = runs.map((run) => run.output);
             return Promise.all(res);
         });
     }
     /**
      * Spawns multiple workflows.
      *
-     * @param workflows an array of objects containing the workflow name, input data, and options for each workflow
-     * @returns a list of references to the spawned workflow runs
-     * @deprecated use bulkEnqueueChildren or bulkRunChildren instead
+     * @param workflows - An array of objects containing the workflow name, input data, and options for each workflow.
+     * @returns A list of references to the spawned workflow runs.
+     * @deprecated Use bulkRunNoWaitChildren or bulkRunChildren instead.
      */
     spawnWorkflows(workflows) {
         const { workflowRunId, stepRunId } = this.action;
@@ -309,50 +403,38 @@ class Context {
         }
     }
     /**
-     * Runs a new workflow.
+     * Runs a new workflow and waits for its result.
      *
-     * @param workflow the workflow to run
-     * @param input the input data for the workflow
-     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
-     * @param <Q> the type of the input data
-     * @param <P> the type of the output data
-     * @return the result of the workflow
+     * @param workflow - The workflow to run (name, Workflow instance, or WorkflowV1 instance).
+     * @param input - The input data for the workflow.
+     * @param options - Additional options for spawning the workflow. If a string is provided, it is used as the key.
+     * @returns The result of the workflow.
      */
     runChild(workflow, input, options) {
         return __awaiter(this, void 0, void 0, function* () {
             const run = yield this.spawnWorkflow(workflow, input, options);
-            return run.result();
+            return run.output;
         });
     }
     /**
-     * Enqueues a new workflow.
+     * Enqueues a new workflow without waiting for its result.
      *
-     * @param workflowName the name of the workflow to spawn
-     * @param input the input data for the workflow
-     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
-     *                If an object is provided, it can include:
-     *                - key: a unique identifier for the workflow (deprecated, use options.key instead)
-     *                - sticky: a boolean indicating whether to use sticky execution
-     * @param <Q> the type of the input data
-     * @param <P> the type of the output data
-     * @return a reference to the spawned workflow run
-     */
-    enqueueChild(workflow, input, options) {
+     * @param workflow - The workflow to enqueue (name, Workflow instance, or WorkflowV1 instance).
+     * @param input - The input data for the workflow.
+     * @param options - Additional options for spawning the workflow.
+     * @returns A reference to the spawned workflow run.
+     */
+    runNoWaitChild(workflow, input, options) {
         return this.spawnWorkflow(workflow, input, options);
     }
     /**
      * Spawns a new workflow.
      *
-     * @param workflowName the name of the workflow to spawn
-     * @param input the input data for the workflow
-     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
-     *                If an object is provided, it can include:
-     *                - key: a unique identifier for the workflow (deprecated, use options.key instead)
-     *                - sticky: a boolean indicating whether to use sticky execution
-     * @param <Q> the type of the input data
-     * @param <P> the type of the output data
-     * @return a reference to the spawned workflow run
-     * @deprecated use runChild or enqueueChild instead
+     * @param workflow - The workflow to spawn (name, Workflow instance, or WorkflowV1 instance).
+     * @param input - The input data for the workflow.
+     * @param options - Additional options for spawning the workflow.
+     * @returns A reference to the spawned workflow run.
+     * @deprecated Use runChild or runNoWaitChild instead.
      */
     spawnWorkflow(workflow, input, options) {
         const { workflowRunId, stepRunId } = this.action;
@@ -395,6 +477,10 @@ class Context {
             throw new hatchet_error_1.default(e.message);
         }
     }
+    /**
+     * Retrieves additional metadata associated with the current workflow run.
+     * @returns A record of metadata key-value pairs.
+     */
     additionalMetadata() {
         if (!this.action.additionalMetadata) {
             return {};
@@ -403,17 +489,75 @@ class Context {
         const res = (0, parse_1.parseJSON)(this.action.additionalMetadata);
         return res;
     }
+    /**
+     * Gets the index of this workflow if it was spawned as part of a bulk operation.
+     * @returns The child index number, or undefined if not set.
+     */
     childIndex() {
         return this.action.childWorkflowIndex;
     }
+    /**
+     * Gets the key associated with this workflow if it was spawned as a child workflow.
+     * @returns The child key, or undefined if not set.
+     */
     childKey() {
         return this.action.childWorkflowKey;
     }
+    /**
+     * Gets the ID of the parent workflow run if this workflow was spawned as a child.
+     * @returns The parent workflow run ID, or undefined if not a child workflow.
+     */
     parentWorkflowRunId() {
         return this.action.parentWorkflowRunId;
     }
 }
 exports.Context = Context;
+class DurableContext extends Context {
+    constructor() {
+        super(...arguments);
+        this.waitKey = 0;
+    }
+    /**
+     * 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.
+     */
+    sleepFor(duration, readableDataKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.waitFor({ sleepFor: duration, readableDataKey });
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const pbConditions = (0, transformer_1.conditionsToPb)((0, conditions_1.Render)(condition_1.Action.CREATE, conditions));
+            // eslint-disable-next-line no-plusplus
+            const key = `waitFor-${this.waitKey++}`;
+            yield this.client.durableListener.registerDurableEvent({
+                taskId: this.action.stepRunId,
+                signalKey: key,
+                sleepConditions: pbConditions.sleepConditions,
+                userEventConditions: pbConditions.userEventConditions,
+            });
+            const listener = this.client.durableListener.subscribe({
+                taskId: this.action.stepRunId,
+                signalKey: key,
+            });
+            const event = yield listener.get();
+            // Convert event.data from Uint8Array to string if needed
+            const eventData = event.data instanceof Uint8Array ? new TextDecoder().decode(event.data) : event.data;
+            const res = JSON.parse(eventData);
+            return res.CREATE;
+        });
+    }
+}
+exports.DurableContext = DurableContext;
 function mapRateLimit(limits) {
     if (!limits)
         return [];

package/util/sleep.d.ts

@@ -1,2 +1,9 @@
+/**
+ * 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
+ * @returns A promise that resolves after the given number of milliseconds
+ */
 declare const sleep: (ms: number) => Promise<unknown>;
 export default sleep;

package/util/sleep.js

@@ -1,5 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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
+ * @returns A promise that resolves after the given number of milliseconds
+ */
 const sleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });

package/util/workflow-run-ref.d.ts

@@ -1,4 +1,4 @@
-import { ListenerClient, StepRunEvent } from '../clients/listener/listener-client';
+import { RunListenerClient, StepRunEvent } from '../clients/listeners/run-listener/child-listener-client';
 type EventualWorkflowRunId = string | Promise<string> | Promise<{
     workflowRunId: string;
 }>;
@@ -11,9 +11,15 @@ export default class WorkflowRunRef<T> {
     private client;
     constructor(workflowRunId: string | Promise<string> | Promise<{
         workflowRunId: string;
-    }>, client: ListenerClient, parentWorkflowRunId?: string);
+    }>, client: RunListenerClient, parentWorkflowRunId?: string);
+    get runId(): Promise<string>;
     getWorkflowRunId(): Promise<string>;
     stream(): Promise<AsyncGenerator<StepRunEvent, void, unknown>>;
+    get output(): Promise<T>;
+    /**
+     * @alias output
+     * @deprecated use output
+     */
     result(): Promise<T>;
     toJSON(): Promise<string>;
 }

package/util/workflow-run-ref.js

@@ -55,6 +55,11 @@ class WorkflowRunRef {
         this.parentWorkflowRunId = parentWorkflowRunId;
         this.client = client;
     }
+    // TODO docstrings
+    get runId() {
+        return this.getWorkflowRunId();
+    }
+    // @deprecated use runId
     getWorkflowRunId() {
         return __awaiter(this, void 0, void 0, function* () {
             return getWorkflowRunId(this.workflowRunId);
@@ -66,6 +71,14 @@ class WorkflowRunRef {
             return this.client.stream(workflowRunId);
         });
     }
+    // TODO not sure if i want this to be a get since it might be blocking for a long time..
+    get output() {
+        return this.result();
+    }
+    /**
+     * @alias output
+     * @deprecated use output
+     */
     result() {
         return __awaiter(this, void 0, void 0, function* () {
             const workflowRunId = yield getWorkflowRunId(this.workflowRunId);