@xano/developer-mcp 1.0.21 → 1.0.22

package/dist/xanoscript_docs_auto/types.md

@@ -0,0 +1,323 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Data Types
+
+XanoScript supports a rich type system for defining inputs, variables, and database columns.
+
+## Quick Reference
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | String data | `"hello world"` |
+| `email` | Email address format | `"user@example.com"` |
+| `password` | Password field (sensitive) | (user input) |
+| `int` | Integer number | `42`, `-5` |
+| `decimal` | Floating-point number | `3.14`, `99.99` |
+| `bool` | Boolean value | `true`, `false` |
+| `date` | Date value | `2025-01-15` |
+| `time` | Time value | `14:30:00` |
+| `timestamp` | Date and time | `2025-01-15 14:30:00+0000` |
+| `json` | JSON object/array | `{name: "John"}` |
+| `file` | File resource | (uploaded file) |
+| `uuid` | UUID identifier | (auto-generated) |
+| `array` | Array of values | `[1, 2, 3]` |
+| `object` | Key-value object | `{key: value}` |
+
+---
+
+## Input Block Types
+
+Define input parameters with types and validation:
+
+```xs
+input {
+  text name filters=trim|min:1|max:100
+  email user_email filters=trim|lower
+  int age filters=min:0|max:150
+  decimal price filters=min:0
+  bool is_active
+  timestamp created_at
+  json metadata
+  file avatar
+  array tags
+  object preferences
+}
+```
+
+### Optional Parameters
+
+Add `?` after type name for optional fields:
+
+```xs
+input {
+  text name                    // Required
+  text? nickname               // Optional
+  int? age                     // Optional integer
+}
+```
+
+### Default Values
+
+```xs
+input {
+  int page default=1
+  int per_page default=20
+  text sort default="created_at"
+  bool ascending default=true
+}
+```
+
+### Array Types
+
+Specify array element types:
+
+```xs
+input {
+  array<text> tags            // Array of strings
+  array<int> ids              // Array of integers
+  array<object> items         // Array of objects
+}
+```
+
+---
+
+## Input Validation Filters
+
+Apply filters to validate and transform input:
+
+### Validation Filters
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `min:<value>` | Minimum value/length | `min:1` |
+| `max:<value>` | Maximum value/length | `max:100` |
+| `startsWith:<prefix>` | Must start with prefix | `startsWith:SKU-` |
+| `pattern:<regex>` | Regex pattern match | `pattern:^[A-Z]+$` |
+| `pattern:<regex>:<error>` | Regex with custom error | `pattern:^\\d{5}$:Invalid ZIP` |
+| `prevent:<phrase>` | Blacklist phrase | `prevent:spam` |
+| `ok:<chars>` | Whitelist characters | `ok:abc123` |
+| `alphaOk` | Only alphabetic characters | `alphaOk` |
+| `digitOk` | Only numeric characters | `digitOk` |
+| `minAlpha:<count>` | Minimum alphabetic chars | `minAlpha:2` |
+| `minDigit:<count>` | Minimum digits | `minDigit:1` |
+| `minSpecial:<count>` | Minimum special chars | `minSpecial:1` |
+
+### Transformation Filters
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `trim` | Remove whitespace | `trim` |
+| `lower` | Convert to lowercase | `lower` |
+| `upper` | Convert to uppercase | `upper` |
+| `ltrim` | Remove left whitespace | `ltrim` |
+| `rtrim` | Remove right whitespace | `rtrim` |
+
+### Chaining Filters
+
+```xs
+input {
+  text email filters=trim|lower
+  text username filters=trim|min:3|max:20|alphaOk
+  password pwd filters=min:8|minAlpha:1|minDigit:1|minSpecial:1
+}
+```
+
+---
+
+## Type Conversion Filters
+
+Convert between types at runtime:
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `to_int` | Convert to integer | `"123"\|to_int` |
+| `to_decimal` | Convert to decimal | `"1.5"\|to_decimal` |
+| `to_text` | Convert to string | `123\|to_text` |
+| `to_bool` | Convert to boolean | `"true"\|to_bool` |
+| `to_timestamp` | Parse to timestamp | `"now"\|to_timestamp` |
+| `to_ms` | Milliseconds since epoch | `"now"\|to_ms` |
+| `to_seconds` | Seconds since epoch | `"now"\|to_seconds` |
+
+---
+
+## Type Checking Filters
+
+Test value types:
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `is_null` | `null\|is_null` | `true` |
+| `is_empty` | `[]\|is_empty` | `true` |
+| `is_array` | `[1]\|is_array` | `true` |
+| `is_object` | `{}\|is_object` | `true` |
+| `is_int` | `1\|is_int` | `true` |
+| `is_text` | `"a"\|is_text` | `true` |
+| `is_decimal` | `1.5\|is_decimal` | `true` |
+| `is_bool` | `true\|is_bool` | `true` |
+
+---
+
+## JSON Type
+
+The `json` type accepts objects and arrays:
+
+```xs
+input {
+  json settings                // Any JSON value
+}
+
+// Access nested properties
+var $theme { value = $input.settings.theme }
+var $colors { value = $input.settings.colors|first }
+```
+
+### JSON Operations
+
+```xs
+// Encode/decode
+$obj|json_encode               // Object to JSON string
+$str|json_decode               // JSON string to object
+
+// Property access
+$obj|get:"key"                 // Get property
+$obj|set:"key":"value"         // Set property
+$obj|unset:"key"               // Remove property
+$obj|has:"key"                 // Check property exists
+
+// Object manipulation
+$obj|keys                      // Get all keys
+$obj|values                    // Get all values
+$obj|entries                   // Get key-value pairs
+$obj|pick:["a","b"]            // Keep only specified keys
+$obj|unpick:["c"]              // Remove specified keys
+```
+
+---
+
+## File Type
+
+Handle file uploads and resources:
+
+```xs
+input {
+  file avatar                  // File upload
+  file? document               // Optional file
+}
+
+// File properties
+$input.avatar.name             // Original filename
+$input.avatar.mime             // MIME type
+$input.avatar.size             // Size in bytes
+$input.avatar.path             // Storage path
+```
+
+### File Operations
+
+```xs
+// Create file resource
+storage.create_file_resource {
+  name = "document.pdf"
+  content = $file_content
+} as $file
+
+// Read file
+storage.read_file_resource {
+  path = $input.file.path
+} as $content
+
+// Delete file
+storage.delete_file {
+  path = $file_path
+}
+
+// Image with metadata
+storage.create_image {
+  name = "photo.jpg"
+  content = $image_data
+} as $image
+```
+
+---
+
+## Timestamp Type
+
+Date and time handling:
+
+```xs
+input {
+  timestamp start_date
+  timestamp? end_date
+  date birth_date
+  time meeting_time
+}
+```
+
+### Timestamp Formats
+
+```xs
+// Current time
+now                            // Current timestamp
+
+// Format timestamp
+$ts|format_timestamp:"Y-m-d":"UTC"
+$ts|format_timestamp:"Y-m-d H:i:s":"America/New_York"
+
+// Transform timestamp
+$ts|transform_timestamp:"-7 days"
+$ts|transform_timestamp:"+1 month"
+$ts|add_secs_to_timestamp:3600
+
+// Extract parts
+$ts|timestamp_year             // Year
+$ts|timestamp_month            // Month (1-12)
+$ts|timestamp_day_of_month     // Day (1-31)
+$ts|timestamp_hour             // Hour (0-23)
+$ts|timestamp_minute           // Minute (0-59)
+$ts|timestamp_day_of_week      // Day (0=Sunday)
+```
+
+---
+
+## Array Type
+
+Arrays with element type specification:
+
+```xs
+input {
+  array items                  // Generic array
+  array<text> tags             // String array
+  array<int> scores            // Integer array
+  array<object> products       // Object array
+}
+```
+
+### Array Operations
+
+```xs
+// Access elements
+$arr|first                     // First element
+$arr|last                      // Last element
+$arr|count                     // Length
+$arr|slice:1:3                 // Elements 1-3
+
+// Modify arrays
+$arr|push:$item                // Add to end
+$arr|unshift:$item             // Add to start
+$arr|pop                       // Remove from end
+$arr|shift                     // Remove from start
+$arr|merge:$other              // Combine arrays
+$arr|unique                    // Remove duplicates
+$arr|reverse                   // Reverse order
+$arr|shuffle                   // Random order
+
+// Functional operations
+$arr|map:$$.value              // Transform elements
+$arr|filter:$$.active          // Filter elements
+$arr|find:$$.id==1             // Find first match
+$arr|findIndex:$$.id==1        // Find index
+$arr|some:$$.valid             // Any match?
+$arr|every:$$.valid            // All match?
+$arr|reduce:$$+$result:0       // Reduce to value
+```