when-block-must-have-name - ESLint plugin rules

This rule requires a when(...) call to include an explicit name as its first argument when its .then() callback returns a value that isn't a direct step invocation.

Severity#

warn. This rule is enabled in the recommended preset.

What it Targets#

This rule targets when(...) calls inside createWorkflow bodies that:

• use the two-argument form when(values, condition) (no name), and
• have a .then() callback that returns something that isn't a step result.

When the .then() callback returns a transform(...) call, a plain object literal, or any other non-step result, Medusa wraps the result in a synthetic step. Without an explicit name, Medusa assigns a random name to that step at runtime and logs a warning in production.

The following code is reported by the rule:

src/workflows/example.ts
1import {2  createWorkflow,3  when,4  transform,5} from "@medusajs/framework/workflows-sdk"6
7export const exampleWorkflow = createWorkflow(8  "example",9  (input) => {10    when({ input }, ({ input }) => input.data?.custom_amount === null).then(11      () => {12        return transform({ input }, ({ input }) => ({ id: input.id }))13      }14    )15  }16)

To fix this, pass a unique name as the first argument to when:

src/workflows/example.ts
1import {2  createWorkflow,3  when,4  transform,5} from "@medusajs/framework/workflows-sdk"6
7export const exampleWorkflow = createWorkflow(8  "example",9  (input) => {10    when("custom-amount-null", { input }, ({ input }) => input.data?.custom_amount === null).then(11      () => {12        return transform({ input }, ({ input }) => ({ id: input.id }))13      }14    )15  }16)

Why it's Important#

When the .then() callback returns a value that Medusa wraps in a synthetic step (such as a transform result), Medusa assigns a random name to that step at runtime if no name is provided. Random names change across restarts, which makes distributed-tracing logs and compensation-log entries hard to read and correlates poorly across runs.

Learn more in the Workflows documentation.

Fixable#

This rule is not auto-fixable. You must add the name manually as the first argument to when.

Turn it Off#

To turn off this rule, set it to off in your ESLint configuration:

eslint.config.ts
1import { defineConfig } from "eslint/config"2import medusa from "@medusajs/eslint-plugin"3
4export default defineConfig([5  ...medusa.configs.recommended,6  {7    rules: {8      "@medusajs/when-block-must-have-name": "off",9    },10  },11])

Or disable it for a single line using an inline comment:

Code
1// eslint-disable-next-line @medusajs/when-block-must-have-name2when({ input }, ({ input }) => !!input.flag).then(() => {