no-nested-when-in-workflow - ESLint plugin rules

This rule disallows calling when(...) inside a when().then() callback in a workflow composition function.

Severity#

error. This rule is enabled in the recommended preset.

What it Targets#

This rule targets when(...) calls that appear inside the callback of another when().then() call within a createWorkflow body.

The following code is reported by the rule:

src/workflows/example.ts
1import {2  createWorkflow,3  when,4  WorkflowResponse,5} from "@medusajs/framework/workflows-sdk"6
7createWorkflow("my-workflow", (input) => {8  const result = when({ input }, (d) => d.input.items.length > 0).then(() => {9    // Reported: `when` nested inside another `when().then()` callback10    const inner = when({ input }, (d) => d.input.flag).then(() => someStep(input))11    return inner12  })13
14  return new WorkflowResponse(result)15})

Instead, restructure the logic into sibling when(...).then(...) calls at the same level:

src/workflows/example.ts
1import {2  createWorkflow,3  when,4  WorkflowResponse,5} from "@medusajs/framework/workflows-sdk"6
7createWorkflow("my-workflow", (input) => {8  const result = when({ input }, (d) => d.input.items.length > 0).then(() =>9    outerStep(input)10  )11
12  const inner = when({ input }, (d) => d.input.items.length > 0 && d.input.flag)13    .then(() => someStep(input))14
15  return new WorkflowResponse(result)16})

Why it's Important#

when tracks its pending condition in a single shared slot rather than a stack. When you nest a when(...) call inside a when().then() callback, the inner .then() clears that shared slot before the outer .then() reads it. This causes a TypeError: Cannot read properties of undefined (reading 'steps') at server boot rather than at build time, making the bug difficult to trace.

Learn more in the Conditions in Workflows documentation.

Fixable#

This rule isn't auto-fixable.