From 368715ae374208be246c3a802a6a7bd4b71daad4 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 11 Jul 2024 15:30:50 +0300 Subject: [PATCH] docs: document when-then + migrations revert change (#8089) - Add documentation around when-then and workflow conditions - Change the CLI reference based on change in revert migrations command. --- .../workflows/conditions/page.mdx | 62 +++++++++++++++++++ .../constructor-constraints/page.mdx | 29 +++++++++ www/apps/book/sidebar.mjs | 4 ++ www/apps/resources/app/medusa-cli/page.mdx | 21 ++++--- 4 files changed, 108 insertions(+), 8 deletions(-) create mode 100644 www/apps/book/app/advanced-development/workflows/conditions/page.mdx diff --git a/www/apps/book/app/advanced-development/workflows/conditions/page.mdx b/www/apps/book/app/advanced-development/workflows/conditions/page.mdx new file mode 100644 index 0000000000..2d4939f6bc --- /dev/null +++ b/www/apps/book/app/advanced-development/workflows/conditions/page.mdx @@ -0,0 +1,62 @@ +export const metadata = { + title: `${pageNumber} Conditions in Workflow with When-Then`, +} + +# {metadata.title} + +In this chapter, you'll learn how to execute an action based on a condition in a workflow using the when-then utility. + +## What is the When-Then Utility? + +The when-then utility executes an action if a condition is satisfied. + +Since if-conditions aren't allowed in the workflow constructor function, use the when-then utility if you want to execute a step based on a condition. + +--- + +## How to Use the When-Then Utility? + +For example: + +export const highlights = [ + ["15", "input", "The data to pass as a parameter to the function in the second parameter"], + ["17", "return", "The function must return a boolean value indicating whether\nthe callback function passed to `then` should be executed."], + ["19", "() => {", "The function to execute if `when`'s second parameter returns a `true` value."] +] + +```ts highlights={highlights} +import { + createWorkflow, + when +} from "@medusajs/workflows-sdk" +// step imports... + +type WorkflowInput = { + is_active: boolean +} + +const workflow = createWorkflow + + ("workflow", function (input) { + const result = when( + input, + (input) => { + return input.is_active + } + ).then(() => { + const stepResult = isActiveStep() + return stepResult + }) + + // executed without condition + return anotherStep(result) + } +) +``` + +Then `when` utility is a function imported from `@medusajs/workflows-sdk`. It accepts the following parameters: + +1. An object or the workflow's input. This data is passed as a parameter to the function in `when`'s second parameter. +2. A function that returns a boolean indicating whether to execute the action. + +To specify the action to perform if the condition is satisfied, chain a `then` function to `when` and pass it a callback function. The callback function is only executed if `when`'s second parameter function returns a `true` value. \ No newline at end of file diff --git a/www/apps/book/app/advanced-development/workflows/constructor-constraints/page.mdx b/www/apps/book/app/advanced-development/workflows/constructor-constraints/page.mdx index 825956f2ad..ccd6bb59be 100644 --- a/www/apps/book/app/advanced-development/workflows/constructor-constraints/page.mdx +++ b/www/apps/book/app/advanced-development/workflows/constructor-constraints/page.mdx @@ -75,6 +75,35 @@ const myWorkflow = createWorkflow< }) ``` +### No If Conditions + +You can't use if-conditions in a workflow. Instead, use the when-then utility function explained in the next chapter: + +```ts +// Don't +const myWorkflow = createWorkflow< + WorkflowInput, + WorkflowOutput +>("hello-world", function (input) { + if (input.is_active) { + // perform an action + } +}) + +// Do (explained in the next chapter) +const myWorkflow = createWorkflow< + WorkflowInput, + WorkflowOutput +>("hello-world", function (input) { + when(input, (input) => { + return input.is_active + }) + .then(() => { + // perform an action + }) +}) +``` + --- ## Step Constraints diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index 359be4c972..81f39e41eb 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -191,6 +191,10 @@ export const sidebar = sidebarAttachHrefCommonOptions( path: "/advanced-development/workflows/constructor-constraints", title: "Workflow Constraints", }, + { + path: "/advanced-development/workflows/conditions", + title: "Conditions in Workflows", + }, { path: "/advanced-development/workflows/compensation-function", title: "Compensation Function", diff --git a/www/apps/resources/app/medusa-cli/page.mdx b/www/apps/resources/app/medusa-cli/page.mdx index b60a77d589..2882764f0a 100644 --- a/www/apps/resources/app/medusa-cli/page.mdx +++ b/www/apps/resources/app/medusa-cli/page.mdx @@ -340,12 +340,20 @@ npx medusa start -### migrations +### migrations run -Perform migration actions to reflect changes on the database, such as running or reverting migrations. +Run the latest migrations to reflect changes on the database. ```bash -npx medusa migrations +npx medusa migrations run +``` + +### migration revert + +Revert the last migrations ran on one or more modules. + +```bash +npx medusa migrations revert ``` #### Arguments @@ -362,15 +370,12 @@ npx medusa migrations - `action` + `module_names` - The action to perform. Values can be `run`, `show`, or `revert`. - `run` is used to run the migrations; `show` is used to only show - what migrations are available to run; and `revert` is to undo the - last migration. + The name of one or more module, separated by spaces. For example, `helloModuleService`.