export const metadata = { title: when-block-must-have-name - ESLint plugin rules, }

{metadata.title}

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:

import {
  createWorkflow,
  when,
  transform,
} from "@medusajs/framework/workflows-sdk"

export const exampleWorkflow = createWorkflow(
  "example",
  (input) => {
    when({ input }, ({ input }) => input.data?.custom_amount === null).then(
      () => {
        return transform({ input }, ({ input }) => ({ id: input.id }))
      }
    )
  }
)

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

import {
  createWorkflow,
  when,
  transform,
} from "@medusajs/framework/workflows-sdk"

export const exampleWorkflow = createWorkflow(
  "example",
  (input) => {
    when("custom-amount-null", { input }, ({ input }) => input.data?.custom_amount === null).then(
      () => {
        return transform({ input }, ({ input }) => ({ id: input.id }))
      }
    )
  }
)

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:

import { defineConfig } from "eslint/config"
import medusa from "@medusajs/eslint-plugin"

export default defineConfig([
  ...medusa.configs.recommended,
  {
    rules: {
      "@medusajs/when-block-must-have-name": "off",
    },
  },
])

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

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