@xano/developer-mcp 1.0.27 → 1.0.29

package/dist/xanoscript_docs_auto/debugging.md

@@ -0,0 +1,527 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Debugging
+
+Logging, inspecting, and debugging XanoScript execution.
+
+## Quick Reference
+
+| Function | Purpose |
+|----------|---------|
+| `debug.log` | Log value to debugger |
+| `debug.stop` | Stop execution and inspect |
+| `precondition` | Assert condition with error |
+| `throw` | Raise custom error |
+
+---
+
+## debug.log
+
+Log values during execution:
+
+```xs
+debug.log {
+  value = "Processing started"
+}
+
+debug.log {
+  value = $input
+}
+
+debug.log {
+  value = {
+    user_id: $user.id,
+    action: "login",
+    timestamp: now
+  }
+}
+```
+
+### Log with Labels
+
+```xs
+debug.log {
+  value = "User ID: " ~ $user.id
+}
+
+debug.log {
+  value = "Items: " ~ ($items|json_encode)
+}
+
+debug.log {
+  value = "Count: " ~ ($results|count)
+}
+```
+
+### Log Objects
+
+```xs
+debug.log {
+  value = {
+    step: "after_validation",
+    input: $input,
+    user: $user,
+    is_valid: $is_valid
+  }
+}
+```
+
+---
+
+## debug.stop
+
+Stop execution and inspect state:
+
+```xs
+debug.stop {
+  value = "Inspection point"
+}
+
+debug.stop {
+  value = {
+    variables: {
+      user: $user,
+      items: $items,
+      total: $total
+    },
+    input: $input,
+    auth: $auth
+  }
+}
+```
+
+### Conditional Stop
+
+```xs
+conditional {
+  if ($suspicious_value) {
+    debug.stop {
+      value = "Suspicious value detected"
+    }
+  }
+}
+```
+
+---
+
+## 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 ($auth.role == "admin") {
+  error_type = "accessdenied"
+  error = "Admin access required"
+}
+```
+
+### Error Types
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 | Invalid input |
+| `accessdenied` | 403 | Unauthorized |
+| `notfound` | 404 | Resource missing |
+| `standard` | 500 | General error |
+
+---
+
+## Throwing Errors
+
+### Basic Throw
+
+```xs
+throw {
+  name = "ValidationError"
+  value = "Email format is invalid"
+}
+```
+
+### With Error Code
+
+```xs
+throw {
+  name = "RateLimitError"
+  value = "Too many requests"
+  code = 429
+}
+```
+
+### Conditional Throw
+
+```xs
+conditional {
+  if ($user == null) {
+    throw {
+      name = "UserNotFound"
+      value = "User with ID " ~ $input.user_id ~ " not found"
+      code = 404
+    }
+  }
+}
+```
+
+---
+
+## Try/Catch Debugging
+
+### Log Errors
+
+```xs
+try_catch {
+  try {
+    function.run "risky_operation" {
+      input = $data
+    } as $result
+  }
+  catch {
+    debug.log {
+      value = {
+        error_name: $error.name,
+        error_message: $error.message,
+        error_code: $error.code,
+        input_data: $data
+      }
+    }
+
+    // Rethrow or handle
+    throw {
+      name = $error.name
+      value = $error.message
+      code = $error.code
+    }
+  }
+}
+```
+
+### Error Recovery
+
+```xs
+try_catch {
+  try {
+    api.request {
+      url = $external_api
+      timeout = 5000
+    } as $response
+  }
+  catch {
+    debug.log {
+      value = "External API failed, using fallback"
+    }
+
+    var $response {
+      value = {data: [], cached: true}
+    }
+  }
+}
+```
+
+---
+
+## Logging Patterns
+
+### Execution Tracing
+
+```xs
+function "process_order" {
+  input { int order_id }
+  stack {
+    debug.log { value = "START: process_order(" ~ $input.order_id ~ ")" }
+
+    db.get order {
+      field_name = "id"
+      field_value = $input.order_id
+    } as $order
+
+    debug.log { value = "STEP: Fetched order" }
+
+    function.run "validate_order" {
+      input = {order: $order}
+    } as $valid
+
+    debug.log { value = "STEP: Validation result = " ~ $valid }
+
+    function.run "charge_payment" {
+      input = {order: $order}
+    } as $payment
+
+    debug.log { value = "STEP: Payment charged" }
+
+    debug.log { value = "END: process_order" }
+  }
+  response = $payment
+}
+```
+
+### Performance Logging
+
+```xs
+var $start_time { value = now|to_ms }
+
+// Expensive operation
+db.query large_table {
+  return = {type: "all"}
+} as $results
+
+var $end_time { value = now|to_ms }
+var $duration { value = $end_time - $start_time }
+
+debug.log {
+  value = "Query took " ~ $duration ~ "ms, returned " ~ ($results|count) ~ " rows"
+}
+```
+
+### Conditional Logging
+
+```xs
+// Only log in development
+conditional {
+  if ($env.DEBUG == "true") {
+    debug.log {
+      value = $detailed_info
+    }
+  }
+}
+```
+
+---
+
+## Database Debugging
+
+### Log Query Results
+
+```xs
+db.query user {
+  where = $db.user.active == true
+} as $users
+
+debug.log {
+  value = {
+    query: "active users",
+    count: $users|count,
+    first_10: $users|slice:0:10
+  }
+}
+```
+
+### Log Mutations
+
+```xs
+db.add user {
+  data = $user_data
+} as $new_user
+
+debug.log {
+  value = {
+    action: "user_created",
+    id: $new_user.id,
+    data: $user_data
+  }
+}
+```
+
+---
+
+## API Debugging
+
+### Log Requests
+
+```xs
+debug.log {
+  value = {
+    api_call: $external_api,
+    method: "POST",
+    body: $request_body
+  }
+}
+
+api.request {
+  url = $external_api
+  method = "POST"
+  body = $request_body
+} as $response
+
+debug.log {
+  value = {
+    api_response: $response,
+    status: $response.status
+  }
+}
+```
+
+### Log Authentication
+
+```xs
+debug.log {
+  value = {
+    auth_info: {
+      user_id: $auth.id,
+      role: $auth.role,
+      ip: $env.$remote_ip
+    }
+  }
+}
+```
+
+---
+
+## Debugging Tips
+
+### Isolate Problems
+
+```xs
+// Add log before suspected issue
+debug.log { value = "Before problematic code" }
+debug.log { value = $suspect_variable }
+
+// Problematic code
+function.run "suspect_function" {
+  input = $suspect_variable
+} as $result
+
+// Add log after
+debug.log { value = "After problematic code" }
+debug.log { value = $result }
+```
+
+### Check Variable Types
+
+```xs
+debug.log {
+  value = {
+    value: $variable,
+    type: $variable|is_array ? "array"
+        : $variable|is_object ? "object"
+        : $variable|is_int ? "int"
+        : $variable|is_text ? "text"
+        : $variable|is_null ? "null"
+        : "unknown"
+  }
+}
+```
+
+### Log Loop Progress
+
+```xs
+var $index { value = 0 }
+
+foreach ($items) {
+  each as $item {
+    var.update $index { value = $index + 1 }
+
+    conditional {
+      if ($index % 100 == 0) {
+        debug.log {
+          value = "Processed " ~ $index ~ " of " ~ ($items|count)
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Production Debugging
+
+### Structured Logging
+
+```xs
+db.add log_entry {
+  data = {
+    level: "error",
+    context: "payment_processing",
+    message: $error.message,
+    data: {
+      order_id: $order.id,
+      amount: $order.total,
+      user_id: $auth.id
+    },
+    request: {
+      method: $env.$request_method,
+      uri: $env.$request_uri,
+      ip: $env.$remote_ip
+    },
+    created_at: now
+  }
+}
+```
+
+### Error Reporting
+
+```xs
+try_catch {
+  try {
+    // Operation
+  }
+  catch {
+    // Log to database
+    db.add error_log {
+      data = {
+        error_name: $error.name,
+        error_message: $error.message,
+        error_code: $error.code,
+        stack_trace: $error.stack,
+        context: "api_endpoint",
+        user_id: $auth.id,
+        request_data: $input|json_encode,
+        created_at: now
+      }
+    }
+
+    // Alert if critical
+    conditional {
+      if ($error.code >= 500) {
+        util.send_email {
+          to = $env.ADMIN_EMAIL
+          subject = "Critical Error: " ~ $error.name
+          body = $error.message
+        }
+      }
+    }
+
+    // Rethrow
+    throw {
+      name = $error.name
+      value = $error.message
+      code = $error.code
+    }
+  }
+}
+```
+
+---
+
+## Disable in Production
+
+### Mock Debug Functions
+
+```xs
+// Wrapper that respects environment
+conditional {
+  if ($env.ENVIRONMENT != "production") {
+    debug.log { value = $debug_info }
+  }
+}
+```
+
+### Using Disabled Flag
+
+```xs
+debug.log {
+  disabled = $env.ENVIRONMENT == "production"
+  value = $sensitive_debug_info
+}
+```