Chapter III. - JEXL Functions Reference Guide

This document provides a detailed overview of all JEXL functions available in the tSM platform. Each function is categorized for better usability and includes descriptions, parameters, and examples.

1. Date & Time Utilities

addTime

Adds time to a given date in specified units.

• Parameters:
  • date: The starting date (string or Date object).
  • amount: The amount of time to add (integer).
  • unit: The unit of time (e.g., 'days', 'hours', 'minutes').
• Example:

addTime('2023-01-01T00:00:00Z', 1, 'days');
// Output: '2023-01-02T00:00:00Z'

compareDates

Compares two dates using a specified operator and unit of time.

• Parameters:
  • date1: First date (string or Date object).
  • date2: Second date (string or Date object).
  • operator: Comparison operator ('<', '>', '==', etc.).
  • unit: The unit of time to compare ('days', 'hours', etc.).
• Example:

compareDates('2023-01-01', '2023-01-10', '<', 'days');
// Output: true

dateDiff

Calculates the difference between two dates in a specified unit.

• Parameters:
  • startDate: The start date (string or Date object).
  • endDate: The end date (string or Date object).
  • unit: The unit of time ('days', 'hours', 'minutes', etc.).
• Example:

dateDiff('2023-01-01', '2023-01-10', 'days');
// Output: 9

dateFormat

Formats a date into a custom pattern.

• Parameters:
  • date: The date (string or Date object).
  • pattern: The desired output format (e.g., 'YYYY-MM-DD').
• Example:

dateFormat(new Date(), 'YYYY-MM-DD');
// Output: '2023-01-01'

dateFormatFrom

Converts a date from one format to another.

• Parameters:
  • dateString: The date as a string.
  • fromPattern: The current format of the dateString.
  • toPattern: The desired output format.
• Example:

dateFormatFrom('2023-01-01', 'YYYY-MM-DD', 'DD-MM-YYYY');
// Output: '01-01-2023'

dateServerFormat

Formats a date to a server-compatible format.

• Parameters:
  • date: The date (string or Date object).
  • time: The time portion (e.g., '12:00'), if needed.
  • pattern: The format pattern for parsing the date part.
• Example:

dateServerFormat(new Date(), '12:00', 'YYYY-MM-DD');
// Output: '2023-01-01T12:00:00.000Z'

decimalToHoursMinutesSeconds

Converts a decimal hour value into hours, minutes (and optionally seconds).

• Parameters:
  • decimalHours: The decimal number representing hours.
• Example:

decimalToHoursMinutesSeconds(1.5);
// Output: '01:30'

hours

Converts a date to the number of hours since the Unix epoch (1970-01-01).

• Parameters:
  • date: The date (string or Date object).
• Example:

hours('2023-01-01T00:00:00Z');
// Output: 438291

isToday

Checks if a given date is today.

• Parameters:
  • date: The date (string or Date object).
• Example:

isToday('2023-01-01');
// Output: true

isTomorrow

Checks if a given date is tomorrow.

• Parameters:
  • date: The date (string or Date object).
• Example:

isTomorrow('2023-01-02');
// Output: true

isYesterday

Checks if a given date is yesterday.

• Parameters:
  • date: The date (string or Date object).
• Example:

isYesterday('2023-01-31');
// Output: true

midnight

Returns the ISO string for midnight of the current or a specified day.

• Parameters:
  • (Optional) daysOffset: Number of days from now (integer).
• Example:

midnight(1);
// Output: '2023-01-02T23:59:59.999Z'

minutes

Converts a date to the number of minutes since the Unix epoch.

• Parameters:
  • date: The date (string or Date object).
• Example:

minutes('2023-01-01T00:00:00Z');
// Output: 26297460

nidToDate

Converts a national identification number into a date.

• Parameters:
  • nid: The national ID string (e.g., '123456/7890').
• Example:

nidToDate('123456/7890');
// Output: '1956-04-12'

now

Returns the current date and time in ISO format.

• Parameters:
  • (none)
• Example:

now();
// Output: '2023-01-01T12:00:00.000Z'

nowWithHours

Returns the current date and time with specific hours, minutes, and seconds.

• Parameters:
  • hours: Hour to set (integer).
  • minutes: Minutes to set (integer).
  • (Optional) seconds: Seconds to set (integer).
• Example:

nowWithHours(15, 30);
// Output: '2023-01-01T15:30:00.000Z'

roundDateTo

Rounds a date to a specified unit of time.

• Parameters:
  • date: The date (string or Date object).
  • unit: The unit of time to round to (e.g., 'hours', 'minutes').
• Example:

roundDateTo('2023-01-01T12:45', 'hours');
// Output: '2023-01-01T13:00:00.000Z'

seconds

Converts a date to the number of seconds since the Unix epoch.

• Parameters:
  • date: The date (string or Date object).
• Example:

seconds('2023-01-01T00:00:00Z');
// Output: 1577847600

---

2. Data Manipulation

addItems

Adds items to an existing array.

• Parameters:
  • array: The initial array.
  • items: An array of items to add.
• Example:

addItems([1, 2], [3, 4]);
// Output: [1, 2, 3, 4]

createHashMap

Creates a hash map from alternating key-value arguments.

• Parameters:
  • keyValuePairs: A list of strings in the sequence 'key1', 'value1', 'key2', 'value2', ....
• Example:

createHashMap('key1', 'value1', 'key2', 'value2');
// Output: { key1: 'value1', key2: 'value2' }

createObject

Creates an object with specified fields and values.

• Parameters:
  • keys: An array of keys.
  • values: An array of values.
• Example:

createObject(['name'], ['John']);
// Output: { name: 'John' }

every

Checks if every item in an array matches a condition (similar to JavaScript’s Array.every).

• Parameters:
  • array: The array of objects.
  • field: The field to compare within each object.
  • operator: Comparison operator ('==', '>', etc.).
  • value: Value to compare against.
• Example:

every([{ a: 5 }, { a: 10 }], 'a', '>', 3);
// Output: true

filter

Filters an array of objects based on a single field-value condition.

• Parameters:
  • array: The array of objects.
  • field: The field to match.
  • value: The value to match.
• Example:

filter([{ a: 1 }, { a: 2 }], 'a', 2);
// Output: [{ a: 2 }]

filterAnd

Filters an array of objects based on multiple field-value conditions using AND logic.

• Parameters:
  • array: The array of objects.
  • fields: An array of field names.
  • values: An array of corresponding values.
• Example:

filterAnd([{ a: 1 }, { a: 2 }], ['a'], [1]);
// Output: [{ a: 1 }]

filterOr

Filters an array of objects based on multiple field-value conditions using OR logic.

• Parameters:
  • array: The array of objects.
  • fields: An array of field names.
  • values: An array of corresponding values.
• Example:

filterOr([{ a: 1 }, { a: 2 }], ['a'], [2]);
// Output: [{ a: 2 }]

find

Finds the first item in an array that meets a field-value condition.

• Parameters:
  • array: The array of objects.
  • field: The field to match.
  • value: The value to match.
• Example:

find([{ id: 1 }, { id: 2 }], 'id', 2);
// Output: { id: 2 }

findAnd

Finds the first object in an array that matches multiple field-value conditions using AND logic.

• Parameters:
  • array: The array of objects.
  • fields: An array of fields.
  • values: An array of values.
• Example:

findAnd([{ a: 1 }, { a: 2 }], ['a'], [1]);
// Output: { a: 1 }

findOr

Finds the first object in an array that matches any of the field-value conditions using OR logic.

• Parameters:
  • array: The array of objects.
  • fields: An array of fields.
  • values: An array of values.
• Example:

findOr([{ a: 1 }, { a: 2 }], ['a'], [2]);
// Output: { a: 2 }

firstOrNull

Returns the first element of an array or null if the array is empty.

• Parameters:
  • array: The array.
• Example:

firstOrNull(['apple', 'banana']);
// Output: 'apple'

flatMap

Flattens and maps an array of objects based on a specified field.

• Parameters:
  • array: An array of objects.
  • field: The field containing the array to flatten.
• Example:

flatMap([{ a: [1, 2] }, { a: [3, 4] }], 'a');
// Output: [1, 2, 3, 4]

getFieldByObject

Retrieves a field value from an object using a dot-notation field path.

• Parameters:
  • obj: The object to query.
  • fieldPath: String path (e.g., 'a.b.c').
• Example:

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

hashMap

Creates a hash map from an array of [key, value] pairs.

• Parameters:
  • pairs: An array of arrays, where each sub-array is [key, value].
• Example:

hashMap([['key1', 'value1']]);
// Output: { key1: 'value1' }

includes

Checks if an array contains a specific value.

• Parameters:
  • array: The array.
  • value: The value to look for.
• Example:

includes(['apple', 'banana'], 'apple');
// Output: true

includesArray

Checks if an array contains all or some elements from another array.

• Parameters:
  • sourceArray: The array to search in.
  • searchArray: The array of items to look for.
  • allRequired: Boolean indicating whether all items must be present (true) or any item suffices (false).
• Example:

includesArray([1, 2, 3], [2, 4], true);
// Output: true

join

Joins an array of strings with a specified separator.

• Parameters:
  • array: Array of strings.
  • separator: The string to separate items.
• Example:

join(['apple', 'banana'], '-');
// Output: 'apple-banana'

json

Converts an object into a JSON string.

• Parameters:
  • object: The object to convert.
• Example:

json({ key: 'value' });
// Output: '{"key":"value"}'

jsonParse

Parses a JSON string into an object.

• Parameters:
  • jsonString: A valid JSON string.
• Example:

jsonParse('{"key":"value"}');
// Output: { key: 'value' }

length

Returns the length of a string or array.

• Parameters:
  • target: A string or an array.
• Example:

length('hello');
// Output: 5

like

Checks if any string in an array contains a given substring.

• Parameters:
  • array: Array of strings.
  • substring: The substring to look for.
• Example:

like(['apple', 'banana'], 'app');
// Output: true

map

Maps an array of objects based on a transformation function or a specific field.

• Parameters:
  • array: The array of objects.
  • fieldOrCallback: A field name string or a function to transform each element.
• Example:

map([{ a: 1 }, { a: 2 }], 'a');
// Output: [1, 2]

mapObject

Transforms an array of objects into an array of values based on a specific field.

• Parameters:
  • array: Array of objects.
  • field: The field to extract from each object.
• Example:

mapObject([{ a: 1 }, { a: 2 }], 'a');
// Output: [1, 2]

mapToArray

Maps an array of objects to an array of arrays, extracting specified fields.

• Parameters:
  • array: Array of objects.
  • fields: An array of field names to extract.
• Example:

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

mapToObject

Maps an array of objects to a new array containing only specific fields.

• Parameters:
  • array: Array of objects.
  • fields: An array of fields to include in each object.
• Example:

mapToObject([{ a: 1, b: 2 }], ['a']);
// Output: [{ a: 1 }]

replace

Replaces all occurrences of a target string with another string.

• Parameters:
  • text: The original text.
  • searchValue: The string to replace.
  • replaceValue: The new string.
• Example:

replace('hello-world', '-', ' ');
// Output: 'hello world'

replaceDoubleQuotesToSingle

Replaces all double quotes in a string with single quotes.

• Parameters:
  • text: The original text.
• Example:

replaceDoubleQuotesToSingle('"hello"');
// Output: ''hello''

replacement

Replaces placeholders in an object (e.g., __REPLACEMENT__) with provided replacement values.

• Parameters:
  • object: The object containing placeholders.
  • replacements: An array of replacement values.
• Example:

replacement({ key: '__REPLACEMENT__' }, ['value']);
// Output: { key: 'value' }

some

Checks if any item in an array meets a specific field-value condition.

• Parameters:
  • array: The array of objects.
  • field: The field to check.
  • value: The value to match.
• Example:

some([{ a: 1 }, { a: 5 }], 'a', 5);
// Output: true

someAnd

Checks if any object in an array matches multiple field-value conditions using AND logic.

• Parameters:
  • array: The array of objects.
  • fields: An array of field names.
  • values: An array of corresponding values.
• Example:

someAnd([{ a: 1, b: 2 }, { a: 3, b: 4 }], ['a', 'b'], [1, 2]);
// Output: true

someEmpty

Checks if any attribute in an array of objects is empty or null.

• Parameters:
  • array: The array of objects.
  • field: The field to check for empty/null.
• Example:

someEmpty([{ a: 1 }, { a: null }], 'a');
// Output: true

someOr

Checks if any object in an array matches any of the field-value conditions using OR logic.

• Parameters:
  • array: The array of objects.
  • fields: Array of field names.
  • values: Array of corresponding values.
• Example:

someOr([{ a: 1, b: 2 }, { a: 3, b: 4 }], ['a', 'b'], [1, 4]);
// Output: true

split

Splits a string into an array based on a specified delimiter.

• Parameters:
  • text: The string to split.
  • delimiter: The delimiter character(s).
• Example:

split('a/b/c', '/');
// Output: ['a', 'b', 'c']

spread

Merges two objects into one.

• Parameters:
  • obj1: The first object.
  • obj2: The second object.
• Example:

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

substring

Extracts a substring from a string.

• Parameters:
  • text: The original string.
  • start: The starting index.
  • end: The ending index (non-inclusive).
• Example:

substring('abcdef', 1, 4);
// Output: 'bcd'

---

3. Arithmetic

ceil

Rounds a number up to the nearest integer.

• Parameters:
  • value: The numeric value to round up.
• Example:

ceil(1.2);
// Output: 2

floor

Rounds a number down to the nearest integer.

• Parameters:
  • value: The numeric value to round down.
• Example:

floor(1.9);
// Output: 1

percentToValue

Converts a percentage string (e.g., "50%") into a decimal value.

• Parameters:
  • percentString: The percentage in string format (e.g., "50%").
• Example:

percentToValue('50%');
// Output: 0.5

round

Rounds a number to the nearest integer.

• Parameters:
  • value: The numeric value to round.
• Example:

round(1.5);
// Output: 2

sum

Calculates the sum of multiple numbers.

• Parameters:
  • Any number of numeric arguments.
• Example:

sum(1, 2, 3);
// Output: 6

sumMany

Sums numbers in an array based on a specific field.

• Parameters:
  • array: The array of objects.
  • field: The field name to sum by.
• Example:

sumMany([{ a: 1 }, { a: 2 }], 'a');
// Output: 3

toFixed

Rounds a number to a fixed number of decimal places (returns a string).

• Parameters:
  • value: The numeric value.
  • decimals: Number of decimal places.
• Example:

toFixed(1.2345, 2);
// Output: '1.23'

transformNumber

Transforms a number to a formatted string with a specified precision (often adding commas, etc.).

• Parameters:
  • value: The numeric value.
  • decimals: Number of decimal places.
• Example:

transformNumber(12345.678, 2);
// Output: '12,345.68'

---

4. Validation

banValid

Validates a bank account number.

• Parameters:
  • accountNumber: The bank account number as a string.
• Example:

banValid('1234567890');
// Output: true

isNaN

Checks if a value is NaN (Not a Number).

• Parameters:
  • value: The value to test.
• Example:

isNaN('not-a-number');
// Output: true

isNullOrEmpty

Checks if a variable or array is null, undefined, or empty.

• Parameters:
  • input: The value or array to test.
• Example:

isNullOrEmpty([]);
// Output: true

isUuid

Checks if a string is a valid UUID.

• Parameters:
  • uuidString: The string to test.
• Example:

isUuid('550e8400-e29b-41d4-a716-446655440000');
// Output: true

isValidEmail

Validates if a string is a properly formatted email address.

• Parameters:
  • email: The email string to validate.
• Example:

isValidEmail('test@example.com');
// Output: true

nidValid

Validates Czech and Slovak national identification numbers.

• Parameters:
  • nid: The national ID string (e.g., '123456/7890').
• Example:

nidValid('123456/7890');
// Output: true

---

5. Utilities

getUuid

Generates a new UUID.

• Parameters:
  • (none)
• Example:

getUuid();
// Output: '550e8400-e29b-41d4-a716-446655440000'

---

6. Current

currentOrganizationId

Returns the current organization ID.

• Parameters:
  • (none)
• Example:

currentOrganizationId();
// Output: 'org12345'

currentUserId

Returns the ID of the currently logged-in user.

• Parameters:
  • (none)
• Example:

currentUserId();
// Output: 'user12345'

---

7. Entity-based

account

(Potentially an alias or function for array manipulation — details unclear from source.)
Adds items to an array.

• Parameters:
  • array: The initial array.
  • items: An array of items to add.
• Example:

account([1, 2], [3, 4]);
// Output: [1, 2, 3, 4]