breaking: implement workflow hooks (first iteration)

[thetutlage]

Fixes: FRMW-2629

This PR implements the workflow hooks proposal as defined in the linked RFC.

---

ChangeLog

This PR adds a new helper, createHook, to the workflows-sdk. The createHook helper exposes a hook from a workflow. Later (after the workflow has been composed), the workflow consumers can bind a handler to the hook to run custom logic.

Note

As of now, you can only register one hook handler, and the workflow orchestrator ignores the return value.

Exposing hook via createHook

import {
  createStep,
  createHook,
  createWorkflow,
  WorkflowResponse
} from '@medusajs/workflows-sdk'

const createProductStep = createStep('createProduct', function () {
  // business logic for "createProduct"
})

const workflow = createWorkflow('name', function (input) {
  createProductStep(input)
  const productCreatedHook = createHook('productCreated', { productId: input.id })

  return new WorkflowResponse(input, {
    hooks: [productCreatedHook]
  })
})

Points to note

• Unlike the createStep function, the createHook method is called within the workflow composition callback.
• You must return the created hooks from the composition callback. Returning of hooks is needed for the TypeScript engine to provide intellisense when registering a handler for the hook.
• Hooks are executed in the same position as they are defined within the composition callback

Registering the hook handler

The workflow user must register a hook handler to run custom logic within a workflow. They can do that as follows.

workflow.hooks.productCreated(() => {
  // run custom business logic
})

Points to note

• The hook handler behaves similarly to a workflow step. It can run async code, will be retried, and can also have compensation behavior (defined as the 2nd parameter)
• There can only be one handler for a hook. If you need multiple handlers, you should create another workflow and register that as the hook handler (not supported yet).
• The return value of the hook handler is ignored in this first iteration.

Introducing the WorkflowResponse class and breaking changes

The introduction of hooks has changed the return value of the createWorkflow composition callback. Now, we must return both the workflow results and the configured hooks.

Instead of manually composing the return value, you can use the WorkflowResponse class to construct the current response. The WorkflowResponse class accepts the following parameters.

• The first parameter is the result of the workflow.
• The second parameter (optional) is a config object with configured hooks.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
medusa-dashboard	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 31, 2024 9:41am

6 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
api-reference	⬜️ Ignored (Inspect)			Jul 31, 2024 9:41am
api-reference-v2	⬜️ Ignored (Inspect)	Visit Preview		Jul 31, 2024 9:41am
docs-ui	⬜️ Ignored (Inspect)	Visit Preview		Jul 31, 2024 9:41am
docs-v2	⬜️ Ignored (Inspect)	Visit Preview		Jul 31, 2024 9:41am
medusa-docs	⬜️ Ignored (Inspect)	Visit Preview		Jul 31, 2024 9:41am
resources-docs	⬜️ Ignored (Inspect)	Visit Preview		Jul 31, 2024 9:41am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0b8901b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[thetutlage]

@olivermrbl @srindom The PR is ready for the final review. Maybe you can go through the changelog once (in the PR description) to see if everything looks as expected.

[olivermrbl]

LGTM, nice work 🚢