list steps

Author: ianmacartney

example/convex/_generated/api.d.ts

@@ -395,6 +395,45 @@ export declare const components: {
           };
         }
       >;
+      listSteps: FunctionReference<
+        "query",
+        "internal",
+        {
+          order: "asc" | "desc";
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+          workflowId: string;
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            args: any;
+            completedAt?: number;
+            eventId?: string;
+            kind: "function" | "workflow" | "event";
+            name: string;
+            nestedWorkflowId?: string;
+            runResult?:
+              | { kind: "success"; returnValue: any }
+              | { error: string; kind: "failed" }
+              | { kind: "canceled" };
+            startedAt: number;
+            stepId: string;
+            stepNumber: number;
+            workId?: string;
+            workflowId: string;
+          }>;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        }
+      >;
     };
   };
 };

src/client/index.ts

@@ -10,6 +10,8 @@ import {
   type GenericDataModel,
   type GenericMutationCtx,
   type GenericQueryCtx,
+  type PaginationOptions,
+  type PaginationResult,
   type RegisteredMutation,
   type ReturnValueForOptionalValidator,
 } from "convex/server";
@@ -20,13 +22,19 @@ import type {
   EventSpec,
   OnCompleteArgs,
   WorkflowId,
+  WorkflowStep,
 } from "../types.js";
 import { safeFunctionName } from "./safeFunctionName.js";
-import type { OpaqueIds, WorkflowComponent, WorkflowStep } from "./types.js";
+import type { OpaqueIds, WorkflowComponent, WorkflowCtx } from "./types.js";
 import { workflowMutation } from "./workflowMutation.js";
 import { parse } from "convex-helpers/validators";
 
-export { vWorkflowId, type WorkflowId } from "../types.js";
+export {
+  vWorkflowId,
+  type WorkflowId,
+  vWorkflowStep,
+  type WorkflowStep,
+} from "../types.js";
 export type { RunOptions } from "./types.js";
 export { defineEvent } from "./events.js";
 
@@ -67,7 +75,7 @@ export type WorkflowDefinition<
 > = {
   args?: ArgsValidator;
   handler: (
-    step: WorkflowStep,
+    step: WorkflowCtx,
     args: ObjectType<ArgsValidator>,
   ) => Promise<ReturnValueForOptionalValidator<ReturnsValidator>>;
   returns?: ReturnsValidator;
@@ -201,6 +209,36 @@ export class WorkflowManager {
     });
   }
 
+  /**
+   * List the steps in a workflow, including their name, args, return value etc.
+   *
+   * @param ctx - The Convex context from a query, mutation, or action.
+   * @param workflowId - The workflow ID.
+   * @param opts - How many steps to fetch and in what order.
+   *   e.g. `{ order: "desc", paginationOpts: { cursor: null, numItems: 10 } }`
+   *   will get the last 10 steps in descending order.
+   *   Defaults to 100 steps in ascending order.
+   * @returns The pagination result with per-step data.
+   */
+  async listSteps(
+    ctx: RunQueryCtx,
+    workflowId: WorkflowId,
+    opts?: {
+      order?: "asc" | "desc";
+      paginationOpts?: PaginationOptions;
+    },
+  ): Promise<PaginationResult<WorkflowStep>> {
+    const steps = await ctx.runQuery(this.component.workflow.listSteps, {
+      workflowId,
+      order: opts?.order ?? "asc",
+      paginationOpts: opts?.paginationOpts ?? {
+        cursor: null,
+        numItems: 100,
+      },
+    });
+    return steps as PaginationResult<WorkflowStep>;
+  }
+
   /**
    * Clean up a completed workflow's storage.
    *

src/client/step.ts

@@ -36,7 +36,7 @@ export type StepRequest = {
       }
     | {
         kind: "event";
-        args: { eventId?: EventId<string> };
+        args: { eventId?: EventId };
       }
     | {
         kind: "workflow";

src/client/stepContext.ts

@@ -8,11 +8,11 @@ import type {
 import { safeFunctionName } from "./safeFunctionName.js";
 import type { StepRequest } from "./step.js";
 import type { RetryOption } from "@convex-dev/workpool";
-import type { RunOptions, WorkflowStep } from "./types.js";
+import type { RunOptions, WorkflowCtx } from "./types.js";
 import type { EventSpec, WorkflowId } from "../types.js";
 import { parse } from "convex-helpers/validators";
 
-export class StepContext implements WorkflowStep {
+export class StepContext implements WorkflowCtx {
   constructor(
     public workflowId: WorkflowId,
     private sender: BaseChannel<StepRequest>,

src/client/types.ts

@@ -7,7 +7,7 @@ import type {
 } from "convex/server";
 import type { api } from "../component/_generated/api.js";
 import type { GenericId } from "convex/values";
-import type { EventSpec, WorkflowId } from "../types.js";
+import type { EventId, EventSpec, WorkflowId } from "../types.js";
 
 export type WorkflowComponent = UseApi<typeof api>;
 
@@ -38,7 +38,7 @@ export type SchedulerOptions =
       runAfter?: number;
     };
 
-export type WorkflowStep = {
+export type WorkflowCtx = {
   /**
    * The ID of the workflow currently running.
    */
@@ -132,7 +132,7 @@ export type UseApi<API> = Expand<{
 export type OpaqueIds<T> =
   T extends GenericId<infer _T>
     ? string
-    : T extends WorkId
+    : T extends WorkId | WorkflowId | EventId<any>
       ? string
       : T extends (infer U)[]
         ? OpaqueIds<U>[]

src/component/_generated/api.d.ts

@@ -389,6 +389,45 @@ export type Mounts = {
         };
       }
     >;
+    listSteps: FunctionReference<
+      "query",
+      "public",
+      {
+        order: "asc" | "desc";
+        paginationOpts: {
+          cursor: string | null;
+          endCursor?: string | null;
+          id?: number;
+          maximumBytesRead?: number;
+          maximumRowsRead?: number;
+          numItems: number;
+        };
+        workflowId: string;
+      },
+      {
+        continueCursor: string;
+        isDone: boolean;
+        page: Array<{
+          args: any;
+          completedAt?: number;
+          eventId?: string;
+          kind: "function" | "workflow" | "event";
+          name: string;
+          nestedWorkflowId?: string;
+          runResult?:
+            | { kind: "success"; returnValue: any }
+            | { error: string; kind: "failed" }
+            | { kind: "canceled" };
+          startedAt: number;
+          stepId: string;
+          stepNumber: number;
+          workId?: string;
+          workflowId: string;
+        }>;
+        pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+        splitCursor?: string | null;
+      }
+    >;
   };
 };
 // For now fullApiWithMounts is only fullApi which provides
@@ -422,6 +461,7 @@ export declare const components: {
         "internal",
         {
           before?: number;
+          limit?: number;
           logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
         },
         any

src/component/workflow.ts

@@ -1,17 +1,35 @@
 import { vResultValidator } from "@convex-dev/workpool";
 import { assert } from "convex-helpers";
-import type { FunctionHandle } from "convex/server";
+import {
+  paginationOptsValidator,
+  type FunctionHandle,
+  type PaginationResult,
+} from "convex/server";
 import { type Infer, v } from "convex/values";
 import { mutation, type MutationCtx, query } from "./_generated/server.js";
 import { type Logger, logLevel } from "./logging.js";
 import { getWorkflow } from "./model.js";
 import { getWorkpool } from "./pool.js";
-import { journalDocument, vOnComplete, workflowDocument } from "./schema.js";
+import schema, {
+  journalDocument,
+  vOnComplete,
+  workflowDocument,
+  type JournalEntry,
+} from "./schema.js";
 import { getDefaultLogger } from "./utils.js";
-import type { WorkflowId, OnCompleteArgs } from "../types.js";
+import {
+  type WorkflowId,
+  type OnCompleteArgs,
+  type WorkflowStep,
+  type EventId,
+  vPaginationResult,
+  vWorkflowStep,
+} from "../types.js";
 import { api, internal } from "./_generated/api.js";
 import { formatErrorWithStack } from "../shared.js";
 import type { SchedulerOptions } from "../client/types.js";
+import type { Id } from "./_generated/dataModel.js";
+import { paginator } from "convex-helpers/server/pagination";
 
 const createArgs = v.object({
   workflowName: v.string(),
@@ -95,6 +113,60 @@ export const getStatus = query({
   },
 });
 
+function publicWorkflowId(workflowId: Id<"workflows">): WorkflowId {
+  return workflowId as any;
+}
+
+function publicStep(step: JournalEntry): WorkflowStep {
+  return {
+    workflowId: publicWorkflowId(step.workflowId),
+    name: step.step.name,
+    stepId: step._id,
+    stepNumber: step.stepNumber,
+
+    args: step.step.args,
+    runResult: step.step.runResult,
+
+    startedAt: step.step.startedAt,
+    completedAt: step.step.completedAt,
+
+    ...(step.step.kind === "event"
+      ? {
+          kind: "event",
+          eventId: step.step.eventId as unknown as EventId,
+        }
+      : step.step.kind === "workflow"
+        ? {
+            kind: "workflow",
+            nestedWorkflowId: publicWorkflowId(step.step.workflowId!),
+          }
+        : {
+            kind: "function",
+            workId: step.step.workId!,
+          }),
+  } satisfies WorkflowStep;
+}
+
+export const listSteps = query({
+  args: {
+    workflowId: v.id("workflows"),
+    order: v.union(v.literal("asc"), v.literal("desc")),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: vPaginationResult(vWorkflowStep),
+  handler: async (ctx, args) => {
+    const result = await paginator(ctx.db, schema)
+      .query("steps")
+      .withIndex("workflow", (q) => q.eq("workflowId", args.workflowId))
+      .order(args.order)
+      .paginate(args.paginationOpts);
+    return {
+      ...result,
+      page: result.page.map(publicStep),
+    } as PaginationResult<Infer<typeof vWorkflowStep>>;
+  },
+});
+
 export const cancel = mutation({
   args: {
     workflowId: v.id("workflows"),