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

package/protoc/workflows/workflows.js

@@ -1,7 +1,7 @@
 "use strict";
 // Code generated by protoc-gen-ts_proto. DO NOT EDIT.
 // versions:
-//   protoc-gen-ts_proto  v2.6.0
+//   protoc-gen-ts_proto  v2.6.1
 //   protoc               v3.19.1
 // source: workflows/workflows.proto
 Object.defineProperty(exports, "__esModule", { value: true });

package/step.d.ts

@@ -8,8 +8,10 @@ import WorkflowRunRef from './util/workflow-run-ref';
 import { V0Worker } from './clients/worker';
 import { WorkerLabels } from './clients/dispatcher/dispatcher-client';
 import { CreateStepRateLimit, RateLimitDuration, WorkerLabelComparator } from './protoc/workflows';
-import { CreateTaskOpts } from './v1/task';
-import { WorkflowDeclaration as WorkflowV1 } from './v1/workflow';
+import { CreateWorkflowTaskOpts } from './v1/task';
+import { BaseWorkflowDeclaration as WorkflowV1 } from './v1/declaration';
+import { Conditions } from './v1/conditions';
+import { Duration } from './v1/client/duration';
 export declare const CreateRateLimitSchema: z.ZodObject<{
     key: z.ZodOptional<z.ZodString>;
     staticKey: z.ZodOptional<z.ZodString>;
@@ -159,8 +161,10 @@ export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 export type NextStep = {
     [key: string]: JsonValue;
 };
+type TriggerData = Record<string, Record<string, any>>;
 interface ContextData<T, K> {
     input: T;
+    triggers: TriggerData;
     parents: Record<string, any>;
     triggered_by: string;
     user_data: K;
@@ -169,9 +173,27 @@ interface ContextData<T, K> {
 export declare class ContextWorker {
     private worker;
     constructor(worker: V0Worker);
+    /**
+     * Gets the ID of the worker.
+     * @returns The ID of the worker.
+     */
     id(): string | undefined;
+    /**
+     * 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: string): boolean;
+    /**
+     * Gets the current state of the worker labels.
+     * @returns The labels of the worker.
+     */
     labels(): WorkerLabels;
+    /**
+     * 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: WorkerLabels): Promise<WorkerLabels>;
 }
 export declare class Context<T, K = {}> {
@@ -185,33 +207,111 @@ export declare class Context<T, K = {}> {
     logger: Logger;
     spawnIndex: number;
     constructor(action: Action, client: InternalHatchetClient, worker: V0Worker);
-    parentData<L = NextStep>(task: CreateTaskOpts<any, L> | string): Promise<L>;
+    /**
+     * 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<L = NextStep>(task: CreateWorkflowTaskOpts<any, L> | string): Promise<L>;
+    /**
+     * 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<L = NextStep>(step: string): L;
+    /**
+     * 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(): Record<string, string>;
+    /**
+     * 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(): Record<string, string>;
+    /**
+     * Gets the dag conditional triggers for the current workflow run.
+     * @returns The triggers for the current workflow.
+     */
+    triggers(): TriggerData;
+    /**
+     * Determines if the workflow was triggered by an event.
+     * @returns True if the workflow was triggered by an event, otherwise false.
+     */
     triggeredByEvent(): boolean;
+    /**
+     * Gets the input data for the current workflow.
+     * @returns The input data for the workflow.
+     */
     workflowInput(): T;
+    /**
+     * Gets the name of the current workflow.
+     * @returns The name of the workflow.
+     */
     workflowName(): string;
+    /**
+     * Gets the user data associated with the workflow.
+     * @returns The user data.
+     */
     userData(): K;
+    /**
+     * Gets the name of the current task.
+     * @returns The name of the task.
+     * @deprecated use ctx.taskName instead
+     */
     stepName(): string;
+    /**
+     * Gets the name of the current running task.
+     * @returns The name of the task.
+     */
+    taskName(): string;
+    /**
+     * Gets the ID of the current workflow run.
+     * @returns The workflow run ID.
+     */
     workflowRunId(): string;
+    /**
+     * Gets the number of times the current task has been retried.
+     * @returns The retry count.
+     */
     retryCount(): number;
-    playground(name: string, defaultValue?: string): string;
+    /**
+     * Logs a message from the current task.
+     * @param message - The message to log.
+     * @param level - The log level (optional).
+     */
     log(message: string, level?: LogLevel): void;
     /**
-     * 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: Duration): Promise<void>;
+    /**
+     * 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.
      */
-    refreshTimeout(incrementBy: string): Promise<void>;
     releaseSlot(): Promise<void>;
+    /**
+     * 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: string | Uint8Array): Promise<void>;
     /**
-     * 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<Q extends JsonObject = any, P extends JsonObject = any>(children: Array<{
+    bulkRunNoWaitChildren<Q extends JsonObject = any, P extends JsonObject = any>(children: Array<{
         workflow: string | Workflow | WorkflowV1<Q, P>;
         input: Q;
         options?: {
@@ -221,9 +321,9 @@ export declare class Context<T, K = {}> {
         };
     }>): Promise<WorkflowRunRef<P>[]>;
     /**
-     * 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<Q extends JsonObject = any, P extends JsonObject = any>(children: Array<{
         workflow: string | Workflow | WorkflowV1<Q, P>;
@@ -237,9 +337,9 @@ export declare class Context<T, K = {}> {
     /**
      * 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<Q extends JsonObject = any, P extends JsonObject = any>(workflows: Array<{
         workflow: string | Workflow | WorkflowV1<Q, P>;
@@ -251,14 +351,12 @@ export declare class Context<T, K = {}> {
         };
     }>): Promise<WorkflowRunRef<P>[]>;
     /**
-     * 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<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
         key?: string;
@@ -266,19 +364,14 @@ export declare class Context<T, K = {}> {
         additionalMetadata?: Record<string, string>;
     }): Promise<P>;
     /**
-     * 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<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
+     * @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<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
         key?: string;
         sticky?: boolean;
         additionalMetadata?: Record<string, string>;
@@ -286,28 +379,61 @@ export declare class Context<T, K = {}> {
     /**
      * 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<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
         key?: string;
         sticky?: boolean;
         additionalMetadata?: Record<string, string>;
     }): WorkflowRunRef<P>;
+    /**
+     * Retrieves additional metadata associated with the current workflow run.
+     * @returns A record of metadata key-value pairs.
+     */
     additionalMetadata(): Record<string, string>;
+    /**
+     * 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(): number | undefined;
+    /**
+     * 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(): string | undefined;
+    /**
+     * 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(): string | undefined;
 }
+export declare class DurableContext<T, K = {}> extends Context<T, K> {
+    waitKey: number;
+    /**
+     * 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: Duration, readableDataKey?: string): Promise<Record<string, any>>;
+    /**
+     * 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>>;
+}
 export type StepRunFunction<T, K> = (ctx: Context<T, K>) => Promise<NextStep | void> | NextStep | void;
+/**
+ * A step is a unit of work that can be run by a worker.
+ * It is defined by a name, a function that returns the next step, and optional configuration.
+ * @deprecated use hatchet.workflows.task factory instead
+ */
 export interface CreateStep<T, K> extends z.infer<typeof CreateStepSchema> {
     run: StepRunFunction<T, K>;
 }