docs: improve transform docs

www/apps/book/app/learn/advanced-development/workflows/variable-manipulation/page.mdx

@@ -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?
 
@@ -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.
+  }
+)
+```

www/apps/book/generated/edit-dates.mjs

@@ -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",

www/apps/book/sidebar.mjs

@@ -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",