@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/xanoscript_docs_auto/control-flow.md

@@ -0,0 +1,543 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Control Flow
+
+Conditionals, loops, and error handling in XanoScript.
+
+## Quick Reference
+
+| Structure | Purpose |
+|-----------|---------|
+| `conditional` | If/elseif/else branching |
+| `switch` | Multi-case matching |
+| `for` | Fixed iteration count |
+| `foreach` | Array iteration |
+| `while` | Condition-based loop |
+| `try_catch` | Error handling |
+| `precondition` | Validation with typed errors |
+| `break` | Exit loop |
+| `continue` | Skip to next iteration |
+| `return` | Exit function with value |
+| `throw` | Raise error |
+
+---
+
+## Conditional (if/elseif/else)
+
+### Basic If
+
+```xs
+conditional {
+  if ($input.age >= 18) {
+    var $status { value = "adult" }
+  }
+}
+```
+
+### If/Else
+
+```xs
+conditional {
+  if ($user != null) {
+    var $message { value = "Welcome, " ~ $user.name }
+  }
+  else {
+    var $message { value = "Please log in" }
+  }
+}
+```
+
+### If/Elseif/Else
+
+```xs
+conditional {
+  if ($input.score >= 90) {
+    var $grade { value = "A" }
+  }
+  elseif ($input.score >= 80) {
+    var $grade { value = "B" }
+  }
+  elseif ($input.score >= 70) {
+    var $grade { value = "C" }
+  }
+  elseif ($input.score >= 60) {
+    var $grade { value = "D" }
+  }
+  else {
+    var $grade { value = "F" }
+  }
+}
+```
+
+### Nested Conditionals
+
+```xs
+conditional {
+  if ($user != null) {
+    conditional {
+      if ($user.role == "admin") {
+        var $access { value = "full" }
+      }
+      elseif ($user.role == "moderator") {
+        var $access { value = "partial" }
+      }
+      else {
+        var $access { value = "basic" }
+      }
+    }
+  }
+  else {
+    var $access { value = "none" }
+  }
+}
+```
+
+---
+
+## Switch Statement
+
+Match against multiple cases:
+
+```xs
+switch ($input.status) {
+  case ("pending") {
+    var $action { value = "review" }
+  } break
+  case ("approved") {
+    var $action { value = "process" }
+  } break
+  case ("rejected") {
+    var $action { value = "notify" }
+  } break
+  default {
+    var $action { value = "unknown" }
+  }
+}
+```
+
+### Multiple Values per Case
+
+```xs
+switch ($input.method) {
+  case ("GET", "HEAD") {
+    var $type { value = "read" }
+  } break
+  case ("POST", "PUT", "PATCH") {
+    var $type { value = "write" }
+  } break
+  case ("DELETE") {
+    var $type { value = "delete" }
+  } break
+  default {
+    var $type { value = "other" }
+  }
+}
+```
+
+---
+
+## For Loop
+
+Fixed number of iterations:
+
+```xs
+for (10) {
+  each as $index {
+    debug.log { value = "Iteration: " ~ $index }
+  }
+}
+```
+
+### With Variable Count
+
+```xs
+for ($input.count) {
+  each as $i {
+    array.push {
+      array = $items
+      value = {index: $i}
+    }
+  }
+}
+```
+
+### Building Arrays
+
+```xs
+var $squares { value = [] }
+
+for (5) {
+  each as $n {
+    var $square { value = ($n + 1) * ($n + 1) }
+    array.push {
+      array = $squares
+      value = $square
+    }
+  }
+}
+// $squares = [1, 4, 9, 16, 25]
+```
+
+---
+
+## Foreach Loop
+
+Iterate over arrays:
+
+```xs
+foreach ($input.items) {
+  each as $item {
+    debug.log { value = $item }
+  }
+}
+```
+
+### With Index
+
+```xs
+foreach ($input.users) {
+  each as $user {
+    debug.log {
+      value = "User " ~ $this.index ~ ": " ~ $user.name
+    }
+  }
+}
+```
+
+### Processing Array Elements
+
+```xs
+var $processed { value = [] }
+
+foreach ($input.orders) {
+  each as $order {
+    function.run "calculate_total" {
+      input = {order: $order}
+    } as $total
+
+    array.push {
+      array = $processed
+      value = {
+        id: $order.id,
+        total: $total
+      }
+    }
+  }
+}
+```
+
+---
+
+## While Loop
+
+Repeat while condition is true:
+
+```xs
+var $counter { value = 0 }
+
+while ($counter < 10) {
+  each {
+    debug.log { value = $counter }
+    var.update $counter { value = $counter + 1 }
+  }
+}
+```
+
+### Pagination Example
+
+```xs
+var $page { value = 1 }
+var $has_more { value = true }
+var $all_items { value = [] }
+
+while ($has_more) {
+  each {
+    api.request {
+      url = "https://api.example.com/items"
+      params = {page: $page, limit: 100}
+    } as $response
+
+    array.merge {
+      array = $all_items
+      with = $response.data
+    }
+
+    var.update $has_more {
+      value = $response.data|count == 100
+    }
+    var.update $page { value = $page + 1 }
+  }
+}
+```
+
+---
+
+## Loop Control
+
+### Break
+
+Exit the loop immediately:
+
+```xs
+foreach ($input.items) {
+  each as $item {
+    conditional {
+      if ($item.id == $input.target_id) {
+        var $found { value = $item }
+        break
+      }
+    }
+  }
+}
+```
+
+### Continue
+
+Skip to next iteration:
+
+```xs
+foreach ($input.users) {
+  each as $user {
+    conditional {
+      if (!$user.active) {
+        continue
+      }
+    }
+
+    // Only runs for active users
+    function.run "process_user" {
+      input = {user: $user}
+    }
+  }
+}
+```
+
+---
+
+## Try/Catch/Finally
+
+Handle errors gracefully:
+
+```xs
+try_catch {
+  try {
+    function.run "risky_operation" {
+      input = {data: $input.data}
+    } as $result
+  }
+  catch {
+    debug.log { value = "Error: " ~ $error.message }
+    var $result { value = null }
+  }
+}
+```
+
+### With Finally
+
+```xs
+try_catch {
+  try {
+    db.add user {
+      data = $input.user_data
+    } as $user
+  }
+  catch {
+    debug.log { value = "Failed to create user" }
+    throw {
+      name = "CreateError"
+      value = $error.message
+    }
+  }
+  finally {
+    debug.log { value = "Operation completed" }
+  }
+}
+```
+
+### Accessing Error Info
+
+In catch blocks, `$error` contains:
+
+```xs
+catch {
+  var $error_name { value = $error.name }
+  var $error_message { value = $error.message }
+  var $error_code { value = $error.code }
+}
+```
+
+---
+
+## Preconditions
+
+Validate conditions and throw typed errors:
+
+```xs
+precondition ($input.amount > 0) {
+  error_type = "inputerror"
+  error = "Amount must be positive"
+}
+
+precondition ($user != null) {
+  error_type = "notfound"
+  error = "User not found"
+}
+
+precondition ($user.id == $auth.id) {
+  error_type = "accessdenied"
+  error = "Not authorized"
+}
+```
+
+### Error Types
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 Bad Request | Invalid input data |
+| `accessdenied` | 403 Forbidden | Authorization failure |
+| `notfound` | 404 Not Found | Resource doesn't exist |
+| `standard` | 500 Internal Server Error | General errors |
+
+---
+
+## Throw
+
+Raise custom errors:
+
+```xs
+throw {
+  name = "ValidationError"
+  value = "Email format is invalid"
+}
+```
+
+### With Error Code
+
+```xs
+throw {
+  name = "APIError"
+  value = "Rate limit exceeded"
+  code = 429
+}
+```
+
+---
+
+## Return
+
+Exit function early with a value:
+
+```xs
+conditional {
+  if ($input.skip) {
+    return { value = null }
+  }
+}
+
+// Only reached if not skipping
+db.query user {} as $users
+```
+
+### Return from Nested Logic
+
+```xs
+conditional {
+  if ($cached != null) {
+    return { value = $cached }
+  }
+}
+
+// Cache miss - fetch from database
+db.get user {
+  field_name = "id"
+  field_value = $input.id
+} as $user
+
+return { value = $user }
+```
+
+---
+
+## Pattern: Guard Clauses
+
+Use early returns to simplify logic:
+
+```xs
+function "process_order" {
+  input { int order_id }
+  stack {
+    // Guard: Check order exists
+    db.get order {
+      field_name = "id"
+      field_value = $input.order_id
+    } as $order
+
+    precondition ($order != null) {
+      error_type = "notfound"
+      error = "Order not found"
+    }
+
+    // Guard: Check order is processable
+    precondition ($order.status == "pending") {
+      error_type = "inputerror"
+      error = "Order already processed"
+    }
+
+    // Guard: Check user is authorized
+    precondition ($order.user_id == $auth.id || $auth.role == "admin") {
+      error_type = "accessdenied"
+      error = "Not authorized to process this order"
+    }
+
+    // Main logic (only reached if all guards pass)
+    db.edit order {
+      field_name = "id"
+      field_value = $order.id
+      data = {status: "processing"}
+    } as $updated
+  }
+  response = $updated
+}
+```
+
+---
+
+## Pattern: Retry Logic
+
+```xs
+var $attempts { value = 0 }
+var $max_attempts { value = 3 }
+var $success { value = false }
+
+while (!$success && $attempts < $max_attempts) {
+  each {
+    var.update $attempts { value = $attempts + 1 }
+
+    try_catch {
+      try {
+        api.request {
+          url = $external_api_url
+          method = "POST"
+          body = $payload
+        } as $response
+
+        var.update $success { value = true }
+      }
+      catch {
+        conditional {
+          if ($attempts < $max_attempts) {
+            util.sleep { duration = 1000 * $attempts }
+          }
+        }
+      }
+    }
+  }
+}
+
+precondition ($success) {
+  error_type = "standard"
+  error = "Failed after " ~ $max_attempts ~ " attempts"
+}
+```