read configureWorkflow() without resolving the class workflow

[adenhertog]

Closes #354

Summary

bus-core reads a class workflow's configureWorkflow() from an instance created with Object.create(prototype), so the workflow is only resolved (or constructed) to handle a message. bus-nestjs drops WorkflowResolvedWithoutMessage, which no longer has a case to report.

Background

To read a class workflow's mapping, WorkflowRegistry.getClassWorkflowHandlers resolved the workflow once at registration: from the container with no message, or with new and no arguments. #352 added WorkflowResolvedWithoutMessage to bus-nestjs because a request-scoped workflow got REQUEST === undefined then.

Problem

Reading the mapping ran the constructor and built the workflow's whole dependency tree with no message. A request-scoped workflow couldn't read REQUEST in its constructor, and dependencies with side effects in their constructors were created just to read the configuration.

Approach

• New internal configureClassWorkflow() (workflow/configure-class-workflow.ts) calls configureWorkflow(mapper) on Object.create(WorkflowCtor.prototype). If it throws anything other than the mapper's own errors, it's wrapped in a new exported WorkflowConfigurationFailed, which names the workflow, keeps the error as cause and has a help text. The registry and testWorkflow() both use it, so a test fails the same way the bus does.

• WorkflowMapper.startedBy/when throw the new WorkflowMappingInvalid for a missing message, a handler name that isn't a string, or a lookup without a lookup function or mapsTo string. Without this, a value read from a field (e.g. lookup: this.byOrderId) would pass startup and then fail every message. configureClassWorkflow wraps the error in WorkflowConfigurationFailed. A configureWorkflow declared as an arrow function property, which TypeScript allows, fails with WorkflowConfigurationFailed and help that says to make it a method.

• Function workflows (defineWorkflow) are unchanged.

• bus-nestjs (unreleased): removed WorkflowResolvedWithoutMessage and its catch in nestContainer, and edited the pending nestjs-module changeset. The integration test now checks that a request-scoped workflow reading REQUEST in its constructor starts and gets the message.

• Breaking (minor changeset and a MIGRATING.md entry):

  • A configureWorkflow() that uses the instance's fields or injected dependencies now finds them undefined. Nothing in the repo or docs does this.
  • A workflow the container can't resolve now fails its messages with WorkflowHandlerFailed, as class handlers already do, rather than failing initialize(). bus-nestjs still fails at startup through its introspect check (BusClassNotProvided).

• Docs: the "Creating a workflow" guide covers how configureWorkflow is called, and the NestJS guide says request-scoped workflows can read REQUEST in their constructors.

• This is original work under the clean-room policy, not ported, translated or copied from another messaging framework

• Added a changeset (pnpm changeset) for user-facing changes to published packages, or none is needed

• Docs: updated docs/ for user-facing changes, or none needed

🤖 Generated with Claude Code