> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Utility Functions
## Return
```javascript theme={null}
return {
value = "value to return"
}
```
| Parameter | Purpose | Example |
| --------- | ------------------------------------- | ---------------------------------------- |
| value | The value to return from the function | `"Hello World"`, `123`, `{key: "value"}` |
```javascript theme={null}
return {
value = $api_response|get:"data"
}
```
* Returns a value from the function execution
* Can return any data type (string, number, object, array, etc.)
* Terminates function execution
## Debug Log
```javascript theme={null}
debug.log {
value = "Value to send"
}
```
| Parameter | Purpose | Example |
| --------- | ------------------------------------ | ------------------------------------------ |
| value | The value to output to the debug log | `"Debug message"`, `$variable`, \`response |
```javascript theme={null}
debug.log {
value = "Processing user: "|add:$user.id
}
```
* Outputs a value to the debug log
* Useful for development and troubleshooting
* Can log any data type
* Does not affect function execution
## Precondition
```javascript theme={null}
precondition ($a == 1) {
error_type = "notfound"
error = "Error message to return"
payload = "Payload"
}
```
| Parameter | Purpose | Example |
| ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| error\_type | The type of error to throw | Can be one of the following:
- standard
- notfound
- accessdenied
- toomamyrequests
- unauthorized
- badrequest
- inputerror
|
| error | The error message to display | `"Resource not found"`, `"Access denied"` |
| payload | Additional data to include with the error | `"Error details"`, `{reason: "Invalid input"}` |
```javascript theme={null}
precondition ($user.role != "admin") {
error_type = "accessdenied"
error = "Admin access required"
payload = {
required_role: "admin",
current_role: $user.role
}
}
```
## Try / Catch
```javascript theme={null}
try_catch {
try {
// statements that may throw
function.run risky_function { input = { foo: "bar" } } as $result
}
catch {
debug.log { value = $error }
}
finally {
debug.log { value = "Cleanup actions" }
}
}
```
* Executes code in the `try` block
* If an error occurs, the `catch` block runs
* The `finally` block always runs (optional)
## Throw Error
```javascript theme={null}
throw {
name = "inputerror"
value = "A custom error message"
}
```
* Immediately stops execution and throws an error
* Can be caught by a surrounding `try_catch` block
## Post Process
```javascript theme={null}
post_process {
stack {
debug.log { value = "Post-processing after response" }
}
}
```
* Executes after the main response is sent
* Useful for logging, cleanup, or async side effects
## Send Email
```javascript theme={null}
api.request {
url = "https://api.sendgrid.com/v3/mail/send"
method = "POST"
params = {
personalizations: [{ to: [{ email: "to@example.com" }] }],
from: { email: "from@example.com" },
subject: "Hello from XanoScript",
content: [{ type: "text/plain", value: "This is the email body." }]
}
headers = []|push:"Authorization: Bearer " ~ $env.sendgrid_key
} as $email_response
```
* Use `api.request` to send emails via external providers (e.g., SendGrid, Mailgun)
* Set API keys in environment variables
* Check `$email_response` for status
* Checks a condition and throws an error if the condition is true
* Allows specifying error type, message, and additional payload
* Useful for validation and access control
* Stops execution if condition is met
## Stop and Debug
```javascript theme={null}
debug.stop {
value = "Value to return"
}
```
| Parameter | Purpose | Example |
| --------- | ------------------------------------------- | ---------------------------------------------------------- |
| value | The value to return when stopping execution | `"Debug stop message"`, `$variable`, `{status: "stopped"}` |
```javascript theme={null}
debug.stop {
value = "Stopping execution"
}
```
* Immediately stops function execution
* Returns the specified value
* Useful for debugging and development
* Can return any data type
## Group
```javascript theme={null}
group {
stack {
util.sleep {
value = 1
}
util.sleep {
value = 2
}
}
}
```
| Parameter | Purpose | Example |
| --------- | ----------------------------------- | --------------- |
| group | Container for organizing operations | `group { ... }` |
| stack | Executes operations in sequence | `stack { ... }` |
| value | Duration to sleep in seconds | `1`, `2`, `0.5` |
```javascript theme={null}
group {
stack {
util.sleep {
value = 0.5
}
debug.log {
value = "Half second passed"
}
util.sleep {
value = 1
}
}
}
```
* Groups related operations together
* Stack ensures sequential execution
* Sleep pauses execution for specified duration
* Operations in stack execute in order
## Sleep
```javascript theme={null}
util.sleep {
value = 1
}
```
| Parameter | Purpose | Example |
| --------- | ------------------------------------ | ----------------- |
| value | Number of seconds to pause execution | `1`, `0.5`, `2.5` |
```javascript theme={null}
util.sleep {
value = 0.5
}
```
* Pauses execution for specified number of seconds
* Accepts decimal values for sub-second precision
* Useful for rate limiting or creating delays
## CSV Stream
```javascript theme={null}
stream.from_csv {
value = $input.csv_input
separator = ","
enclosure = '"'
escape_char = '"'
} as csv_stream
```
| Parameter | Purpose | Example |
| ------------ | ------------------------------------------- | ----------------------------------- |
| value | Input CSV data source | `$input.csv_input`, `$file.content` |
| separator | Character used to separate fields | `","`, `";"`, `"\t"` |
| enclosure | Character used to enclose fields | `'"'`, `"'"` |
| escape\_char | Character used to escape special characters | `'"'`, `"\"` |
| as | Alias to reference the stream | `csv_stream` |
```javascript theme={null}
stream.from_csv {
value = $input.users_data
separator = ","
enclosure = '"'
escape_char = '"'
} as users_stream
```
* Creates a stream from CSV formatted data
* Configurable field separator, enclosure, and escape characters
* Assigns stream to an alias for later reference
* Useful for processing large CSV files
## JSONL Stream
```javascript theme={null}
stream.from_jsonl {
value = $input.JSONL_file
} as jsonl_stream
```
| Parameter | Purpose | Example |
| --------- | ----------------------------- | ------------------------------------ |
| value | Input JSONL data source | `$input.JSONL_file`, `$file.content` |
| as | Alias to reference the stream | `jsonl_stream` |
```javascript theme={null}
stream.from_jsonl {
value = $input.log_entries
} as logs_stream
```
* Creates a stream from JSON Lines formatted data
* Each line must be a valid JSON object
* Assigns stream to an alias for later reference
* Useful for processing large datasets line by line
## Set HTTP Header
```javascript theme={null}
util.set_header {
value = "HTTP 1.1 200 OK"
duplicates = "replace"
}
```
| Parameter | Purpose | Example |
| ---------- | ------------------------------- | ------------------------------------------------------- |
| value | HTTP header value to set | `"HTTP 1.1 200 OK"`, `"Content-Type: application/json"` |
| duplicates | How to handle duplicate headers | `"replace"`, `"append"` |
```javascript theme={null}
util.set_header {
value = "Content-Type: application/json"
duplicates = "replace"
}
```
* Sets HTTP response headers
* Controls how duplicate headers are handled
* Useful for customizing API responses
* Common for setting content types, status codes, and custom headers
## Get All Variables
```javascript theme={null}
util.get_vars as all_variables
```
| Parameter | Purpose | Example |
| --------- | ---------------------------------------------- | ----------------------- |
| as | New variable to contain the returned variables | `all_variables`, `vars` |
```javascript theme={null}
util.get_vars as system_vars
debug.log {
value = $system_vars
}
```
* Returns an object containing all variables
## Get All Inputs
```javascript theme={null}
util.get_all_input as all_input
```
| Parameter | Purpose | Example |
| --------- | --------------------------------- | --------------------------- |
| as | Alias to reference the input data | `all_input`, `request_data` |
```javascript theme={null}
util.get_all_input as request_data
debug.log {
value = request_data
}
```
* Retrieves all input data from the current request as defined in the inputs section
## Get All Raw Input
```javascript theme={null}
util.get_input {
encoding = "json"
exclude_middleware = false
} as all_raw_input
```
| Parameter | Purpose | Example |
| ------------------- | ----------------------------------------------------------- | ------------------------------- |
| encoding | Format of the input data | `"json"`, `"raw"`, `"text"` |
| exclude\_middleware | Whether or not to allow middleware to affect the raw inputs | `true, false` |
| as | Alias to reference the input | `all_raw_input`, `request_body` |
```javascript theme={null}
util.get_raw_input {
encoding = "json"
exclude_middleware = false
} as request_body
```
* Retrieves raw input data from the request
## Get Environment Variables
```javascript theme={null}
util.get_env as all_env_vars
```
| Parameter | Purpose | Example |
| --------- | -------------------------------------------- | --------------------- |
| as | Alias to reference the environment variables | `all_env_vars`, `env` |
```javascript theme={null}
util.get_env as env
```
* Returns an object containing all environment variables
## Calculate Distance
```javascript theme={null}
util.geo_distance {
latitude_1 = 37.7749
longitude_1 = 122.4194
latitude_2 = 35.6762
longitude_2 = 139.6503
} as distance
```
| Parameter | Purpose | Example |
| ------------ | ------------------------------------------ | -------------------------- |
| latitude\_1 | Latitude of first point | `37.7749`, `-33.8688` |
| longitude\_1 | Longitude of first point | `122.4194`, `151.2093` |
| latitude\_2 | Latitude of second point | `35.6762`, `51.5074` |
| longitude\_2 | Longitude of second point | `139.6503`, `-0.1278` |
| as | Alias to reference the calculated distance | `distance`, `route_length` |
```javascript theme={null}
util.geo_distance {
latitude_1 = $location1|get:"lat"
longitude_1 = $location1|get:"lng"
latitude_2 = $location2|get:"lat"
longitude_2 = $location2|get:"lng"
} as route_distance
```
* Calculates the distance (straight line) between two geographic coordinates
## IP Address Lookup
```javascript theme={null}
util.ip_lookup {
value = "1.1.1.1"
} as ip_location
```
| Parameter | Purpose | Example |
| --------- | ------------------------------------- | ------------------------------------------- |
| value | IP address to look up | `"1.1.1.1"`, `"192.168.1.1"`, `$request.ip` |
| as | Alias to reference the lookup results | `ip_location`, `visitor_location` |
```javascript theme={null}
util.ip_lookup {
value = $request|get:"ip"
} as visitor_info
```
* Performs geolocation lookup for an IP address
## Set Data Source
```javascript theme={null}
db.set_datasource {
value = "test"
}
```
| Parameter | Purpose | Example |
| --------- | ----------------------------- | ------------------------------------- |
| value | Name of the datasource to use | `"test"`, `"production"`, `"staging"` |
```javascript theme={null}
db.set_datasource {
value = "staging"
}
```
* Sets the active database datasource
## Async Await
```javascript theme={null}
await {
ids = []
timeout = 10
} as async_returns
```
| Parameter | Purpose | Example |
| --------- | ---------------------------------------- | -------------------------------------------- |
| ids | Array of async operation IDs to wait for | `[]`, `["task1", "task2"]`, `$pending_tasks` |
| timeout | Maximum time to wait in seconds | `10`, `30`, `60` |
| as | Alias to reference the results | `async_returns`, `task_results` |
```javascript theme={null}
await {
ids = ["process1", "process2"]
timeout = 30
} as operation_results
```
* Waits for completion of asynchronous operations
* Specifies maximum wait time
* Collects results from multiple async operations
* Returns results when all operations complete or timeout is reached