@upstash/workflow 0.1.5 → 0.2.0

package/svelte.mjs

@@ -1,6 +1,6 @@
 import {
   serve
-} from "./chunk-OJZEI7LO.mjs";
+} from "./chunk-5R2BFC3N.mjs";
 
 // platforms/svelte.ts
 var serve2 = (routeFunction, options) => {

package/{types-CQuc-j8n.d.mts → types-Cki_MHrh.d.mts}

@@ -79,7 +79,7 @@ declare class AutoExecutor {
      *
      * If a function is already executing (this.executingStep), this
      * means that there is a nested step which is not allowed. In this
-     * case, addStep throws QStashWorkflowError.
+     * case, addStep throws WorkflowError.
      *
      * @param stepInfo step plan to add
      * @returns result of the step function
@@ -263,10 +263,6 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * headers of the initial request
      */
     readonly headers: Headers;
-    /**
-     * initial payload as a raw string
-     */
-    readonly rawInitialPayload: string;
     /**
      * Map of environment variables and their values.
      *
@@ -292,7 +288,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * Number of retries
      */
     readonly retries: number;
-    constructor({ qstashClient, workflowRunId, headers, steps, url, failureUrl, debug, initialPayload, rawInitialPayload, env, retries, }: {
+    constructor({ qstashClient, workflowRunId, headers, steps, url, failureUrl, debug, initialPayload, env, retries, }: {
         qstashClient: WorkflowClient;
         workflowRunId: string;
         headers: Headers;
@@ -301,7 +297,6 @@ declare class WorkflowContext<TInitialPayload = unknown> {
         failureUrl?: string;
         debug?: WorkflowLogger;
         initialPayload: TInitialPayload;
-        rawInitialPayload?: string;
         env?: Record<string, string | undefined>;
         retries?: number;
     });
@@ -321,7 +316,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * const [result1, result2] = await Promise.all([
      *   context.run("step 1", () => {
      *     return "result1"
-     *   })
+     *   }),
      *   context.run("step 2", async () => {
      *     return await fetchResults()
      *   })
@@ -336,6 +331,10 @@ declare class WorkflowContext<TInitialPayload = unknown> {
     /**
      * Stops the execution for the duration provided.
      *
+     * ```typescript
+     * await context.sleep('sleep1', 3) // wait for three seconds
+     * ```
+     *
      * @param stepName
      * @param duration sleep duration in seconds
      * @returns undefined
@@ -344,6 +343,10 @@ declare class WorkflowContext<TInitialPayload = unknown> {
     /**
      * Stops the execution until the date time provided.
      *
+     * ```typescript
+     * await context.sleepUntil('sleep1', Date.now() / 1000 + 3) // wait for three seconds
+     * ```
+     *
      * @param stepName
      * @param datetime time to sleep until. Can be provided as a number (in unix seconds),
      *   as a Date object or a string (passed to `new Date(datetimeString)`)
@@ -358,7 +361,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * const { status, body } = await context.call<string>(
      *   "post call step",
      *   {
-     *     url: `https://www.some-endpoint.com/api`,
+     *     url: "https://www.some-endpoint.com/api",
      *     method: "POST",
      *     body: "my-payload"
      *   }
@@ -389,39 +392,69 @@ declare class WorkflowContext<TInitialPayload = unknown> {
         retries?: number;
     }): Promise<CallResponse<TResult>>;
     /**
-     * Makes the workflow run wait until a notify request is sent or until the
-     * timeout ends
+     * Pauses workflow execution until a specific event occurs or a timeout is reached.
      *
-     * ```ts
-     * const { eventData, timeout } = await context.waitForEvent(
-     *   "wait for event step",
-     *   "my-event-id",
-     *   100 // timeout after 100 seconds
-     * );
-     * ```
+     *```ts
+     * const result = await workflow.waitForEvent("payment-confirmed", {
+     *   timeout: "5m"
+     * });
+     *```
      *
-     * To notify a waiting workflow run, you can use the notify method:
+     * To notify a waiting workflow:
      *
      * ```ts
      * import { Client } from "@upstash/workflow";
      *
-     * const client = new Client({ token: });
+     * const client = new Client({ token: "<QSTASH_TOKEN>" });
      *
      * await client.notify({
-     *   eventId: "my-event-id",
-     *   eventData: "eventData"
+     *   eventId: "payment.confirmed",
+     *   data: {
+     *     amount: 99.99,
+     *     currency: "USD"
+     *   }
      * })
      * ```
      *
+     * Alternatively, you can use the `context.notify` method.
+     *
+     * @param stepName
+     * @param eventId - Unique identifier for the event to wait for
+     * @param options - Configuration options.
+     * @returns `{ timeout: boolean, eventData: unknown }`.
+     *   The `timeout` property specifies if the workflow has timed out. The `eventData`
+     *   is the data passed when notifying this workflow of an event.
+     */
+    waitForEvent(stepName: string, eventId: string, options?: WaitEventOptions): Promise<WaitStepResponse>;
+    /**
+     * Notify workflow runs waiting for an event
+     *
+     * ```ts
+     * const { eventId, eventData, notifyResponse } = await context.notify(
+     *   "notify step", "event-id", "event-data"
+     * );
+     * ```
+     *
+     * Upon `context.notify`, the workflow runs waiting for the given eventId (context.waitForEvent)
+     * will receive the given event data and resume execution.
+     *
+     * The response includes the same eventId and eventData. Additionally, there is
+     * a notifyResponse field which contains a list of `Waiter` objects, each corresponding
+     * to a notified workflow run.
+     *
      * @param stepName
-     * @param eventId event id to wake up the waiting workflow run
-     * @param timeout timeout duration in seconds
-     * @returns wait response as `{ timeout: boolean, eventData: unknown }`.
-     *   timeout is true if the wait times out, if notified it is false. eventData
-     *   is the value passed to `client.notify`.
+     * @param eventId event id to notify
+     * @param eventData event data to notify with
+     * @returns notify response which has event id, event data and list of waiters which were notified
      */
-    waitForEvent(stepName: string, eventId: string, timeout: number | Duration): Promise<WaitStepResponse>;
     notify(stepName: string, eventId: string, eventData: unknown): Promise<NotifyStepResponse>;
+    /**
+     * Cancel the current workflow run
+     *
+     * Will throw WorkflowAbort to stop workflow execution.
+     * Shouldn't be inside try/catch.
+     */
+    cancel(): Promise<void>;
     /**
      * Adds steps to the executor. Needed so that it can be overwritten in
      * DisabledWorkflowContext.
@@ -584,7 +617,12 @@ type WorkflowServeOptions<TResponse extends Response = Response, TInitialPayload
      * @param failResponse error message
      * @returns void
      */
-    failureFunction?: (context: Omit<WorkflowContext, "run" | "sleepUntil" | "sleep" | "call">, failStatus: number, failResponse: string, failHeader: Record<string, string[]>) => Promise<void> | void;
+    failureFunction?: (failureData: {
+        context: Omit<WorkflowContext<TInitialPayload>, "run" | "sleepUntil" | "sleep" | "call" | "waitForEvent" | "notify">;
+        failStatus: number;
+        failResponse: string;
+        failHeaders: Record<string, string[]>;
+    }) => Promise<void> | void;
     /**
      * Base Url of the workflow endpoint
      *
@@ -680,6 +718,22 @@ type CallResponse<TResult = unknown> = {
     body: TResult;
     header: Record<string, string[]>;
 };
-type Duration = `${bigint}s` | `${bigint}m` | `${bigint}h` | `${bigint}d`;
+/**
+ * Valid duration string formats
+ * @example "30s" // 30 seconds
+ * @example "5m"  // 5 minutes
+ * @example "2h"  // 2 hours
+ * @example "1d"  // 1 day
+ */
+type Duration = `${bigint}${"s" | "m" | "h" | "d"}`;
+interface WaitEventOptions {
+    /**
+     * Duration in seconds to wait for an event before timing out the workflow.
+     * @example 300 // 5 minutes in seconds
+     * @example "5m" // 5 minutes as duration string
+     * @default "7d"
+     */
+    timeout?: number | Duration;
+}
 
-export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type FailureFunctionPayload as j, type RequiredExceptFields as k, type WaitRequest as l, type WaitStepResponse as m, type NotifyStepResponse as n, type WorkflowLoggerOptions as o, WorkflowLogger as p };
+export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type FailureFunctionPayload as j, type RequiredExceptFields as k, type WaitRequest as l, type WaitStepResponse as m, type NotifyStepResponse as n, type WaitEventOptions as o, type WorkflowLoggerOptions as p, WorkflowLogger as q };

package/{types-CQuc-j8n.d.ts → types-Cki_MHrh.d.ts}

@@ -79,7 +79,7 @@ declare class AutoExecutor {
      *
      * If a function is already executing (this.executingStep), this
      * means that there is a nested step which is not allowed. In this
-     * case, addStep throws QStashWorkflowError.
+     * case, addStep throws WorkflowError.
      *
      * @param stepInfo step plan to add
      * @returns result of the step function
@@ -263,10 +263,6 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * headers of the initial request
      */
     readonly headers: Headers;
-    /**
-     * initial payload as a raw string
-     */
-    readonly rawInitialPayload: string;
     /**
      * Map of environment variables and their values.
      *
@@ -292,7 +288,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * Number of retries
      */
     readonly retries: number;
-    constructor({ qstashClient, workflowRunId, headers, steps, url, failureUrl, debug, initialPayload, rawInitialPayload, env, retries, }: {
+    constructor({ qstashClient, workflowRunId, headers, steps, url, failureUrl, debug, initialPayload, env, retries, }: {
         qstashClient: WorkflowClient;
         workflowRunId: string;
         headers: Headers;
@@ -301,7 +297,6 @@ declare class WorkflowContext<TInitialPayload = unknown> {
         failureUrl?: string;
         debug?: WorkflowLogger;
         initialPayload: TInitialPayload;
-        rawInitialPayload?: string;
         env?: Record<string, string | undefined>;
         retries?: number;
     });
@@ -321,7 +316,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * const [result1, result2] = await Promise.all([
      *   context.run("step 1", () => {
      *     return "result1"
-     *   })
+     *   }),
      *   context.run("step 2", async () => {
      *     return await fetchResults()
      *   })
@@ -336,6 +331,10 @@ declare class WorkflowContext<TInitialPayload = unknown> {
     /**
      * Stops the execution for the duration provided.
      *
+     * ```typescript
+     * await context.sleep('sleep1', 3) // wait for three seconds
+     * ```
+     *
      * @param stepName
      * @param duration sleep duration in seconds
      * @returns undefined
@@ -344,6 +343,10 @@ declare class WorkflowContext<TInitialPayload = unknown> {
     /**
      * Stops the execution until the date time provided.
      *
+     * ```typescript
+     * await context.sleepUntil('sleep1', Date.now() / 1000 + 3) // wait for three seconds
+     * ```
+     *
      * @param stepName
      * @param datetime time to sleep until. Can be provided as a number (in unix seconds),
      *   as a Date object or a string (passed to `new Date(datetimeString)`)
@@ -358,7 +361,7 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * const { status, body } = await context.call<string>(
      *   "post call step",
      *   {
-     *     url: `https://www.some-endpoint.com/api`,
+     *     url: "https://www.some-endpoint.com/api",
      *     method: "POST",
      *     body: "my-payload"
      *   }
@@ -389,39 +392,69 @@ declare class WorkflowContext<TInitialPayload = unknown> {
         retries?: number;
     }): Promise<CallResponse<TResult>>;
     /**
-     * Makes the workflow run wait until a notify request is sent or until the
-     * timeout ends
+     * Pauses workflow execution until a specific event occurs or a timeout is reached.
      *
-     * ```ts
-     * const { eventData, timeout } = await context.waitForEvent(
-     *   "wait for event step",
-     *   "my-event-id",
-     *   100 // timeout after 100 seconds
-     * );
-     * ```
+     *```ts
+     * const result = await workflow.waitForEvent("payment-confirmed", {
+     *   timeout: "5m"
+     * });
+     *```
      *
-     * To notify a waiting workflow run, you can use the notify method:
+     * To notify a waiting workflow:
      *
      * ```ts
      * import { Client } from "@upstash/workflow";
      *
-     * const client = new Client({ token: });
+     * const client = new Client({ token: "<QSTASH_TOKEN>" });
      *
      * await client.notify({
-     *   eventId: "my-event-id",
-     *   eventData: "eventData"
+     *   eventId: "payment.confirmed",
+     *   data: {
+     *     amount: 99.99,
+     *     currency: "USD"
+     *   }
      * })
      * ```
      *
+     * Alternatively, you can use the `context.notify` method.
+     *
+     * @param stepName
+     * @param eventId - Unique identifier for the event to wait for
+     * @param options - Configuration options.
+     * @returns `{ timeout: boolean, eventData: unknown }`.
+     *   The `timeout` property specifies if the workflow has timed out. The `eventData`
+     *   is the data passed when notifying this workflow of an event.
+     */
+    waitForEvent(stepName: string, eventId: string, options?: WaitEventOptions): Promise<WaitStepResponse>;
+    /**
+     * Notify workflow runs waiting for an event
+     *
+     * ```ts
+     * const { eventId, eventData, notifyResponse } = await context.notify(
+     *   "notify step", "event-id", "event-data"
+     * );
+     * ```
+     *
+     * Upon `context.notify`, the workflow runs waiting for the given eventId (context.waitForEvent)
+     * will receive the given event data and resume execution.
+     *
+     * The response includes the same eventId and eventData. Additionally, there is
+     * a notifyResponse field which contains a list of `Waiter` objects, each corresponding
+     * to a notified workflow run.
+     *
      * @param stepName
-     * @param eventId event id to wake up the waiting workflow run
-     * @param timeout timeout duration in seconds
-     * @returns wait response as `{ timeout: boolean, eventData: unknown }`.
-     *   timeout is true if the wait times out, if notified it is false. eventData
-     *   is the value passed to `client.notify`.
+     * @param eventId event id to notify
+     * @param eventData event data to notify with
+     * @returns notify response which has event id, event data and list of waiters which were notified
      */
-    waitForEvent(stepName: string, eventId: string, timeout: number | Duration): Promise<WaitStepResponse>;
     notify(stepName: string, eventId: string, eventData: unknown): Promise<NotifyStepResponse>;
+    /**
+     * Cancel the current workflow run
+     *
+     * Will throw WorkflowAbort to stop workflow execution.
+     * Shouldn't be inside try/catch.
+     */
+    cancel(): Promise<void>;
     /**
      * Adds steps to the executor. Needed so that it can be overwritten in
      * DisabledWorkflowContext.
@@ -584,7 +617,12 @@ type WorkflowServeOptions<TResponse extends Response = Response, TInitialPayload
      * @param failResponse error message
      * @returns void
      */
-    failureFunction?: (context: Omit<WorkflowContext, "run" | "sleepUntil" | "sleep" | "call">, failStatus: number, failResponse: string, failHeader: Record<string, string[]>) => Promise<void> | void;
+    failureFunction?: (failureData: {
+        context: Omit<WorkflowContext<TInitialPayload>, "run" | "sleepUntil" | "sleep" | "call" | "waitForEvent" | "notify">;
+        failStatus: number;
+        failResponse: string;
+        failHeaders: Record<string, string[]>;
+    }) => Promise<void> | void;
     /**
      * Base Url of the workflow endpoint
      *
@@ -680,6 +718,22 @@ type CallResponse<TResult = unknown> = {
     body: TResult;
     header: Record<string, string[]>;
 };
-type Duration = `${bigint}s` | `${bigint}m` | `${bigint}h` | `${bigint}d`;
+/**
+ * Valid duration string formats
+ * @example "30s" // 30 seconds
+ * @example "5m"  // 5 minutes
+ * @example "2h"  // 2 hours
+ * @example "1d"  // 1 day
+ */
+type Duration = `${bigint}${"s" | "m" | "h" | "d"}`;
+interface WaitEventOptions {
+    /**
+     * Duration in seconds to wait for an event before timing out the workflow.
+     * @example 300 // 5 minutes in seconds
+     * @example "5m" // 5 minutes as duration string
+     * @default "7d"
+     */
+    timeout?: number | Duration;
+}
 
-export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type FailureFunctionPayload as j, type RequiredExceptFields as k, type WaitRequest as l, type WaitStepResponse as m, type NotifyStepResponse as n, type WorkflowLoggerOptions as o, WorkflowLogger as p };
+export { type AsyncStepFunction as A, type CallResponse as C, type Duration as D, type FinishCondition as F, type LogLevel as L, type NotifyResponse as N, type ParallelCallState as P, type RouteFunction as R, type Step as S, type WorkflowServeOptions as W, type Waiter as a, WorkflowContext as b, type WorkflowClient as c, type WorkflowReceiver as d, StepTypes as e, type StepType as f, type RawStep as g, type SyncStepFunction as h, type StepFunction as i, type FailureFunctionPayload as j, type RequiredExceptFields as k, type WaitRequest as l, type WaitStepResponse as m, type NotifyStepResponse as n, type WaitEventOptions as o, type WorkflowLoggerOptions as p, WorkflowLogger as q };