Utility Functions

Return

return {
  value = "value to return"
}

Parameter	Purpose	Example
value	The value to return from the function	`"Hello World"`, `123`, `{key: "value"}`

Example

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

debug.log {
  value = "Value to send"
}

Parameter	Purpose	Example
value	The value to output to the debug log	`"Debug message"`, `$variable`, `response

Example

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

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"}`

Example

precondition ($user.role != "admin") {
  error_type = "accessdenied"
  error = "Admin access required"
  payload = {
    required_role: "admin",
    current_role: $user.role
  }
}

Try / Catch

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

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

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

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

debug.stop {
  value = "Value to return"
}

Parameter	Purpose	Example
value	The value to return when stopping execution	`"Debug stop message"`, `$variable`, `{status: "stopped"}`

Example

debug.stop {
  value = "Stopping execution"
}

Immediately stops function execution
Returns the specified value
Useful for debugging and development
Can return any data type

Group

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`

Example

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

util.sleep {
  value = 1
}

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

Example

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

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`

Example

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

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`

Example

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

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"`

Example

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

util.get_vars as all_variables

Parameter	Purpose	Example
as	New variable to contain the returned variables	`all_variables`, `vars`

Example

util.get_vars as system_vars

debug.log {
  value = $system_vars
}

Returns an object containing all variables

Get All Inputs

util.get_all_input as all_input

Parameter	Purpose	Example
as	Alias to reference the input data	`all_input`, `request_data`

Example

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

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`

Example

util.get_raw_input {
  encoding = "json"
  exclude_middleware = false
} as request_body

Retrieves raw input data from the request

Get Environment Variables

util.get_env as all_env_vars

Parameter	Purpose	Example
as	Alias to reference the environment variables	`all_env_vars`, `env`

Example

util.get_env as env

Returns an object containing all environment variables

Calculate Distance

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`

Example

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

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`

Example

util.ip_lookup {
  value = $request|get:"ip"
} as visitor_info

Performs geolocation lookup for an IP address

Set Data Source

db.set_datasource {
  value = "test"
}

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

Example

db.set_datasource {
  value = "staging"
}

Sets the active database datasource

Async Await

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`

Example

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

Start

AI

References

Return

Debug Log

Precondition

Try / Catch

Throw Error

Post Process

Send Email

Stop and Debug

Group

Sleep

CSV Stream

JSONL Stream

Set HTTP Header

Get All Variables

Get All Inputs

Get All Raw Input

Get Environment Variables

Calculate Distance

IP Address Lookup

Set Data Source

Async Await

​ Return

​ Debug Log

​ Precondition

​ Try / Catch

​ Throw Error

​ Post Process

​ Send Email

​ Stop and Debug

​ Group

​ Sleep

​ CSV Stream

​ JSONL Stream

​ Set HTTP Header

​ Get All Variables

​ Get All Inputs

​ Get All Raw Input

​ Get Environment Variables

​ Calculate Distance

​ IP Address Lookup

​ Set Data Source

​ Async Await

Return

Debug Log

Precondition

Try / Catch

Throw Error

Post Process

Send Email

Stop and Debug

Group

Sleep

CSV Stream

JSONL Stream

Set HTTP Header

Get All Variables

Get All Inputs

Get All Raw Input

Get Environment Variables

Calculate Distance

IP Address Lookup

Set Data Source

Async Await