@xano/developer-mcp 1.0.26 → 1.0.27

package/dist/xanoscript_docs_auto/control-flow.md

@@ -1,543 +0,0 @@
----
-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"
-}
-```