@upstash/workflow 0.1.0

package/types-CfN1Epuj.d.ts

@@ -0,0 +1,616 @@
+import { HTTPMethods, Client, Receiver } from '@upstash/qstash';
+
+/**
+ * Base class outlining steps. Basically, each step kind (run/sleep/sleepUntil)
+ * should have two methods: getPlanStep & getResultStep.
+ *
+ * getPlanStep works the same way for all so it's implemented here.
+ * The different step types will implement their own getResultStep method.
+ */
+declare abstract class BaseLazyStep<TResult = unknown> {
+    readonly stepName: string;
+    abstract readonly stepType: StepType;
+    constructor(stepName: string);
+    /**
+     * plan step to submit when step will run parallel with other
+     * steps (parallel call state `first`)
+     *
+     * @param concurrent number of steps running parallel
+     * @param targetStep target step id corresponding to this step
+     * @returns
+     */
+    abstract getPlanStep(concurrent: number, targetStep: number): Step<undefined>;
+    /**
+     * result step to submit after the step executes. Used in single step executions
+     * and when a plan step executes in parallel executions (parallel call state `partial`).
+     *
+     * @param concurrent
+     * @param stepId
+     */
+    abstract getResultStep(concurrent: number, stepId: number): Promise<Step<TResult>>;
+}
+
+declare const LOG_LEVELS: readonly ["DEBUG", "INFO", "SUBMIT", "WARN", "ERROR"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+type ChatLogEntry = {
+    timestamp: number;
+    workflowRunId: string;
+    logLevel: LogLevel;
+    eventType: "ENDPOINT_START" | "SUBMIT_THIRD_PARTY_RESULT" | "CREATE_CONTEXT" | "SUBMIT_FIRST_INVOCATION" | "RUN_SINGLE" | "RUN_PARALLEL" | "SUBMIT_STEP" | "SUBMIT_CLEANUP" | "RESPONSE_WORKFLOW" | "RESPONSE_DEFAULT" | "ERROR";
+    details: unknown;
+};
+type WorkflowLoggerOptions = {
+    logLevel: LogLevel;
+    logOutput: "console";
+};
+declare class WorkflowLogger {
+    private logs;
+    private options;
+    private workflowRunId?;
+    constructor(options: WorkflowLoggerOptions);
+    log(level: LogLevel, eventType: ChatLogEntry["eventType"], details?: unknown): Promise<void>;
+    setWorkflowRunId(workflowRunId: string): void;
+    private writeToConsole;
+    private shouldLog;
+    static getLogger(verbose?: boolean | WorkflowLogger): WorkflowLogger | undefined;
+}
+
+declare class AutoExecutor {
+    private context;
+    private promises;
+    private activeLazyStepList?;
+    private debug?;
+    private readonly nonPlanStepCount;
+    private readonly steps;
+    private indexInCurrentList;
+    stepCount: number;
+    planStepCount: number;
+    protected executingStep: string | false;
+    constructor(context: WorkflowContext, steps: Step[], debug?: WorkflowLogger);
+    /**
+     * Adds the step function to the list of step functions to run in
+     * parallel. After adding the function, defers the execution, so
+     * that if there is another step function to be added, it's also
+     * added.
+     *
+     * After all functions are added, list of functions are executed.
+     * If there is a single function, it's executed by itself. If there
+     * are multiple, they are run in parallel.
+     *
+     * 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.
+     *
+     * @param stepInfo step plan to add
+     * @returns result of the step function
+     */
+    addStep<TResult>(stepInfo: BaseLazyStep<TResult>): Promise<TResult>;
+    /**
+     * Wraps a step function to set this.executingStep to step name
+     * before running and set this.executingStep to False after execution
+     * ends.
+     *
+     * this.executingStep allows us to detect nested steps which are not
+     * allowed.
+     *
+     * @param stepName name of the step being wrapped
+     * @param stepFunction step function to wrap
+     * @returns wrapped step function
+     */
+    wrapStep<TResult = unknown>(stepName: string, stepFunction: StepFunction<TResult>): TResult | Promise<TResult>;
+    /**
+     * Executes a step:
+     * - If the step result is available in the steps, returns the result
+     * - If the result is not avaiable, runs the function
+     * - Sends the result to QStash
+     *
+     * @param lazyStep lazy step to execute
+     * @returns step result
+     */
+    protected runSingle<TResult>(lazyStep: BaseLazyStep<TResult>): Promise<TResult>;
+    /**
+     * Runs steps in parallel.
+     *
+     * @param stepName parallel step name
+     * @param stepFunctions list of async functions to run in parallel
+     * @returns results of the functions run in parallel
+     */
+    protected runParallel<TResults extends unknown[]>(parallelSteps: {
+        [K in keyof TResults]: BaseLazyStep<TResults[K]>;
+    }): Promise<TResults>;
+    /**
+     * Determines the parallel call state
+     *
+     * First filters the steps to get the steps which are after `initialStepCount` parameter.
+     *
+     * Depending on the remaining steps, decides the parallel state:
+     * - "first": If there are no steps
+     * - "last" If there are equal to or more than `2 * parallelStepCount`. We multiply by two
+     *   because each step in a parallel execution will have 2 steps: a plan step and a result
+     *   step.
+     * - "partial": If the last step is a plan step
+     * - "discard": If the last step is not a plan step. This means that the parallel execution
+     *   is in progress (there are still steps to run) and one step has finished and submitted
+     *   its result to QStash
+     *
+     * @param parallelStepCount number of steps to run in parallel
+     * @param initialStepCount steps after the parallel invocation
+     * @returns parallel call state
+     */
+    protected getParallelCallState(parallelStepCount: number, initialStepCount: number): ParallelCallState;
+    /**
+     * sends the steps to QStash as batch
+     *
+     * @param steps steps to send
+     */
+    private submitStepsToQStash;
+    /**
+     * Get the promise by executing the lazt steps list. If there is a single
+     * step, we call `runSingle`. Otherwise `runParallel` is called.
+     *
+     * @param lazyStepList steps list to execute
+     * @returns promise corresponding to the execution
+     */
+    private getExecutionPromise;
+    /**
+     * @param lazyStepList steps we executed
+     * @param result result of the promise from `getExecutionPromise`
+     * @param index index of the current step
+     * @returns result[index] if lazyStepList > 1, otherwise result
+     */
+    private static getResult;
+    private deferExecution;
+}
+
+/**
+ * Upstash Workflow context
+ *
+ * See the docs for fields and methods https://upstash.com/docs/qstash/workflows/basics/context
+ */
+declare class WorkflowContext<TInitialPayload = unknown> {
+    protected readonly executor: AutoExecutor;
+    protected readonly steps: Step[];
+    /**
+     * QStash client of the workflow
+     *
+     * Can be overwritten by passing `qstashClient` parameter in `serve`:
+     *
+     * ```ts
+     * import { Client } from "@upstash/qstash"
+     *
+     * export const POST = serve(
+     *   async (context) => {
+     *     ...
+     *   },
+     *   {
+     *     qstashClient: new Client({...})
+     *   }
+     * )
+     * ```
+     */
+    readonly qstashClient: WorkflowClient;
+    /**
+     * Run id of the workflow
+     */
+    readonly workflowRunId: string;
+    /**
+     * URL of the workflow
+     *
+     * Can be overwritten by passing a `url` parameter in `serve`:
+     *
+     * ```ts
+     * export const POST = serve(
+     *   async (context) => {
+     *     ...
+     *   },
+     *   {
+     *     url: "new-url-value"
+     *   }
+     * )
+     * ```
+     */
+    readonly url: string;
+    /**
+     * URL to call in case of workflow failure with QStash failure callback
+     *
+     * https://upstash.com/docs/qstash/features/callbacks#what-is-a-failure-callback
+     *
+     * Can be overwritten by passing a `failureUrl` parameter in `serve`:
+     *
+     * ```ts
+     * export const POST = serve(
+     *   async (context) => {
+     *     ...
+     *   },
+     *   {
+     *     failureUrl: "new-url-value"
+     *   }
+     * )
+     * ```
+     */
+    readonly failureUrl?: string;
+    /**
+     * Payload of the request which started the workflow.
+     *
+     * To specify its type, you can define `serve` as follows:
+     *
+     * ```ts
+     * // set requestPayload type to MyPayload:
+     * export const POST = serve<MyPayload>(
+     *   async (context) => {
+     *     ...
+     *   }
+     * )
+     * ```
+     *
+     * By default, `serve` tries to apply `JSON.parse` to the request payload.
+     * If your payload is encoded in a format other than JSON, you can utilize
+     * the `initialPayloadParser` parameter:
+     *
+     * ```ts
+     * export const POST = serve<MyPayload>(
+     *   async (context) => {
+     *     ...
+     *   },
+     *   {
+     *     initialPayloadParser: (initialPayload) => {return doSomething(initialPayload)}
+     *   }
+     * )
+     * ```
+     */
+    readonly requestPayload: TInitialPayload;
+    /**
+     * headers of the initial request
+     */
+    readonly headers: Headers;
+    /**
+     * initial payload as a raw string
+     */
+    readonly rawInitialPayload: string;
+    /**
+     * Map of environment variables and their values.
+     *
+     * Can be set using the `env` option of serve:
+     *
+     * ```ts
+     * export const POST = serve<MyPayload>(
+     *   async (context) => {
+     *     const key = context.env["API_KEY"];
+     *   },
+     *   {
+     *     env: {
+     *       "API_KEY": "*****";
+     *     }
+     *   }
+     * )
+     * ```
+     *
+     * Default value is set to `process.env`.
+     */
+    readonly env: Record<string, string | undefined>;
+    /**
+     * Number of retries
+     */
+    readonly retries: number;
+    constructor({ qstashClient, workflowRunId, headers, steps, url, failureUrl, debug, initialPayload, rawInitialPayload, env, retries, }: {
+        qstashClient: WorkflowClient;
+        workflowRunId: string;
+        headers: Headers;
+        steps: Step[];
+        url: string;
+        failureUrl?: string;
+        debug?: WorkflowLogger;
+        initialPayload: TInitialPayload;
+        rawInitialPayload?: string;
+        env?: Record<string, string | undefined>;
+        retries?: number;
+    });
+    /**
+     * Executes a workflow step
+     *
+     * ```typescript
+     * const result = await context.run("step 1", () => {
+     *   return "result"
+     * })
+     * ```
+     *
+     * Can also be called in parallel and the steps will be executed
+     * simulatenously:
+     *
+     * ```typescript
+     * const [result1, result2] = await Promise.all([
+     *   context.run("step 1", () => {
+     *     return "result1"
+     *   })
+     *   context.run("step 2", async () => {
+     *     return await fetchResults()
+     *   })
+     * ])
+     * ```
+     *
+     * @param stepName name of the step
+     * @param stepFunction step function to be executed
+     * @returns result of the step function
+     */
+    run<TResult>(stepName: string, stepFunction: StepFunction<TResult>): Promise<TResult>;
+    /**
+     * Stops the execution for the duration provided.
+     *
+     * @param stepName
+     * @param duration sleep duration in seconds
+     * @returns undefined
+     */
+    sleep(stepName: string, duration: number): Promise<void>;
+    /**
+     * Stops the execution until the date time provided.
+     *
+     * @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)`)
+     * @returns undefined
+     */
+    sleepUntil(stepName: string, datetime: Date | string | number): Promise<void>;
+    /**
+     * Makes a third party call through QStash in order to make a
+     * network call without consuming any runtime.
+     *
+     * ```ts
+     * const postResult = await context.call<string>(
+     *   "post call step",
+     *   `https://www.some-endpoint.com/api`,
+     *   "POST",
+     *   "my-payload"
+     * );
+     * ```
+     *
+     * tries to parse the result of the request as JSON. If it's
+     * not a JSON which can be parsed, simply returns the response
+     * body as it is.
+     *
+     * @param stepName
+     * @param url url to call
+     * @param method call method
+     * @param body call body
+     * @param headers call headers
+     * @returns call result (parsed as JSON if possible)
+     */
+    call<TResult = unknown, TBody = unknown>(stepName: string, url: string, method: HTTPMethods, body?: TBody, headers?: Record<string, string>): Promise<TResult>;
+    waitForEvent(stepName: string, eventId: string, timeout: string | number): Promise<WaitStepResponse>;
+    /**
+     * Adds steps to the executor. Needed so that it can be overwritten in
+     * DisabledWorkflowContext.
+     */
+    protected addStep<TResult = unknown>(step: BaseLazyStep<TResult>): Promise<TResult>;
+}
+
+/**
+ * Interface for Client with required methods
+ *
+ * Neeeded to resolve import issues
+ */
+type WorkflowClient = {
+    batchJSON: InstanceType<typeof Client>["batchJSON"];
+    publishJSON: InstanceType<typeof Client>["publishJSON"];
+    http: InstanceType<typeof Client>["http"];
+};
+/**
+ * Interface for Receiver with required methods
+ *
+ * Neeeded to resolve import issues
+ */
+type WorkflowReceiver = {
+    verify: InstanceType<typeof Receiver>["verify"];
+};
+declare const StepTypes: readonly ["Initial", "Run", "SleepFor", "SleepUntil", "Call", "Wait", "Notify"];
+type StepType = (typeof StepTypes)[number];
+type ThirdPartyCallFields<TBody = unknown> = {
+    /**
+     * Third party call URL. Set when context.call is used.
+     */
+    callUrl: string;
+    /**
+     * Third party call method. Set when context.call is used.
+     */
+    callMethod: HTTPMethods;
+    /**
+     * Third party call body. Set when context.call is used.
+     */
+    callBody: TBody;
+    /**
+     * Third party call headers. Set when context.call is used.
+     */
+    callHeaders: Record<string, string>;
+};
+type WaitFields = {
+    waitEventId: string;
+    timeout: string;
+    waitTimeout?: boolean;
+};
+type NotifyFields = {
+    notifyEventId?: string;
+    notifyBody?: string;
+};
+type Step<TResult = unknown, TBody = unknown> = {
+    /**
+     * index of the step
+     */
+    stepId: number;
+    /**
+     * name of the step
+     */
+    stepName: string;
+    /**
+     * type of the step (Initial/Run/SleepFor/SleepUntil/Call)
+     */
+    stepType: StepType;
+    /**
+     * step result. Set if context.run or context.call are used.
+     */
+    out?: TResult;
+    /**
+     * sleep duration in seconds. Set when context.sleep is used.
+     */
+    sleepFor?: number;
+    /**
+     * unix timestamp (in seconds) to wait until. Set when context.sleepUntil is used.
+     */
+    sleepUntil?: number;
+    /**
+     * number of steps running concurrently if the step is in a parallel run.
+     * Set to 1 if step is not parallel.
+     */
+    concurrent: number;
+    /**
+     * target step of a plan step. In other words, the step to assign the
+     * result of a plan step.
+     *
+     * undefined if the step is not a plan step (of a parallel run). Otherwise,
+     * set to the target step.
+     */
+    targetStep?: number;
+} & (ThirdPartyCallFields<TBody> | {
+    [P in keyof ThirdPartyCallFields]?: never;
+}) & (WaitFields | {
+    [P in keyof WaitFields]?: never;
+}) & (NotifyFields | {
+    [P in keyof NotifyFields]?: never;
+});
+type RawStep = {
+    messageId: string;
+    body: string;
+    callType: "step" | "toCallback" | "fromCallback";
+};
+type SyncStepFunction<TResult> = () => TResult;
+type AsyncStepFunction<TResult> = () => Promise<TResult>;
+type StepFunction<TResult> = AsyncStepFunction<TResult> | SyncStepFunction<TResult>;
+type ParallelCallState = "first" | "partial" | "discard" | "last";
+type RouteFunction<TInitialPayload> = (context: WorkflowContext<TInitialPayload>) => Promise<void>;
+type FinishCondition = "success" | "duplicate-step" | "fromCallback" | "auth-fail" | "failure-callback";
+type WorkflowServeOptions<TResponse extends Response = Response, TInitialPayload = unknown> = {
+    /**
+     * QStash client
+     */
+    qstashClient?: WorkflowClient;
+    /**
+     * Function called to return a response after each step execution
+     *
+     * @param workflowRunId
+     * @returns response
+     */
+    onStepFinish?: (workflowRunId: string, finishCondition: FinishCondition) => TResponse;
+    /**
+     * Function to parse the initial payload passed by the user
+     */
+    initialPayloadParser?: (initialPayload: string) => TInitialPayload;
+    /**
+     * Url of the endpoint where the workflow is set up.
+     *
+     * If not set, url will be inferred from the request.
+     */
+    url?: string;
+    /**
+     * Verbose mode
+     *
+     * Disabled if not set. If set to true, a logger is created automatically.
+     *
+     * Alternatively, a WorkflowLogger can be passed.
+     */
+    verbose?: WorkflowLogger | true;
+    /**
+     * Receiver to verify *all* requests by checking if they come from QStash
+     *
+     * By default, a receiver is created from the env variables
+     * QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY if they are set.
+     */
+    receiver?: WorkflowReceiver;
+    /**
+     * Url to call if QStash retries are exhausted while executing the workflow
+     */
+    failureUrl?: string;
+    /**
+     * Failure function called when QStash retries are exhausted while executing
+     * the workflow. Will overwrite `failureUrl` parameter with the workflow
+     * endpoint if passed.
+     *
+     * @param context workflow context at the moment of error
+     * @param failStatus error status
+     * @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;
+    /**
+     * Base Url of the workflow endpoint
+     *
+     * Can be used to set if there is a local tunnel or a proxy between
+     * QStash and the workflow endpoint.
+     *
+     * Will be set to the env variable UPSTASH_WORKFLOW_URL if not passed.
+     * If the env variable is not set, the url will be infered as usual from
+     * the `request.url` or the `url` parameter in `serve` options.
+     *
+     * @default undefined
+     */
+    baseUrl?: string;
+    /**
+     * Optionally, one can pass an env object mapping environment
+     * variables to their keys.
+     *
+     * Useful in cases like cloudflare with hono.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * Number of retries to use in workflow requests
+     *
+     * 3 by default
+     */
+    retries?: number;
+};
+/**
+ * Payload passed as body in failureFunction
+ */
+type FailureFunctionPayload = {
+    /**
+     * error name
+     */
+    error: string;
+    /**
+     * error message
+     */
+    message: string;
+};
+/**
+ * Makes all fields except the ones selected required
+ */
+type RequiredExceptFields<T, K extends keyof T> = Omit<Required<T>, K> & Partial<Pick<T, K>>;
+type WaitResult<TResult = unknown> = {
+    result: TResult;
+    timeout: boolean;
+};
+type Waiter = {
+    url: string;
+    deadline: number;
+    headers: Record<string, string[]>;
+    timeoutUrl: string;
+    timeoutBody: unknown;
+    timeoutHeaders: Record<string, string[]>;
+};
+type NotifyResponse = {
+    waiter: Waiter;
+    messageId: string;
+    deduplicated: boolean;
+    error: string;
+};
+type WaitRequest = {
+    url: string;
+    timeout: string;
+    timeoutBody?: string;
+    timeoutUrl?: string;
+    timeoutHeaders?: Record<string, string[]>;
+    step: Step;
+};
+type WaitStepResponse = {
+    timeout: boolean;
+    notifyBody: unknown;
+};
+
+export { type AsyncStepFunction as A, 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, WorkflowContext as a, type WorkflowClient as b, type WorkflowReceiver as c, StepTypes as d, type StepType as e, type RawStep as f, type SyncStepFunction as g, type StepFunction as h, type FailureFunctionPayload as i, type RequiredExceptFields as j, type WaitResult as k, type Waiter as l, type WaitRequest as m, type WaitStepResponse as n, type WorkflowLoggerOptions as o, WorkflowLogger as p };