> ## 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

## &#x20;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"}` |

> [accordion] Example
>
> ```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

## &#x20;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 |

> [accordion] Example
>
> ```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

## &#x20;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"}` |

> [accordion] Example
>
> ```javascript theme={null}
> precondition ($user.role != "admin") {
>   error_type = "accessdenied"
>   error = "Admin access required"
>   payload = {
>     required_role: "admin",
>     current_role: $user.role
>   }
> }
> ```

## &#x20;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)

## &#x20;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

## &#x20;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

## &#x20;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

## &#x20;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"}` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```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

## &#x20;Sleep

```javascript theme={null}
util.sleep {
  value = 1
}
```

| Parameter | Purpose | Example |
| - | - | - |
| value | Number of seconds to pause execution | `1`, `0.5`, `2.5` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```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

## &#x20;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"` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```javascript theme={null}
> util.get_vars as system_vars
>
> debug.log {
>   value = $system_vars
> }
> ```
>
> * Returns an object containing all variables

## &#x20;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` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```javascript theme={null}
> util.get_raw_input {
>   encoding = "json"
>   exclude_middleware = false
> } as request_body
> ```
>
> * Retrieves raw input data from the request

## &#x20;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` |

> [accordion] Example
>
> ```javascript theme={null}
> util.get_env as env
> ```
>
> * Returns an object containing all environment variables
> * Each value is returned exactly as saved. `$env.NAME` removes whitespace from both ends of a value, so a PEM key read through it loses its final line break; see [Leading and trailing whitespace](https://docs.xano.com/building/logic/working-with-data/environment-variables.md#leading-and-trailing-whitespace)

## &#x20;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` |

> [accordion] Example
>
> ```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

## &#x20;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` |

> [accordion] Example
>
> ```javascript theme={null}
> util.ip_lookup {
>   value = $request|get:"ip"
> } as visitor_info
> ```
>
> * Performs geolocation lookup for an IP address

## &#x20;Set Data Source

```javascript theme={null}
db.set_datasource {
  value = "test"
}
```

| Parameter | Purpose | Example |
| - | - | - |
| value | Name of the datasource to use | `"test"`, `"production"`, `"staging"` |

> [accordion] Example
>
> ```javascript theme={null}
> db.set_datasource {
>   value = "staging"
> }
> ```
>
> * Sets the active database datasource

## &#x20;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` |

> [accordion] Example
>
> ```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


## Related topics

- [Utility Functions](https://docs.xano.com/the-function-stack/functions/utility-functions.md)
- [Resources & Library Usage](https://docs.xano.com/developer-mcp/resources.md)
- [Functions](https://docs.xano.com/building/logic/core-components/functions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.