Built-in Utilities

Every expression can use a small set of helpers under the utils namespace — no setup required, available in any binding on any page. They cover the everyday jobs of turning raw data into something a user can read: dates, durations, numbers, JSON, and file downloads. Most helpers degrade quietly instead of throwing, so a formatting mistake doesn't crash your page.

Helpers at a Glance

utils.formatDate

Formats a date or timestamp using a date-fns pattern (https://date-fns.org/docs/format).

utils.formatDate(date, formatStr)

Examples

{{ utils.formatDate(order.createdAt, 'dd MMM yyyy') }} // → 15 Jan 2024 {{ utils.formatDate(order.createdAt, 'MMM dd, yyyy h:mm a') }} // → Jan 15, 2024 10:30 AM {{ utils.formatDate('not-a-date', 'dd MMM yyyy') }} // → not-a-date (echoes invalid input)

utils.formatDateByFormatType

Formats a date using a named preset instead of a raw pattern — including relative forms like "2 hours ago".

utils.formatDateByFormatType(date, formatType, options)

Date Format Presets

Presets that combine H (24-hour) with a keep the 24-hour number. For an afternoon time such as Mar 20, 2024, 16:05, dmyhma gives 20 Mar 2024, 16:05 PM, while mdyhma (12-hour h) gives Mar 20, 2024 4:05 PM.

utils.formatTime

Turns a duration in milliseconds into readable units. This is elapsed time, not a clock time.

utils.formatTime(ms, precision, notation, maxSignificantUnits)

Examples

{{ utils.formatTime(90061000, 'seconds') }} // → 1d 1h 1m 1s {{ utils.formatTime(90061000, 'seconds', 'comfortable') }} // → 1 day 1 hour 1 minute 1 second {{ utils.formatTime(90061000, 'seconds', 'compact', 2) }} // → 1d 1h

utils.formatNumber

Formats a number with locale grouping, compact notation, or units. Takes a single options object — not a plain number.

utils.formatNumber({ value, locale, notation, compactDisplay, maximumFractionDigits, padDecimalPlaces, unit, unitDisplay })

Examples

{{ utils.formatNumber({ value: 1234567.891, maximumFractionDigits: 2 }) }} // → 1,234,567.89 {{ utils.formatNumber({ value: 1234567, notation: 'compact', compactDisplay: 'short', maximumFractionDigits: 1 }) }} // → 1.2M {{ utils.formatNumber({ value: 5, maximumFractionDigits: 2, padDecimalPlaces: true }) }} // → 5.00 {{ utils.formatNumber({ value: 20, unit: 'percent' }) }} // → 20% {{ utils.formatNumber({ value: 20, unit: 'kilometer-per-hour', unitDisplay: 'long' }) }} // → 20 kilometers per hour

Warning: utils.formatNumber does not support currency formatting. To show monetary values, format the number and add the currency symbol yourself in your expression: {{ '$' + utils.formatNumber({ value: total, maximumFractionDigits: 2 }) }}

utils.parseJson

Parses a JSON string safely. Invalid JSON never throws — you get the fallback value instead.

utils.parseJson(str, fallback, retriever)

Examples

{{ utils.parseJson(orders_query.data.objects?.[0]?.payloadJson).total }} // → 250 {{ utils.parseJson('oops', []) }} // → [] (fallback) {{ utils.parseJson('null') }} // → {} (null result → fallback)

utils.stringifyJson

Serializes a value to a JSON string. On failure (e.g. circular reference) returns the fallback instead of throwing.

utils.stringifyJson(obj, fallback, space, replacer)

Examples

• {{ utils.stringifyJson({ orderId: 'ORD-1042', total: 250 }) }} → {"orderId":"ORD-1042","total":250}

• {{ utils.stringifyJson({ a: 1 }, undefined, 2) }} → the same JSON indented by 2 spaces per level. Pass undefined for fallback to reach space.

• {{ utils.stringifyJson(circularObject) }} → null (failed, no fallback given)

utils.downloadFile

Starts a file download in the current browser tab. This is a side effect — put it in an action (button's On Click), not in a text/label binding that recomputes on every render.

utils.downloadFile(fileOrUrl, filename)

Usage — in a button's On Click action

Run Script takes plain JavaScript, not a {{ }} binding, so write the call without braces:

utils.downloadFile(invoice_query.data.fileUrl, 'invoice-2024.pdf');

Don't put it in a text binding.

Gotchas