@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/xanoscript_docs_auto/filters.md

@@ -0,0 +1,464 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Filters Reference
+
+Complete reference for all pipe filters in XanoScript.
+
+## Quick Reference
+
+| Category | Filters |
+|----------|---------|
+| String | `trim`, `lower`, `upper`, `strlen`, `substr`, `split`, `replace` |
+| Array | `first`, `last`, `count`, `map`, `filter`, `find`, `reduce` |
+| Object | `get`, `set`, `unset`, `has`, `keys`, `values`, `entries` |
+| Math | `add`, `subtract`, `floor`, `ceil`, `round`, `abs` |
+| Type | `to_int`, `to_text`, `is_null`, `is_array`, `is_object` |
+| Date | `format_timestamp`, `transform_timestamp`, `timestamp_year` |
+| Encoding | `json_encode`, `base64_encode`, `url_encode` |
+| Security | `md5`, `sha256`, `encrypt`, `decrypt` |
+
+---
+
+## String Filters
+
+### Basic String Operations
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `trim` | `"  hi  "\|trim` | `"hi"` |
+| `ltrim` | `"  hi"\|ltrim` | `"hi"` |
+| `rtrim` | `"hi  "\|rtrim` | `"hi"` |
+| `to_lower` | `"Hello"\|to_lower` | `"hello"` |
+| `to_upper` | `"Hello"\|to_upper` | `"HELLO"` |
+| `capitalize` | `"hello world"\|capitalize` | `"Hello World"` |
+| `strlen` | `"hello"\|strlen` | `5` |
+
+### Substring Operations
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `substr` | `"hello"\|substr:1:3` | `"ell"` |
+| `split` | `"a,b,c"\|split:","` | `["a","b","c"]` |
+| `replace` | `"hello"\|replace:"l":"x"` | `"hexxo"` |
+| `concat` | `"a"\|concat:"b":"-"` | `"a-b"` |
+
+### String Checks
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `contains` | `"hello"\|contains:"ell"` | `true` |
+| `starts_with` | `"hello"\|starts_with:"he"` | `true` |
+| `ends_with` | `"hello"\|ends_with:"lo"` | `true` |
+| `icontains` | `"Hello"\|icontains:"ELL"` | `true` |
+| `istarts_with` | `"Hello"\|istarts_with:"HE"` | `true` |
+| `iends_with` | `"Hello"\|iends_with:"LO"` | `true` |
+
+### Regex Operations
+
+```xs
+// Check if matches
+"/pattern/"|regex_matches:"subject"
+
+// Get first match
+"/(\w+)/"|regex_get_first_match:"hello world"   // "hello"
+
+// Get all matches
+"/\w+/"|regex_get_all_matches:"hello world"     // ["hello", "world"]
+
+// Replace with regex
+"/\s+/"|regex_replace:"-":"hello  world"        // "hello-world"
+```
+
+### String Escaping
+
+| Filter | Description |
+|--------|-------------|
+| `addslashes` | Escape quotes and backslashes |
+| `escape` | HTML escape |
+| `text_escape` | Escape for text output |
+| `regex_quote` | Escape regex special characters |
+
+---
+
+## Array Filters
+
+### Array Access
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `first` | `[1,2,3]\|first` | `1` |
+| `last` | `[1,2,3]\|last` | `3` |
+| `count` | `[1,2,3]\|count` | `3` |
+| `slice` | `[1,2,3,4]\|slice:1:2` | `[2,3]` |
+
+### Array Modification
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `push` | `[1,2]\|push:3` | `[1,2,3]` |
+| `pop` | `[1,2,3]\|pop` | `3` |
+| `unshift` | `[1,2]\|unshift:0` | `[0,1,2]` |
+| `shift` | `[1,2,3]\|shift` | `1` |
+| `reverse` | `[1,2,3]\|reverse` | `[3,2,1]` |
+| `unique` | `[1,1,2,2]\|unique` | `[1,2]` |
+| `flatten` | `[[1,2],[3]]\|flatten` | `[1,2,3]` |
+| `shuffle` | `[1,2,3]\|shuffle` | Random order |
+
+### Array Combining
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `merge` | `[1,2]\|merge:[3,4]` | `[1,2,3,4]` |
+| `diff` | `[1,2,3]\|diff:[2]` | `[1,3]` |
+| `intersect` | `[1,2,3]\|intersect:[2,3,4]` | `[2,3]` |
+| `join` | `["a","b"]\|join:","` | `"a,b"` |
+
+### Functional Array Operations
+
+```xs
+// Map - transform each element
+[1,2,3]|map:$$*2                              // [2,4,6]
+[{v:1},{v:2}]|map:$$.v                         // [1,2]
+
+// Filter - keep matching elements
+[1,2,3,4]|filter:$$>2                          // [3,4]
+[1,2,3,4]|filter:$$%2==0                       // [2,4]
+
+// Find - first matching element
+[{id:1},{id:2}]|find:$$.id==2                  // {id:2}
+
+// FindIndex - index of first match
+[{id:1},{id:2}]|findIndex:$$.id==2             // 1
+
+// Some - any element matches?
+[1,2,3]|some:$$>2                              // true
+
+// Every - all elements match?
+[2,4,6]|every:$$%2==0                          // true
+
+// Reduce - accumulate to single value
+[1,2,3,4]|reduce:$$+$result:0                  // 10
+```
+
+### Array Grouping
+
+```xs
+// Group by property
+[{g:"a",v:1},{g:"b",v:2},{g:"a",v:3}]|index_by:g
+// {"a":[{g:"a",v:1},{g:"a",v:3}],"b":[{g:"b",v:2}]}
+
+// Sort
+[{n:"z"},{n:"a"}]|sort:n:text:false            // Ascending
+[{n:"z"},{n:"a"}]|sort:n:text:true             // Descending
+```
+
+### Array Filtering by Type
+
+| Filter | Description |
+|--------|-------------|
+| `filter_empty` | Remove empty values |
+| `filter_empty_text` | Remove empty strings |
+| `filter_empty_array` | Remove empty arrays |
+| `filter_empty_object` | Remove empty objects |
+| `filter_null` | Remove null values |
+| `filter_zero` | Remove zero values |
+| `filter_false` | Remove false values |
+
+---
+
+## Object Filters
+
+### Property Access
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `get` | `{a:1}\|get:"a"` | `1` |
+| `set` | `{a:1}\|set:"b":2` | `{a:1,b:2}` |
+| `unset` | `{a:1,b:2}\|unset:"b"` | `{a:1}` |
+| `has` | `{a:1}\|has:"a"` | `true` |
+
+### Object Transformation
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `keys` | `{a:1,b:2}\|keys` | `["a","b"]` |
+| `values` | `{a:1,b:2}\|values` | `[1,2]` |
+| `entries` | `{a:1}\|entries` | `[{key:"a",value:1}]` |
+| `pick` | `{a:1,b:2,c:3}\|pick:["a","c"]` | `{a:1,c:3}` |
+| `unpick` | `{a:1,b:2,c:3}\|unpick:["b"]` | `{a:1,c:3}` |
+
+### Conditional Set
+
+```xs
+{a:1}|set_conditional:"b":2:true             // {a:1,b:2} if condition true
+{a:1}|set_ifnotempty:"b":"val"               // Set only if val not empty
+{a:1}|set_ifnotnull:"b":$var                 // Set only if $var not null
+```
+
+---
+
+## Math Filters
+
+### Basic Math
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `add` | `10\|add:5` | `15` |
+| `subtract` | `10\|subtract:3` | `7` |
+| `multiply` | `10\|multiply:2` | `20` |
+| `divide` | `10\|divide:2` | `5` |
+| `modulus` | `10\|modulus:3` | `1` |
+
+### Rounding
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `floor` | `2.7\|floor` | `2` |
+| `ceil` | `2.3\|ceil` | `3` |
+| `round` | `2.567\|round:2` | `2.57` |
+| `abs` | `-5\|abs` | `5` |
+
+### Advanced Math
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `sqrt` | `9\|sqrt` | `3` |
+| `pow` | `2\|pow:3` | `8` |
+| `min` | `5\|min:3` | `3` |
+| `max` | `5\|max:10` | `10` |
+
+### Array Math
+
+```xs
+[1,2,3,4]|sum         // 10
+[1,2,3,4]|avg         // 2.5
+[1,2,3,4]|product     // 24
+[5,2,8,1]|array_min   // 1
+[5,2,8,1]|array_max   // 8
+```
+
+### Trigonometry
+
+`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `deg2rad`, `rad2deg`, `sinh`, `cosh`, `tanh`
+
+---
+
+## Type Filters
+
+### Type Conversion
+
+| Filter | Example | Result |
+|--------|---------|--------|
+| `to_int` | `"123"\|to_int` | `123` |
+| `to_decimal` | `"1.5"\|to_decimal` | `1.5` |
+| `to_text` | `123\|to_text` | `"123"` |
+| `to_bool` | `"true"\|to_bool` | `true` |
+
+### Type Checking
+
+| 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` |
+
+### Null Handling
+
+```xs
+null|first_notnull:0                          // 0
+""|first_notempty:"default"                   // "default"
+```
+
+---
+
+## Date/Time Filters
+
+### Timestamp Parsing
+
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `to_timestamp` | `"now"\|to_timestamp` | Parse to timestamp |
+| `to_ms` | `"now"\|to_ms` | Milliseconds since epoch |
+| `to_seconds` | `"now"\|to_seconds` | Seconds since epoch |
+
+### Timestamp Formatting
+
+```xs
+$ts|format_timestamp:"Y-m-d":"UTC"
+$ts|format_timestamp:"Y-m-d H:i:s":"America/New_York"
+$ts|format_timestamp:"F j, Y":"UTC"             // "January 15, 2025"
+```
+
+### Timestamp Manipulation
+
+```xs
+$ts|transform_timestamp:"-7 days"
+$ts|transform_timestamp:"+1 month"
+$ts|transform_timestamp:"+2 hours"
+$ts|add_secs_to_timestamp:3600                  // Add 1 hour
+$ts|add_ms_to_timestamp:1000                    // Add 1 second
+```
+
+### Timestamp Parts
+
+| Filter | Returns |
+|--------|---------|
+| `timestamp_year` | Year (e.g., 2025) |
+| `timestamp_month` | Month (1-12) |
+| `timestamp_day_of_month` | Day (1-31) |
+| `timestamp_hour` | Hour (0-23) |
+| `timestamp_minute` | Minute (0-59) |
+| `timestamp_day_of_week` | Day (0=Sunday) |
+| `timestamp_week` | Week number |
+| `timestamp_day_of_year` | Day of year (1-366) |
+
+---
+
+## Encoding Filters
+
+### JSON
+
+```xs
+{a:1}|json_encode                             // '{"a":1}'
+'{"a":1}'|json_decode                         // {a:1}
+```
+
+### Base64
+
+```xs
+"hello"|base64_encode                         // "aGVsbG8="
+"aGVsbG8="|base64_decode                      // "hello"
+```
+
+### URL
+
+```xs
+"hello world"|url_encode                      // "hello%20world"
+"hello%20world"|url_decode                    // "hello world"
+```
+
+### Other
+
+| Filter | Description |
+|--------|-------------|
+| `xml_decode` | Parse XML to object |
+| `yaml_encode` | Object to YAML |
+| `yaml_decode` | YAML to object |
+| `hex2bin` | Hex string to binary |
+| `bin2hex` | Binary to hex string |
+| `csv_parse` | Parse CSV string |
+| `csv_create` | Create CSV string |
+| `querystring_parse` | Parse query string |
+
+---
+
+## Security Filters
+
+### Hashing
+
+| Filter | Description |
+|--------|-------------|
+| `md5` | MD5 hash |
+| `sha1` | SHA-1 hash |
+| `sha256` | SHA-256 hash |
+| `sha512` | SHA-512 hash |
+| `hmac_sha256` | HMAC-SHA256 |
+
+### Encryption
+
+```xs
+"data"|encrypt:"aes-256-cbc":"key":"iv"
+$encrypted|decrypt:"aes-256-cbc":"key":"iv"
+```
+
+### JWT
+
+```xs
+$payload|jws_encode:"HS256":"secret"           // Sign
+$token|jws_decode:"secret"                     // Verify and decode
+
+$payload|jwe_encode:"A256GCM":"key"            // Encrypt
+$token|jwe_decode:"key"                        // Decrypt
+```
+
+### ID Obfuscation
+
+```xs
+123|secureid_encode                            // Obfuscated ID
+"obfuscated"|secureid_decode                   // Original ID
+```
+
+### UUID Generation
+
+```xs
+|uuid                                          // Generate UUID
+```
+
+---
+
+## Database Query Filters
+
+Special filters for `db.query` where clauses:
+
+### String Operations
+
+```xs
+$db.user.name|to_lower == $input.name|to_lower
+$db.product.sku|substr:0:3 == "SKU"
+$db.name|unaccent ilike $input.search
+```
+
+### Array Operations
+
+```xs
+$db.tags|contains:"featured"
+$db.categories|overlaps:["a","b"]
+$db.items|length >= 3
+```
+
+### Vector Operations (AI/ML)
+
+```xs
+$db.embedding|cosine_similarity:$vec
+$db.embedding|l2_distance_euclidean:$vec
+$db.embedding|inner_product:$vec
+$db.embedding|l1_distance_manhattan:$vec
+```
+
+### Geo Operations
+
+```xs
+$db.location|distance:$point                   // Distance in meters
+$db.location|within:$point:5000                // Within 5km
+$db.boundary|covers:$point                     // Polygon contains point
+```
+
+### Timestamp Arithmetic
+
+```xs
+$db.created_at|timestamp_add_days:7
+$db.expires_at|timestamp_subtract_hours:24
+```
+
+---
+
+## Chaining Filters
+
+Combine multiple filters:
+
+```xs
+$input.email|trim|to_lower
+
+$input.text|trim|substr:0:100|replace:" ":"-"|to_lower
+
+$array|filter:$$.active|map:$$.name|join:", "
+
+$data|json_encode|base64_encode
+```