Skip to main content

List and Monitoring Expression Helpers

These helpers are injected specifically by ExecuteListExpressionAsync. They support monitoring rules that evaluate a historical transaction list against a reference transaction.

They are not automatically available in ordinary command formulas. In this runtime, the historical list is exposed as BaseList and the reference item as Ref. Transaction helpers use those values when their optional arr and ref arguments are omitted.

Expected transaction fields​

The monitoring helpers inspect these fields when relevant:

{
  accountId: '...',
  timestampUtc: '2026-09-21T12:00:00Z',
  amount: 5000,
  status: 'SUCCESS',
  deviceId: '...',
  merchantCode: '...',
  channel: 'MOBILE',
  latitude: 51.5074,
  longitude: -0.1278
}

Status comparisons are case-sensitive and currently expect SUCCESS and FAILED.

Date and window helpers​

FunctionDescription
nowUtc()Current UTC timestamp in ISO-8601 format.
diffMinutes(first, second)Floating-point minutes from first to second; invalid input returns NaN.
diffHours(first, second)Floating-point hours from first to second; invalid input returns NaN.
diffDays(first, second)Floating-point days from first to second; invalid input returns NaN.
addMinutes(timestamp, minutes)Adds minutes and returns ISO-8601 output; invalid input returns null.
parseTimeWindowMinutes(window)Converts 30s, 15m, 2h, or 7d to minutes; invalid input returns 0.

Math and statistics helpers​

FunctionDescription
sum(values)Sum of numeric array entries.
average(values)Arithmetic mean, or 0 for an empty numeric set.
max(values)Maximum numeric value, or 0 for an empty numeric set.
min(values)Minimum numeric value, or 0 for an empty numeric set.
stdev(values)Sample standard deviation of numeric entries, or 0 when fewer than two values remain.
round(value, decimals)Rounds using midpoint-away-from-zero behavior.

Non-numeric array entries are ignored by the aggregate helpers.

String and safe-access helpers​

FunctionDescription
toUpper(value) / toLower(value)Invariant-case conversion; null becomes "".
contains(value, search)Case-insensitive containment check.
startsWith(value, search) / endsWith(value, search)Case-insensitive prefix or suffix check.
trim(value)Trims whitespace; null becomes "".
replaceAll(value, search, replacement)Replaces all literal occurrences.
isNullOrEmpty(value)Treats null and whitespace-only values as empty.
coalesce(values)Returns the first non-null, non-empty entry from the supplied array.
safeGet(object, path)Reads a dot-separated JSON path; returns null if unresolved.
generateUUID()Returns a string generated by .NET Guid.NewGuid().

log(message), warn(message), and error(message) are also registered in this runtime, but they are intentionally no-ops and do not produce returned logs.

Transaction monitoring helpers​

Arguments shown as arr? and ref? are optional. Omit them to use BaseList and Ref.

FunctionDescription
txnCount(window, arr?, ref?, predicate?)Counts account-matching transactions within the lookback window. An optional function can filter (transaction, reference).
txnSum(window, arr?, ref?, predicate?)Sums transaction amount values within the window.
txnAvg(window, arr?, ref?, predicate?)Averages transaction amount values within the window; returns 0 when none match.
uniqueDeviceCount(window, arr?, ref?)Counts distinct non-empty deviceId values within the window.
consecutiveFailures(window, arr?, ref?)Counts the trailing FAILED streak and also includes a failed reference transaction.
merchantBurst(window, arr?, ref?)Counts transactions for the reference account and merchantCode within the window.
firstSeen(field, arr?, ref?)Earliest ISO timestamp at which the reference field value appeared for the account, or null.
isNewValue(field, arr?, ref?, lookbackWindow?)Returns whether the reference field value is absent from account history, optionally within a lookback window.
minutesSinceLastSuccess(arr?, ref?)Minutes since the most recent SUCCESS; returns Infinity when none exists.
geoDistanceKm(lat1, lon1, lat2, lon2)Haversine distance in kilometres. Missing coordinates are treated as zero.
lastLocation(arr?, ref?)Most recent earlier transaction for the account, or null.
impossibleTravel(maxKmPerHour, arr?, ref?)Compares the reference location with the previous location and returns whether speed exceeds the threshold.
channelSwitchCount(window, arr?, ref?)Counts changes between consecutive non-empty channel values, including the reference transaction.
amountZScore(window, arr?, ref?)Reference amount's sample z-score against account history; returns 0 with fewer than two values or zero deviation.
isAbovePercentile(percent, window, arr?, ref?)Tests whether the reference amount is strictly above the selected historical percentile; returns true when no history exists.

Examples​

Velocity rule​

txnCount('15m') >= 5 && txnSum('15m') > 500000

Predicate filtering​

txnCount('1h', undefined, undefined, function (transaction) {
  return transaction.channel === 'MOBILE' && transaction.status === 'FAILED';
}) >= 3

Device and amount anomaly​

isNewValue('deviceId') && amountZScore('30d') >= 3

Impossible travel​

impossibleTravel(900)

Internal functions​

Names beginning with _, such as _ctxList, _ctxRef, _minsBetween, and _parseWinMins, are implementation details. They are intentionally excluded from the supported public API and may change without compatibility guarantees.

See also​