@upstash/workflow 1.3.2 → 1.4.0-rc

package/tanstack.mjs

@@ -2,15 +2,17 @@ import {
   SDK_TELEMETRY,
   serveBase,
   serveManyBase
-} from "./chunk-ICDNN4UW.mjs";
+} from "./chunk-UH6O5IJY.mjs";
 
 // platforms/tanstack.ts
+import { startDevServer } from "@upstash/qstash";
 var telemetry = {
   sdk: SDK_TELEMETRY,
   framework: "tanstack",
   runtime: `node@${process.version}`
 };
 function serve(routeFunction, options) {
+  void startDevServer();
   const POST = (tanstackContext) => {
     const { handler } = serveBase(
       routeFunction,

package/{types-CekOpKvz.d.ts → types-ffLPVG5_.d.mts}

@@ -1,5 +1,6 @@
 import { QstashError, PublishRequest, HTTPMethods as HTTPMethods$1, FlowControl, Client, Receiver } from '@upstash/qstash';
 import { z } from 'zod';
+import { Ok, Err } from 'neverthrow';
 
 /**
  * Error raised during Workflow execution
@@ -170,7 +171,14 @@ type HeadersResponse = {
 type StepParams = {
     context: WorkflowContext;
 } & Pick<HeaderParams, "telemetry"> & Required<Pick<HeaderParams, "step" | "invokeCount">>;
-type GetHeaderParams = StepParams;
+type GetHeaderParams = StepParams & {
+    /**
+     * step-level settings to apply to the message being published. Set
+     * when the next step has settings and this step's submission is what
+     * will produce the delivery that executes it.
+     */
+    stepSettings?: StepSettings;
+};
 type GetBodyParams = StepParams & Omit<HeadersResponse, "contentType">;
 type SubmitStepParams = StepParams & Pick<HeadersResponse, "headers"> & {
     body: string;
@@ -188,7 +196,27 @@ declare abstract class BaseLazyStep<TResult = unknown> {
     abstract readonly stepType: StepType;
     protected abstract readonly allowUndefinedOut: boolean;
     protected readonly context: WorkflowContext;
-    constructor(context: WorkflowContext, stepName: string);
+    /**
+     * step-level settings (flow control, retries etc.) which override the
+     * settings the workflow run was triggered with, for this step only.
+     */
+    readonly stepSettings?: StepSettings;
+    /**
+     * whether this step's result can be submitted after the route function
+     * has moved on, instead of right away.
+     *
+     * Enabled for steps whose `getResultStep` produces the final `out` —
+     * which is not the same as "needs no server round trip":
+     * `LazyCreateWebhookStep` builds its result in `getBody` and returns
+     * `out: undefined` from `getResultStep`, so deferring it would hand
+     * `undefined` to the route function.
+     *
+     * Deferring lets the route function continue and reveal the next step,
+     * so that step's settings can ride on this step's submission instead
+     * of needing a step config request of their own.
+     */
+    readonly supportsDeferredSubmission: boolean;
+    constructor(context: WorkflowContext, stepName: string, stepSettings?: StepSettings);
     /**
      * plan step to submit when step will run parallel with other
      * steps (parallel call state `first`)
@@ -219,7 +247,7 @@ declare abstract class BaseLazyStep<TResult = unknown> {
     protected handleUndefinedOut(step: Step): TResult;
     protected static tryParsing(stepOut: unknown): any;
     getBody({ step }: GetBodyParams): string;
-    getHeaders({ context, telemetry, invokeCount, step }: GetHeaderParams): HeadersResponse;
+    getHeaders({ context, telemetry, invokeCount, step, stepSettings, }: GetHeaderParams): HeadersResponse;
     submitStep({ context, body, headers }: SubmitStepParams): Promise<{
         messageId: string;
     }[]>;
@@ -236,6 +264,63 @@ type WaitForWebhookResponse = {
     request: undefined;
 };
 
+/**
+ * The configuration QStash applied to the delivery in hand.
+ *
+ * Reported on every delivery through the `Upstash-Flow-Control-*`,
+ * `Upstash-Retries` and `Upstash-Retry-Delay` headers. For an ordinary delivery this is the configuration the run was triggered with; for a
+ * step-configured delivery it is that step's own configuration, which
+ * delivery is meant to execute.
+ */
+type EffectiveConfig = {
+    /**
+     * flow control applied to this delivery, if any
+     */
+    flowControl?: NormalizedFlowControl;
+    /**
+     * retry limit of this delivery, or undefined when QStash did not
+     * report one (a version which predates the header)
+     */
+    retries?: number;
+    /**
+     * retry delay expression applied to this delivery, if any
+     */
+    retryDelay?: string;
+    /**
+     * whether the message of this delivery was published with step-level
+     * settings (the guard marker).
+     */
+    hasStepConfig: boolean;
+};
+/**
+ * Flow control reduced to a form both sides of the protocol agree on.
+ *
+ * Needed because the SDK and QStash format the same values differently:
+ * the SDK joins the control value with ", " and writes durations
+ * (`period=1m`), QStash joins with "," and writes whole seconds
+ * (`period=60`). `rate` and `ratePerSecond` are aliases on the SDK side.
+ * Comparing the header strings would report a mismatch for values which
+ * are in fact identical, so both sides are parsed into this shape first.
+ */
+type NormalizedFlowControl = {
+    key: string;
+    parallelism: number;
+    rate: number;
+    /**
+     * period in whole seconds
+     */
+    period: number;
+};
+
+/**
+ * What came of submitting the step being held, if one was.
+ */
+type PendingStepOutcome = {
+    result: "submitted-step";
+    abort: WorkflowAbort;
+} | {
+    result: "no-pending-step";
+};
 declare class AutoExecutor {
     private context;
     private promises;
@@ -250,6 +335,25 @@ declare class AutoExecutor {
     stepCount: number;
     planStepCount: number;
     protected executingStep: string | false;
+    /**
+     * an executed step whose result hasn't been submitted to QStash yet.
+     *
+     * Set when a step which can produce its result in-process executes. The
+     * submission waits so that the route function can continue and reveal
+     * what comes next: if that is a single step with step-level settings,
+     * the settings ride on this submission and no step config request is
+     * needed, since the delivery of the submission is what executes it.
+     *
+     * Flushed when the next step is reached (see `addStep`) or when the
+     * route function ends (see `flushPendingStep` in `serve`).
+     */
+    private pendingStep?;
+    /**
+     * configuration QStash applied to the delivery being handled. A step
+     * with step-level settings is settled by comparing its settings against
+     * this.
+     */
+    private readonly effectiveConfig;
     /**
      * @param context workflow context
      * @param steps list of steps
@@ -257,8 +361,10 @@ declare class AutoExecutor {
      * @param dispatchLifecycle lifecycle event dispatcher
      * @param telemetry optional telemetry information
      * @param invokeCount optional invoke count
+     * @param effectiveConfig configuration QStash applied to the delivery
+     *   being handled
      */
-    constructor(context: WorkflowContext, steps: Step[], dispatchDebug: DispatchDebug, dispatchLifecycle: DispatchLifecycle, telemetry?: Telemetry, invokeCount?: number);
+    constructor(context: WorkflowContext, steps: Step[], dispatchDebug: DispatchDebug, dispatchLifecycle: DispatchLifecycle, telemetry?: Telemetry, invokeCount?: number, effectiveConfig?: EffectiveConfig);
     /**
      * Adds the step function to the list of step functions to run in
      * parallel. After adding the function, defers the execution, so
@@ -300,6 +406,31 @@ declare class AutoExecutor {
      * @returns step result
      */
     protected runSingle<TResult>(lazyStep: BaseLazyStep<TResult>): Promise<TResult>;
+    /**
+     * Submits the result of the step being held, if there is one, and
+     * returns the abort the caller has to throw to end the invocation.
+     *
+     * Returns undefined when no step is being held, which is the caller's
+     * signal that there is nothing to end. Throws instead of returning
+     * when the submission itself fails, so that error reaches the caller
+     * rather than an abort claiming the step was submitted.
+     *
+     * Callers which arrive while a submission is already under way (the
+     * steps of a parallel group, added together) wait for that one and get
+     * the same abort, rather than submitting a second time.
+     *
+     * The next step's settings are attached whenever it has any, without
+     * checking them against the current delivery: the executor only knows
+     * the configuration of the delivery in hand, which inside a
+     * delivery is the *previous* step's, so such a check would be wrong
+     * exactly when two steps with settings follow each other.
+     *
+     * @param nextStepSettings step-level settings of the next step
+     * @returns `submitted-step` with the abort which ends this invocation,
+     *   or `no-pending-step` when nothing was held and there is nothing to
+     *   end
+     */
+    submitPendingStep(nextStepSettings?: StepSettings): Promise<Ok<PendingStepOutcome, never> | Err<never, Error>>;
     /**
      * Runs steps in parallel.
      *
@@ -715,7 +846,41 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * `1` on the first retry, `2` on the second, and so on.
      */
     readonly retried: number;
-    constructor({ qstashClient, workflowRunId, workflowRunCreatedAt, headers, steps, url, initialPayload, env, telemetry, invokeCount, label, retried, middlewareManager, }: {
+    /**
+     * Configuration QStash applied to the request being handled.
+     *
+     * This is the configuration of *this delivery*, not of the run: it is
+     * the configuration the run was triggered with, except inside the
+     * delivery which executes a step that has step-level settings, where
+     * it is that step's settings. The fields below expose it; the executor
+     * gets it directly rather than reaching through the context.
+     */
+    private readonly effectiveConfig;
+    /**
+     * Flow control QStash applied to the request being handled, if any.
+     *
+     * This is the flow control of the request in hand, which is the one the
+     * run was triggered with except inside a step carrying its own.
+     */
+    get flowControl(): NormalizedFlowControl | undefined;
+    /**
+     * Retry limit QStash applied to the request being handled, if it
+     * reported one.
+     *
+     * Not to be confused with {@link retried}, which is how many retries
+     * have already happened.
+     *
+     * @see {@link flowControl} for what "the request being handled" means
+     */
+    get retries(): number | undefined;
+    /**
+     * Retry delay expression QStash applied to the request being handled,
+     * if any.
+     *
+     * @see {@link flowControl} for what "the request being handled" means
+     */
+    get retryDelay(): string | undefined;
+    constructor({ qstashClient, workflowRunId, workflowRunCreatedAt, headers, steps, url, initialPayload, env, telemetry, invokeCount, label, retried, middlewareManager, effectiveConfig, }: {
         qstashClient: WorkflowClient;
         workflowRunId: string;
         workflowRunCreatedAt: number;
@@ -729,6 +894,12 @@ declare class WorkflowContext<TInitialPayload = unknown> {
         label?: string | string[];
         retried?: number;
         middlewareManager?: MiddlewareManager<TInitialPayload>;
+        /**
+         * configuration QStash applied to the delivery being handled, read
+         * from its headers. Defaults to no flow control and no retries,
+         * which is what a context created outside a delivery observes.
+         */
+        effectiveConfig?: EffectiveConfig;
     });
     /**
      * Executes a workflow step
@@ -753,11 +924,28 @@ declare class WorkflowContext<TInitialPayload = unknown> {
      * ])
      * ```
      *
+     * Step-level settings can be passed as a third argument, overriding
+     * the settings the workflow run was triggered with for this step only:
+     *
+     * ```typescript
+     * const result = await context.run(
+     *   "step 1",
+     *   () => {
+     *     return "result"
+     *   },
+     *   {
+     *     flowControl: { key: "custom-key", parallelism: 3 },
+     *     retries: 5,
+     *   }
+     * )
+     * ```
+     *
      * @param stepName name of the step
      * @param stepFunction step function to be executed
+     * @param stepSettings step-level settings for this step
      * @returns result of the step function
      */
-    run<TResult>(stepName: string, stepFunction: StepFunction<TResult>): Promise<TResult>;
+    run<TResult>(stepName: string, stepFunction: StepFunction<TResult>, stepSettings?: StepSettings): Promise<TResult>;
     /**
      * Stops the execution for the duration provided.
      *
@@ -1003,7 +1191,7 @@ type Step<TResult = unknown, TBody = unknown> = {
 type RawStep = {
     messageId: string;
     body: string;
-    callType: "step" | "toCallback" | "fromCallback";
+    callType: "step" | "toCallback" | "fromCallback" | "stepConfig";
 };
 type SyncStepFunction<TResult> = () => TResult;
 type AsyncStepFunction<TResult> = () => Promise<TResult>;
@@ -1215,6 +1403,58 @@ interface WaitEventOptions {
      */
     timeout?: number | Duration;
 }
+/**
+ * Step-level settings which override the workflow run settings
+ * passed in `client.trigger` for the execution of a single step.
+ *
+ * Passed as the third argument of `context.run`:
+ *
+ * ```ts
+ * const result = await context.run(
+ *   "step",
+ *   () => { ... },
+ *   { flowControl: { key: "custom-key", parallelism: 3 }, retries: 5 }
+ * );
+ * ```
+ *
+ * The settings must be applied to the request whose delivery executes
+ * the step:
+ *
+ * - a step running in parallel with others carries its settings on its
+ *   own plan step, whose delivery is what executes the step. No extra
+ *   request is made.
+ * - otherwise, the SDK can only learn about the step once the workflow
+ *   function has been replayed, which happens in a delivery that was
+ *   published before the step was known. So instead of executing the
+ *   step in that delivery, a hidden request carrying the
+ *   settings is published and the step executes when QStash delivers it.
+ *   This costs one extra message and one extra endpoint invocation per
+ *   step which carries settings. QStash hides the request from the
+ *   step logs.
+ */
+type StepSettings = {
+    /**
+     * Settings for controlling the number of active requests
+     * and number of requests per second with the same key
+     * while executing this step.
+     *
+     * Overrides the flow control settings passed when triggering
+     * the workflow for this step only.
+     */
+    flowControl?: FlowControl;
+    /**
+     * Number of times QStash will retry the delivery which executes
+     * this step.
+     *
+     * Overrides the retries passed when triggering the workflow for
+     * this step only.
+     */
+    retries?: number;
+    /**
+     * Delay between retries of the delivery which executes this step.
+     */
+    retryDelay?: string;
+};
 type CallSettings = {
     url: string;
     method?: HTTPMethods$1;
@@ -1342,4 +1582,4 @@ type InvokableWorkflow<TInitialPayload, TResult> = {
     useJSONContent?: boolean;
 };
 
-export { type AsyncStepFunction as A, type CallResponse as C, type DetailedFinishCondition as D, type ExclusiveValidationOptions as E, type FailureFunctionPayload as F, type HeaderParams as H, type InvokableWorkflow as I, type LazyInvokeStepParams as L, type NotifyResponse as N, type ParallelCallState as P, type QStashClientExtraConfig as Q, type RawStep as R, type StepType as S, type Telemetry as T, WorkflowMiddleware as W, type WorkflowClient as a, type WorkflowReceiver as b, type RouteFunction as c, type WorkflowServeOptions as d, type Waiter as e, type CallSettings as f, type Duration as g, type FinishCondition as h, type InvokeStepResponse as i, type InvokeWorkflowRequest as j, type NotifyStepResponse as k, type RequiredExceptFields as l, type Step as m, type StepFunction as n, StepTypes as o, type SyncStepFunction as p, type WaitEventOptions as q, type WaitRequest as r, type WaitStepResponse as s, WorkflowAbort as t, WorkflowContext as u, WorkflowError as v, WorkflowNonRetryableError as w, WorkflowRetryAfterError as x };
+export { type AsyncStepFunction as A, type CallResponse as C, type DetailedFinishCondition as D, type ExclusiveValidationOptions as E, type FailureFunctionPayload as F, type HeaderParams as H, type InvokableWorkflow as I, type LazyInvokeStepParams as L, type NotifyResponse as N, type ParallelCallState as P, type QStashClientExtraConfig as Q, type RawStep as R, type StepType as S, type Telemetry as T, WorkflowMiddleware as W, type WorkflowClient as a, type WorkflowReceiver as b, type RouteFunction as c, type WorkflowServeOptions as d, type Waiter as e, type CallSettings as f, type Duration as g, type FinishCondition as h, type InvokeStepResponse as i, type InvokeWorkflowRequest as j, type NotifyStepResponse as k, type RequiredExceptFields as l, type Step as m, type StepFunction as n, type StepSettings as o, StepTypes as p, type SyncStepFunction as q, type WaitEventOptions as r, type WaitRequest as s, type WaitStepResponse as t, WorkflowAbort as u, WorkflowContext as v, WorkflowError as w, WorkflowNonRetryableError as x, WorkflowRetryAfterError as y };