use a pattern to break type dependency cycles

Author: ianmacartney

example/convex/_generated/api.d.ts

@@ -11,7 +11,8 @@
 import type * as admin from "../admin.js";
 import type * as example from "../example.js";
 import type * as transcription from "../transcription.js";
-import type * as userConfirmation from "../userConfirmation.js";
+import type * as userConfirmation_steps from "../userConfirmation/steps.js";
+import type * as userConfirmation_workflow from "../userConfirmation/workflow.js";
 
 import type {
   ApiFromModules,
@@ -31,7 +32,8 @@ declare const fullApi: ApiFromModules<{
   admin: typeof admin;
   example: typeof example;
   transcription: typeof transcription;
-  userConfirmation: typeof userConfirmation;
+  "userConfirmation/steps": typeof userConfirmation_steps;
+  "userConfirmation/workflow": typeof userConfirmation_workflow;
 }>;
 declare const fullApiWithMounts: typeof fullApi;
 

example/convex/userConfirmation.ts

@@ -0,0 +1,31 @@
+import { v } from "convex/values";
+import { internalAction, internalMutation } from "../_generated/server";
+import { workflow } from "../example";
+import { vWorkflowId, defineEvent } from "@convex-dev/workflow";
+
+export const approvalEvent = defineEvent({
+  name: "approval",
+  validator: v.union(
+    v.object({ approved: v.literal(true), choice: v.number() }),
+    v.object({ approved: v.literal(false), reason: v.string() }),
+  ),
+});
+
+export const generateProposals = internalAction({
+  args: { prompt: v.string() },
+  handler: async (_ctx, _args) => {
+    // imagine this is a call to an LLM
+    return ["proposal1", "proposal2", "proposal3"];
+  },
+});
+
+export const chooseProposal = internalMutation({
+  args: { workflowId: vWorkflowId, choice: v.number() },
+  handler: async (ctx, args) => {
+    await workflow.sendEvent(ctx, args.workflowId, approvalEvent, {
+      approved: true,
+      choice: args.choice,
+    });
+    return true;
+  },
+});

example/convex/userConfirmation/steps.ts

@@ -0,0 +1,30 @@
+import { v } from "convex/values";
+import { anyApi, type ApiFromModules } from "convex/server";
+import { workflow } from "../example";
+import { approvalEvent } from "./steps";
+
+// This allows us to scope an `internal` object to just the steps file,
+// breaking circular dependency issues.
+const steps = (
+  anyApi as unknown as ApiFromModules<{
+    "userConfirmation/steps": typeof import("./steps");
+  }>
+).userConfirmation.steps;
+
+export const confirmationWorkflow = workflow.define({
+  args: { prompt: v.string() },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    const proposals = await ctx.runAction(
+      steps.generateProposals,
+      { prompt: args.prompt },
+      { retry: true },
+    );
+    const approval = await ctx.awaitEvent(approvalEvent);
+    if (!approval.approved) {
+      return "rejected: " + approval.reason;
+    }
+    const choice = proposals[approval.choice];
+    return choice;
+  },
+});