Formula Helper Functions

These global JavaScript helpers are injected into standard command-formula execution. They are available without imports when a command is executed through the BankLingo command engine, including ExeFormula and BPMN formula execution that uses ExecuteFormulaWithLogsAsync.

They are not browser APIs. See Runtime availability for execution modes that expose only the base engine or a different helper library.

Null and object helpers

Function	Returns	Behavior
`isNullOrEmpty(value)`	boolean	`true` for `null`, `undefined`, or `""`. Whitespace-only strings are not empty.
`coalesce(...values)`	any	First value that is not `null`, `undefined`, or `""`; otherwise `null`.
`safeGet(object, path, defaultValue)`	any	Reads a dot-separated path and returns `defaultValue` when the path cannot be resolved.
`generateUUID()`	string	UUID-shaped identifier generated by JavaScript. It uses `Math.random` and must not be used as a cryptographic token.

var customerName = coalesce(
  safeGet(context, 'customer.displayName', null),
  safeGet(context, 'customer.legalName', null),
  'Unknown customer'
);

Date and time helpers

Function	Returns	Behavior
`now()`	string	Current time as an ISO-8601 UTC string.
`addDays(date, days)`	string or `null`	Adds calendar days and returns an ISO string.
`diffDays(first, second)`	number or `null`	Whole-day difference calculated as `floor(second - first)`.
`formatDate(date, format)`	string or `null`	Supports `YYYY-MM-DD`, `DD/MM/YYYY`, and `YYYYMMDDHHmmss`; other formats return ISO output.

var expiresAt = addDays(now(), 30);

return {
  expiresAt: expiresAt,
  displayDate: formatDate(expiresAt, 'DD/MM/YYYY'),
  daysRemaining: diffDays(now(), expiresAt)
};

Invalid date inputs return null. Date-only formatting uses the runtime's local calendar fields, while now() and the fallback output are ISO UTC strings.

String helpers

Function	Returns	Behavior
`toUpper(value)`	string or original value	Uppercases strings.
`toLower(value)`	string or original value	Lowercases strings.
`trim(value)`	string or original value	Removes leading and trailing whitespace from strings.
`contains(value, search)`	boolean-like	Case-sensitive substring test for non-empty inputs.
`replaceAll(value, search, replacement)`	string	Replaces every occurrence using literal string matching.
`slugify(value)`	string	Lowercases text, replaces whitespace with hyphens, and removes non-alphanumeric characters except hyphens.

var productCode = toUpper(trim(context.productCode));
var documentSlug = slugify(context.documentTitle);
var normalizedReference = replaceAll(context.reference, ' ', '');

Numeric helpers

Function	Returns	Behavior
`round(value, decimals)`	number	Rounds to the requested decimal places.
`toFixed(value, decimals)`	string	Formats a number with a fixed number of decimal places.
`percentageOf(amount, percent)`	number	Calculates `(amount * percent) / 100`.

var fee = round(percentageOf(context.amount, 1.5), 2);
var displayFee = toFixed(fee, 2);

toFixed() returns a string. Use round() when the result must remain numeric. For converting an integer amount to English words, see numberToWords().

Validation helpers

Function	Returns	Accepted form
`isEmail(value)`	boolean	Basic `name@domain.tld` structure.
`isPhoneNumber(value)`	boolean	Optional leading `+` followed by 7 to 15 digits.
`isNumber(value)`	boolean	Value can be parsed as a finite JavaScript number.
`isDate(value)`	boolean	JavaScript `Date` can parse the value.

These are format checks, not proof that an email address, telephone number, or date represents a real or authorized entity.

if (!isEmail(context.emailAddress)) {
  throw new Error('A valid email address is required');
}

if (!isNumber(context.amount)) {
  throw new Error('amount must be numeric');
}

Logging helpers

Function	Description
`console.log(message)`	Adds an informational entry to the command's returned `logs` collection.
`console.warn(message)`	Adds a warning entry to the returned `logs` collection.
`console.error(message)`	Adds an error entry to the returned `logs` collection.
`log(message)`	Convenience wrapper around `console.log`.

Pass a single string or object per call. Logging availability differs in the specialized list-expression runtime, where log, warn, and error are no-ops.

BpmnError

BpmnError is a globally registered error constructor for a business error with an error code.

throw new BpmnError('LIMIT_EXCEEDED', 'The transaction exceeds the configured limit');

Argument	Required	Description
`errorCode`	Yes	Stable BPMN/business error code.
`message`	No	Human-readable message. Defaults to `BPMN Error: <errorCode>`.

Formula-only execution preserves the code as a BpmnErrorException. Standard command execution always surfaces the message, but code propagation depends on the execution path; do not assume every caller receives errorCode unless that path has been verified.

Runtime availability

Runtime	Helpers on this page
Command formulas executed by `ExecuteAsync`	Yes
`ExeFormula`	Yes
`ExecuteFormulaWithLogsAsync`	Yes
`ExecuteFormulaOnlyAsync`	Base-engine globals only; the inline helpers on this page are not injected
`ExecuteDualFormulaAsync`	Base-engine globals only
`ExecuteListExpressionAsync`	Uses the separate List and Monitoring Expression Helpers
BPM process-trigger condition expressions	No; those expressions receive only `context` and standard JavaScript
Browser/client scripts	No

Null and object helpers​

Date and time helpers​

String helpers​

Numeric helpers​

Validation helpers​

Logging helpers​

BpmnError​

Runtime availability​

See also​