docs RestermScript
Standard library
Built-in helpers for text, JSON, lists, time, crypto and more.
The standard library provides helpers for text, JSON, lists, time, crypto, and other request tasks. It is available as rts, and stdlib still works as a deprecated alias. The library does not allow file writes or network access.
Core helpers and every namespace (crypto, base64, url, time, json, headers, query, encoding, text, list, dict, math) are also available at the top level. A script can reuse any of these names, such as let json = 1, and rts.json still reaches the namespace.
Builtins and reserved words may be removed within a major version, but only after deprecation in a minor release. Removal happens no earlier than the next minor release. Until then, the builtin still works and the parser warns on each line that uses it (WARN line <n> in the status bar, with the full text in Explain). Release notes list each removal and its replacement. See Compatibility for the wider versioning policy.
Core helpers
Core helpers are the general functions, such as len, str, and append. Helpers for one kind of value, such as text.upper, live in that kind's namespace.
rts.fail(msg)stops evaluation and returns an error message.rts.len(x)returns the length of a string, list, or dict.rts.append(list, items...)returns a new list with the items added to the end. A null list counts as empty. An item that is a list is added as one item, soappend([], [1])is[[1]]. Uselist.concatto join two lists.rts.min(values...)returns the smallest value. Pass one list to compare its items, or two or more values to compare them with each other. An empty list or null gives null, somin(xs) ?? 0works. The values must be all numbers or all strings. Strings compare byte by byte, so ISO timestamps compare by time when they use the same time zone and the same number of digits.rts.max(values...)works likeminand returns the largest value.rts.contains(container, value)applies the same membership relation asvalue in container.rts.match(pattern, text)applies a regular expression to text and returns true when it matches. A null pattern is an error.rts.str(x)converts a value to a string, writing numbers, lists, and dicts asjson.stringifydoes, sostr(1000000)is"1000000".rts.num(x[, def])converts a value to a number, or returnsdefwhen conversion fails.rts.int(x[, def])converts a value to an integer, or returnsdefwhen conversion fails.rts.bool(x[, def])converts a value to a bool, or returnsdefwhen conversion fails.rts.typeof(x)returns the type name.rts.uuid()generates a UUID and requires random generation to be enabled.
Crypto helpers
rts.crypto.sha256(text)returns a hex-encoded SHA-256 digest.rts.crypto.hmacSha256(key, text)returns a hex-encoded HMAC-SHA256 digest.rts.crypto.sha512(text)returns a hex-encoded SHA-512 digest.rts.crypto.hmacSha512(key, text)returns a hex-encoded HMAC-SHA512 digest.
Encoding and URL helpers
rts.base64.encode(x)encodes a string to base64.rts.base64.decode(x)decodes a base64 string.rts.encoding.hex.encode(x)encodes a string to hex.rts.encoding.hex.decode(x)decodes a hex string.rts.encoding.base64url.encode(x)encodes a string to base64url (no padding).rts.encoding.base64url.decode(x)decodes a base64url string.rts.url.encode(x)percent-encodes a string for use in a URL.rts.url.decode(x)decodes a percent-encoded string.
Time helpers
rts.time.nowISO()returns the current time in ISO 8601 format.rts.time.nowUnix()returns the current time as unix seconds.rts.time.nowUnixString()returns the current time as a decimal unix seconds string.rts.time.nowUnixMs()returns the current time as unix milliseconds.rts.time.format(layout)formats the current time with the given layout string.rts.time.parse(layout, value)parses a time string and returns unix seconds (fractional).rts.time.formatUnix(ts, layout)formats a unix timestamp with the given layout.rts.time.addUnix(ts, secondsOrDuration)adds seconds (number) or a duration string to a unix timestamp.rts.time.duration(value)parses a duration string (includingdandw) and returns seconds.
JSON helpers
rts.json.file(path)reads and parses JSON using the request base directory (only when file access is enabled).rts.json.parse(text)parses a JSON string into RestermScript values.rts.json.stringify(value[, indent])converts a value to JSON text.indentcan be a string or a number (0-32).rts.json.get(value[, path])returns the value at a dot or[index]path in a dict or list (optional leading$) and returns null when missing. Negative indexes count from the end, soitems[-1]reads the last item. Quote a key that contains dots or spaces, as in$["display.name"]or['a b']. A null path or an invalid path such asitems[*]returns an error.rts.json.has(value, path)returns true when a value exists at the path. A null path is an error.rts.json.equal(a, b)returns true for matching JSON values, including the contents of lists and dicts.rts.json.diff(got, want)returns a list with one message per difference, or an empty list for equal values. Messages include the path:$.user.id: got 7, want 8,$.extra: unexpected true, or$.tags[1]: missing, want "b".
json.diff sorts dict keys and shows values as compact JSON without escaping < or &. It shows up to 120 bytes of each value, adding ... when truncated. Results contain up to 100 differences, followed by a count of the rest, such as and 3 more differences. Paths use the same syntax as json.get.
Both helpers reject functions, host objects, NaN, and infinite numbers. Each list or dict counts toward the step limit. To compare response bodies, pass response.json().
Text helpers
rts.text.lower(s)returns a lowercased string.rts.text.upper(s)returns an uppercased string.rts.text.trim(s)trims leading and trailing whitespace.rts.text.split(s, sep)splits a string into a list. A null separator is an error.rts.text.join(list, sep)joins list items with a separator (items may be strings, numbers, or bools).rts.text.replace(s, old, new)replaces all occurrences of the substringoldwithnew. A null substring is an error.rts.text.startsWith(s, prefix)returns true when a string starts withprefix. A null prefix is an error.rts.text.endsWith(s, suffix)returns true when a string ends withsuffix. A null suffix is an error.
List helpers
rts.list.append(list, items...)works likeappend.rts.list.concat(a, b)returns a new list withbappended toa.rts.list.sort(list)returns a sorted copy (numbers or strings only).rts.list.map(list, fn)returns a new list withfn(item)applied to each value.rts.list.filter(list, fn)returns a new list of values wherefn(item)is truthy.rts.list.any(list, fn)returns true if any value makesfn(item)truthy.rts.list.all(list, fn)returns true if all values makefn(item)truthy.rts.list.slice(list, start[, end])returns a slice of the list.rts.list.unique(list)returns a list of unique primitive values.
Dict helpers
rts.dict.keys(dict)returns a sorted list of keys.rts.dict.values(dict)returns values ordered by sorted keys.rts.dict.items(dict)returns a list of{key, value}entries ordered by key.rts.dict.set(dict, key, value)returns a new dict withkeyset.rts.dict.merge(a, b)returns a new dict withbapplied overa.rts.dict.remove(dict, key)returns a new dict withoutkey.rts.dict.get(dict, key[, def])returnsdefor null when missing.rts.dict.has(dict, key)returns true when a key exists.rts.dict.pick(dict, keys)returns a dict with the specified keys.rts.dict.omit(dict, keys)returns a dict without the specified keys.
These helpers use keys exactly as written, like dict[key]. See Keys and names.
Header and query helpers
headers.get(h, name)returns the first value of a header, or null when it is missing.headers.has(h, name)returns true when a header carries a value.headers.set(h, name, value)returns a new dict with a string orlist<string>set, replacing the header regardless of name casing.headers.remove(h, name)returns a new dict without the header, regardless of name casing.headers.merge(a, b)returns a new dict withbapplied overa. A null value inbremoves that header.headers.normalize(h)returns a new dict with the names lowercased.query.parse(rawQuery)parses raw query text. It never guesses that its argument is a URL.query.fromURL(url)parses the query component of a URL.query.encode(query)encodes a query multimap into a query string.query.merge(url, query)returns the URL with the parameters applied. Null or an empty list removes a parameter.
Header and query dictionaries use dict<string, string | list<string>>. One value is a string, multiple values are a list, and zero values are an empty list. This depends on the number of values, so even a one-element input list is returned as a string.
These helpers do not convert numbers or booleans to strings for you. Null is not a stored value; it only marks a value for removal in a patch passed to headers.merge or query.merge.
Header names are case-insensitive HTTP field names. Two forms of the same header always return an error, because picking one would depend on map order. Every header helper validates the entire input block and the requested name. Returned header names are lowercased, and headers.get returns the first value whether the stored value is a string or a list.
Query helpers keep keys and values exactly as written, including empty keys and whitespace. Encoding preserves the data but may change order and escaping. query.parse removes one leading ? as syntax and treats every other byte as query data. query.fromURL and query.merge do not trim or repair their URL argument. Call rts.text.trim yourself if you want trimming.
Math helpers
rts.math.abs(x)returns the absolute value.rts.math.min(a, b)returns the smaller value.rts.math.max(a, b)returns the larger value.rts.math.clamp(x, min, max)clampsxinto the range.rts.math.floor(x)returns the largest integer <= x.rts.math.ceil(x)returns the smallest integer >= x.rts.math.round(x)rounds to the nearest integer (half away from zero).rts.math.sum(list)adds a list of numbers from left to right, as a+loop does. An empty list or null gives 0.