Skip to content

Commit

Permalink
docs: improve transform docs (#10023)
Browse files Browse the repository at this point in the history
  • Loading branch information
shahednasser authored Nov 11, 2024
1 parent 0ef92cc commit c4183a5
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ export const metadata = {

# {metadata.title}

In this chapter, you'll learn how to manipulate variables in a workflow using the transform utility.
In this chapter, you'll learn how to use the `transform` utility to manipulate variables in a workflow.

## Why Variable Manipulation isn't Allowed in Workflows?

Expand Down Expand Up @@ -113,4 +113,77 @@ This workflow receives an `items` array in its input.

You use the `transform` utility to create an `ids` variable, which is an array of strings holding the `id` of each item in the `items` array.

You then pass the `ids` variable as a parameter to the `doSomethingStep`.
You then pass the `ids` variable as a parameter to the `doSomethingStep`.

---

## Caveats

### Transform Evaluation

The transform utility's value is only evaluated if you pass its output to a step or in the workflow response.

For example, if you have the following workflow:

```ts
const myWorkflow = createWorkflow(
"hello-world",
function (input) {
const str = transform(
{ input },
(data) => `${data.input.str1}${data.input.str2}`
)

return new WorkflowResponse("done")
}
)
```

Since `str`'s value isn't used as a step's input or passed to `WorkflowResponse`, its value is never evaluated.

### Data Validation

The `transform` utility should only be used to perform variable or data manipulation.

If you want to perform some validation on the data, use a step or the [when-then utility](../conditions/page.mdx) instead.

For example:

```ts
// DON'T
const myWorkflow = createWorkflow(
"hello-world",
function (input) {
const str = transform(
{ input },
(data) => {
if (!input.str1) {
throw new Error("Not allowed!")
}
}
)
}
)

// DO
const validateHasStr1Step = createStep(
"validate-has-str1",
({ input }) => {
if (!input.str1) {
throw new Error("Not allowed!")
}
}
)

const myWorkflow = createWorkflow(
"hello-world",
function (input) {
validateHasStr1({
input
})

// workflow continues its execution only if
// the step doesn't throw the error.
}
)
```
2 changes: 1 addition & 1 deletion www/apps/book/generated/edit-dates.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ export const generatedEditDates = {
"app/learn/debugging-and-testing/instrumentation/page.mdx": "2024-09-17T08:53:15.910Z",
"app/learn/advanced-development/api-routes/additional-data/page.mdx": "2024-09-30T08:43:53.120Z",
"app/learn/advanced-development/workflows/page.mdx": "2024-09-18T08:00:57.364Z",
"app/learn/advanced-development/workflows/variable-manipulation/page.mdx": "2024-09-30T08:43:53.130Z",
"app/learn/advanced-development/workflows/variable-manipulation/page.mdx": "2024-11-11T13:33:41.270Z",
"app/learn/customization/custom-features/api-route/page.mdx": "2024-09-12T12:42:34.201Z",
"app/learn/customization/custom-features/module/page.mdx": "2024-10-16T08:49:44.676Z",
"app/learn/customization/custom-features/workflow/page.mdx": "2024-09-30T08:43:53.133Z",
Expand Down
4 changes: 2 additions & 2 deletions www/apps/book/sidebar.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -409,12 +409,12 @@ export const sidebar = numberSidebarItems(
{
type: "link",
path: "/learn/advanced-development/workflows/variable-manipulation",
title: "Variable Manipulation",
title: "Transform Variables",
},
{
type: "link",
path: "/learn/advanced-development/workflows/conditions",
title: "Using Conditions",
title: "When-Then Conditions",
},
{
type: "link",
Expand Down

0 comments on commit c4183a5

Please sign in to comment.