Skip to main content
Version: 2.4

JEXL Functions: Arrays And Objects

Function Reference​

This section lists the non-entity JEXL helper functions currently available in tSM configuration. Entity calls such as crm.customer.find(...) are covered separately in the Public API section.

Arrays, Objects, And Data Manipulation​

length(value)​

Returns the length of a value. For null and undefined, it returns 0. Numbers are converted to strings first.

length('abc')
// 3
length([1, 2, 3])
// 3
length(1234)
// 4

addItems(array, items)​

Adds items from the second array to the first array.

addItems(['a'], ['b', 'c'])
// ['a', 'b', 'c']

If items is empty or missing, it returns the original array.

intersection(array1, array2)​

Returns common items of two arrays.

intersection(['A', 'B'], ['B', 'C'])
// ['B']

If either array is missing, it returns [].

firstOrNull(array, index?)​

Returns the first item or the item at the given index. If the input is not a usable array or is empty, it returns null.

firstOrNull(['A', 'B'])
// 'A'
firstOrNull(['A', 'B'], 1)
// 'B'

map(array, fieldOrCallback)​

Maps an array to new values.

By field name:

map($context.form.contacts, 'name')
// ['Peter', 'Jana']

By nested path:

map($context.form.contacts, 'address.city')

With method syntax and callback:

$context.form.contacts.map(x => x.name)

If the input is not an array, the helper returns [].

flatMap(array, fieldOrCallback)​

Maps an array and flattens the result by one level.

flatMap([{ tags: ['A', 'B'] }, { tags: ['C'] }], 'tags')
// ['A', 'B', 'C']

Method syntax:

$context.form.items.flatMap(x => x.tags)

filter(array, fieldOrCallback, value?)​

Filters an array.

By field:

filter($context.form.items, 'status', 'ACTIVE')

With method syntax and callback:

$context.form.items.filter(x => x.status == 'ACTIVE')

If the input is not an array, the helper returns [].

find(array, fieldOrCallback, value?)​

Finds the first matching item.

find($context.form.contacts, 'primary', true)

Method syntax:

$context.form.contacts.find(x => x.primary)

If no item is found or the input is not an array, the helper returns null.

every(array, fieldOrCallback, operator?, value?)​

Checks whether all items match a condition.

every($context.form.items, 'quantity', '>=', 1)

Method syntax:

$context.form.items.every(x => x.quantity >= 1)

For strict edge cases, test the expression in the JEXL console with real data.

some(array, fieldOrCallback, value?)​

Checks whether at least one item matches a condition.

Method syntax:

$context.form.items.some(x => x.status == 'ERROR')

Intended helper form:

some($context.form.items, 'status', 'ERROR')

For complex conditions, prefer callback or method syntax because it is easier to read and test.

someEmpty(array, field?)​

Returns true if at least one item has the given field as null, undefined, or empty string.

someEmpty($context.form.contacts, 'email')

Use in validation: at least one contact has no email.

someEmpty($context.form.contacts, 'email')

someAnd(array, fields, values)​

Returns true when at least one item matches all field-value conditions.

someAnd(
  $context.form.items,
  ['status', 'type'],
  ['ACTIVE', 'SERVICE']
)

someOr(array, fields, values)​

Returns true when at least one item matches at least one field-value condition.

someOr(
  $context.form.items,
  ['status', 'priority'],
  ['ERROR', 'HIGH']
)

findAnd(array, fields, values)​

Finds the first item that matches all field-value conditions.

findAnd(
  $context.form.contacts,
  ['primary', 'active'],
  [true, true]
)

If the input array is missing, it returns null.

findOr(array, fields, values)​

Finds the first item that matches at least one field-value condition.

findOr(
  $context.form.contacts,
  ['email', 'phone'],
  [$context.form.searchEmail, $context.form.searchPhone]
)

filterAnd(array, fields, values)​

Filters items that match all field-value conditions.

filterAnd(
  $context.form.items,
  ['status', 'type'],
  ['ACTIVE', 'SERVICE']
)

filterOr(array, fields, values)​

Filters items that match at least one field-value condition.

filterOr(
  $context.form.items,
  ['status', 'priority'],
  ['ERROR', 'HIGH']
)

includes(array, value)​

Returns true if the array contains the value.

includes($context.form.roles, 'ADMIN')

Method syntax:

$context.form.roles.includes('ADMIN')

If the array is missing, the helper returns false.

includesArray(array, values, onlySome = false)​

Checks whether an array contains values from another array.

Default: all values must be present.

includesArray(['A', 'B', 'C'], ['A', 'B'])
// true

If onlySome is true, at least one value is enough:

includesArray(['A', 'B', 'C'], ['X', 'B'], true)
// true
includesArray(['A', 'B', 'C'], ['X', 'Y'])
// false

like(array, value)​

Returns true if at least one string in the array contains the given substring.

like(['customer:123', 'account:456'], 'customer')
// true

join(array, separator = ', ')​

Joins an array of strings into one string.

join(['A', 'B'], ', ')
// 'A, B'
join(map($context.form.contacts, 'email'), ';')

If the array is empty or missing, it returns an empty string.

split(value, separator = '/')​

Splits a string into an array.

split('A/B/C')
// ['A', 'B', 'C']
split('A|B|C', '|')
// ['A', 'B', 'C']

If the input is missing, it returns [].

mapObject(array, field)​

Extracts nested path values from an array of objects.

mapObject([{ a: { b: 1 } }, { a: { b: 2 } }], 'a.b')
// [1, 2]

If the input is missing or empty, it returns [].

mapToObject(array, fields)​

Creates a new object from each item, keeping only selected fields.

mapToObject([{ a: 1, b: 2, c: 3 }], ['a', 'c'])
// [{ a: 1, c: 3 }]

mapToArray(array, fields)​

Creates an array of values from each object according to the selected fields.

mapToArray([{ a: 1, b: 2 }], ['a', 'b'])
// [[1, 2]]

createObject(field, value)​

Creates an object and sets a value by dot path.

createObject('customer.id', $context.form.customerId)
// { customer: { id: '...' } }

Multiple fields:

createObject(
  ['customer.id', 'customer.name'],
  [$context.form.customerId, $context.form.customerName]
)

hashMap(pairs)​

Creates an object from [key, value] pairs.

hashMap([['status', 'ACTIVE'], ['type', 'SERVICE']])
// { status: 'ACTIVE', type: 'SERVICE' }

createHashMap(...values)​

Creates an object from alternating key, value arguments.

createHashMap('status', 'ACTIVE', 'type', 'SERVICE')
// { status: 'ACTIVE', type: 'SERVICE' }

If the last key has no value, it is set to null:

createHashMap('status', 'ACTIVE', 'type')
// { status: 'ACTIVE', type: null }

replacement(object, replacements)​

Replaces __REPLACEMENT__ placeholder values in an object.

replacement({ code: '__REPLACEMENT__' }, ['ABC'])
// { code: 'ABC' }

Use case: prepared object template filled with form values.

replacement(
  { customer: { id: '__REPLACEMENT__' } },
  [$context.form.customerId]
)

spread(obj1, obj2)​

Copies properties from the second object into the first object and returns the first object.

spread({ a: 1 }, { b: 2 })
// { a: 1, b: 2 }

The function updates the first object and returns it. Use it when the target field expects the original object to be extended with additional properties.

getFieldByObject(obj, fieldPath)​

Reads a nested value by dot path.

getFieldByObject({ a: { b: 1 } }, 'a.b')
// 1

It can often be replaced with direct access:

$context.form.a.b

or with helpers such as map, mapObject, or find.