Global
This is the global namespace. Functions are available without having to prepend them with a namespace identifier.
Static properties
Image any
HTML Image.
Methods
NUM
NUM(number: number, numDecimals?: number)
Returns a formatted number as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used.
Parameters
number number
A numeric value.
numDecimals number
(optional) The number of decimals. Defaults to 0.
Return type
string
Examples
NUM(3) // => "3"
NUM(3.99) // => "3.99"
NUM(3.99) // => "3,99" (when {culture:'nl'} is specified in execution options)
NUM(3.99, 1) // => "4.0"
NUM(3.99, 0) // => "4"
CUR
CUR(number: number, numDecimals?: number)
Returns a formatted currency number as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used.
Parameters
number number
A numeric value.
numDecimals number
(optional) The number of decimals. Defaults to 2.
Return type
string
Examples
CUR(3) // => "3.00"
CUR(3.99) // => "3.99" (default)
CUR(3.99) // => "£3.99" (when {culture:'en-GB'} is specified in execution options)
CUR(3.99) // => "$3.99" (when {culture:'en-US'} is specified in execution options)
CUR(3.99) // => "€ 3,99" (when {culture:'nl'} is specified in execution options)
CUR(3.99, 1) // => "4.0"
CUR(3.99, 0) // => "4"
CURN
CURN(number: number, numDecimals?: number)
Returns a formatted currency number as a string without the currency symbol. If a culture is specified when executing a ruleset, the formatting of that culture will be used.
Parameters
number number
A numeric value.
numDecimals number
(optional) The number of decimals. Defaults to 2.
Return type
string
Examples
CURN(3) // => "3.00"
CURN(3.99) // => "3.99" (default)
CURN(3.99) // => "3,99" (when {culture:'nl'} is specified in execution options)
CURN(3.99, 1) // => "4.0"
CURN(3.99, 0) // => "4
DATESTR
DATESTR(date: Date | string, options?: Intl.DateTimeFormatOptions)
Returns a formatted date as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used. See Intl.DateTimeFormat for more information on the formatting options.
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
options Intl.DateTimeFormatOptions
(optional) The formatting options.
Return type
string
Examples
DATESTR(TODAY()) // => "3-5-2023" (when {culture:'nl'} is specified in execution options)
DATESTR(TODAY()) // => "5/3/2023" (when {culture:'en'} is specified in execution options)
// Custom formatting:
DATESTR(TODAY(), {year:'numeric', month:'long', day:'numeric'})
// => "3 mei 2023" (when {culture:'nl'} is specified in execution options)
DATESTR(TODAY(), {year:'numeric', month:'long', day:'numeric'})
// => "May 3, 2023" (when {culture:'en'} is specified in execution options)
AGE
AGE(birthDate: Date | string)
Returns the amount of full years passed since a given JavaScript Date Object.
Parameters
birthDate Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
AGE(new Date('1980-01-01')) // => 43
AGE('1986-01-01') // => 37
DATE
DATE(year: number | string | Date, month?: number, day?: number)
Creates a JavaScript Date Object. Is more reliable than using 'new Date()' to create a date, as DATE() ignores timezones.
Parameters
year number | string | Date
The year or a YYYY-MM-DD string.
month number
(optional) The month.
day number
(optional) The day.
Return type
Date
Examples
DATE(2000, 1, 1) // => (Date) 2000-01-01T00:00:00.000Z
DATE('2000-01-01') // => (Date) 2000-01-01T00:00:00.000Z
DATE('2000-01-01T00:00') // => (Date) 2000-01-01T00:00:00.000Z
For comparison:
new Date(2000, 1, 1) // => (Date) 2000-01-31T23:00:00.000Z
new Date('2000-01-01') // => (Date) 2000-01-01T00:00:00.000Z
new Date('2000-01-01T00:00') // => (Date) 1999-12-31T23:00:00.000Z
TODAY
TODAY()
Returns the current date as a JavaScript Date Object at the start of the day (midnight, 00:00).
Parameters
Return type
Date
Examples
TODAY() // => (Date) 2023-05-03T00:00:00.000Z
NOW
NOW()
Returns the current date and time as a JavaScript Date Object accurate to the millisecond.
Parameters
Return type
Date
Examples
NOW() // => (Date) 2023-05-03T12:18:07.466Z
DAY
DAY(date: Date | string)
Returns the day of a given JavaScript Date Object.
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
DAY(TODAY()) // => 3
WEEKDAY
WEEKDAY(date: Date | string)
Returns the day of the week of a given JavaScript Date Object. Differs from JS Date's getDay() method, in that it is 1-based. (e.g. Sunday = 1, instead of 0. Saturday = 7)
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
WEEKDAY(TODAY()) // => 4 (Wednesday = 4)
MONTH
MONTH(date: Date | string)
Returns the month of a given JavaScript Date Object. Differs from JS Date's getMonth() method, in that it is 1-based. (e.g. January = 1, instead of 0.)
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
MONTH(TODAY()) // => 5
YEAR
YEAR(date: Date | string)
Returns the year of a given JavaScript Date Object.
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
YEAR(TODAY()) // => 2023
YEARMONTH
YEARMONTH(date: Date | string)
Returns the year and month of a given JavaScript Date Object.
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
string
Examples
YEARMONTH(TODAY()) // => "2023-05"
YEARMONTHDAY
YEARMONTHDAY(date: Date | string)
Returns the year, month and day of a given JavaScript Date Object. Note: this is similar to calling .toShortDateString() on a Date. See also:
Date.toShortDateString
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
string
Examples
YEARMONTHDAY(TODAY()) // => "2023-05-03"
TODAY().toShortDateString() // => "2023-05-03"
MONTHDAY
MONTHDAY(date: Date | string)
Returns the month and day of a given JavaScript Date Object.
Parameters
date Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
string
Examples
MONTHDAY(TODAY()) // => "05-03"
DAYDIFF
DAYDIFF(dateFrom: Date | string, dateTo: Date | string)
Returns the amount of full days between two dates. See also:
Date.diff
Parameters
dateFrom Date | string
A JavaScript Date object or an ISO 8601 formatted string.
dateTo Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
DAYDIFF(new Date('2010-01-01'), new Date('2011-01-01')) // => 365
DAYDIFF(new Date('2000-01-01T12:00:00'), new Date('2000-01-02T11:59:59')) // => 0
DAYDIFF(new Date('2000-01-01T12:00:00'), new Date('2000-01-02T12:00:00')) // => 1
SAMEDAY
SAMEDAY(dateA: Date | string, dateB: Date | string)
Returns whether two dates are on the same day. See also:
Date.isSameDay
Parameters
dateA Date | string
A JavaScript Date object or an ISO 8601 formatted string.
dateB Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
boolean
Examples
SAMEDAY(new Date('2011-01-01'), new Date('2011-01-01')) // => true
SAMEDAY(new Date('2000-01-01T00:00:00'), new Date('2000-01-01T23:59:59')) // => true
SAMEDAY(new Date('2000-01-01'), new Date('2000-01-02')) // => false
MONTHDIFF
MONTHDIFF(dateFrom: Date | string, dateTo: Date | string)
Returns the amount of full months between two dates. See also:
Date.diff
Parameters
dateFrom Date | string
A JavaScript Date object or an ISO 8601 formatted string.
dateTo Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
MONTHDIFF(new Date('1980-01-01'), new Date('2000-01-01')) // => 240
MONTHDIFF(new Date('1980-01-01'), new Date('2000-01-15')) // => 240
MONTHDIFF(new Date('1980-01-15'), new Date('2000-01-01')) // => 239
MONTHDIFF('2020-04-16T15:37:25.579Z', '2023-06-01T15:37:25.578Z') // => 37
YEARDIFF
YEARDIFF(dateFrom: Date | string, dateTo: Date | string)
Returns the amount of full years between two dates. See also:
Date.diff
Parameters
dateFrom Date | string
A JavaScript Date object or an ISO 8601 formatted string.
dateTo Date | string
A JavaScript Date object or an ISO 8601 formatted string.
Return type
number
Examples
YEARDIFF(new Date('1980-01-01'), new Date('2000-01-01')) // => 20
YEARDIFF(new Date('1980-01-02'), new Date('2000-01-01')) // => 19
DATEDIFF
DATEDIFF(dateFrom: Date | string, dateTo: Date | string, absolute?: boolean)
Returns an object containing the difference between two dates in various units. The output is similar to Date.diff(). See also:
Date.diff
Parameters
dateFrom Date | string
A JavaScript Date object or an ISO 8601 formatted string.
dateTo Date | string
A JavaScript Date object or an ISO 8601 formatted string.
absolute boolean
(optional) If true, will return a positive value for the difference.
Return type
DateDiffResult
Examples
DATEDIFF(new Date('1980-01-01'), new Date('2000-01-01')) // =>
{
totalMilliseconds: 631152000000,
totalSeconds: 631152000,
totalMinutes: 10519200,
totalHours: 175320,
totalDays: 7305,
totalMonths: 240,
totalYears: 20,
totalFullSeconds: 631152000,
totalFullMinutes: 10519200,
totalFullHours: 175320,
totalFullDays: 7305,
totalFullMonths: 240,
totalFullYears: 20
}
ABS
ABS(x: number)
Shorthand for Math.abs()
Parameters
x number
A number.
Return type
number
Examples
ABS(1) // => 1
ABS(-1) // => 1
CEIL
CEIL(x: number, numDecimals?: number)
Returns the smallest integer greater than or equal to a given number.
Parameters
x number
A number.
numDecimals number
(optional) Number of decimals. Can be negative to round down to number of integers.
Return type
number
Examples
CEIL(1) // => 1
CEIL(1.1) // => 2
CEIL(1.501, 1) // => 1.6
// A negative numDecimals will round down to number of integers:
CEIL(1948, -1) // => 1950
CEIL(1948, -2) // => 2000
CEIL(1948, -3) // => 2000
FLOOR
FLOOR(x: number, numDecimals?: number)
Returns the largest integer less than or equal to a given number.
Parameters
x number
A number.
numDecimals number
(optional) Number of decimals. Can be negative to round down to number of integers.
Return type
number
Examples
FLOOR(1) // => 1
FLOOR(1.9) // => 1
FLOOR(1.501, 1) // => 1.5
// A negative numDecimals will round down to number of integers:
FLOOR(1948, -1) // => 1940
FLOOR(1948, -2) // => 1900
FLOOR(1948, -3) // => 1000
ROUND
ROUND(x: number, numDecimals?: number)
Returns the value of a number rounded to the nearest integer. Using the 'Half Away From Zero' rounding mode.
Parameters
x number
A number.
numDecimals number
(optional) Number of decimals. Can be negative to round down to number of integers.
Return type
number
Examples
ROUND(1.4) // => 1
ROUND(1.5) // => 2
ROUND(1.501, 1) // => 1.5
// A negative numDecimals will round down to number of integers:
ROUND(1948, -1) // => 1950
ROUND(1948, -2) // => 1900
ROUND(1948, -3) // => 2000
LOG
LOG(x: number)
Shorthand for Math.log() - returns the natural logarithm (base e) of the given number.
Parameters
x number
A number.
Return type
number
Examples
LOG(8) / LOG(2) // => 3 (for 2 x 2 x 2 = 8)
LOG(625) / LOG(5) // => 4 (for 5 x 5 x 5 x 5 = 625)
EXP
EXP(x: number)
Shorthand for Math.exp() - returns ex, where x is the argument, and e is Euler's number (also known as Napier's constant), the base of the natural logarithms.
Parameters
x number
A number.
Return type
number
Examples
EXP(0) // => 1
EXP(1) // => 2.718281828459045
EXP(-1) // => 0.36787944117144233
EXP(2) // => 7.38905609893065
POW
POW(base: number, exponent: number)
Shorthand for Math.pow() - returns the base to the exponent power. Note: for performance reasons it is better to use the ** operator instead of POW or Math.pow.
Parameters
base number
The base number.
exponent number
The exponent used to raise the base.
Return type
number
Examples
POW(2, 3) // => 8
POW(4, 0.5) // => 2
POW(7, -2) // => 0.020408163265306124 (1/49)
SQRT
SQRT(x: number)
Shorthand for Math.sqrt() - returns the square root of a number.
Parameters
x number
A number.
Return type
number
Examples
SQRT(9) // => 3
SQRT(2) // => 1.4142135623730951
SQRT(1) // => 1
MIN
MIN(...numbers: number[])
Returns the lowest-valued number passed into it.
Parameters
...numbers number[]
Numbers.
Return type
number
Examples
MIN(2, 3) // => 2
MIN(-2, 3, -1) // => -2
MIN([-2, 3, -1]) // You can pass in an array of numbers, too => -2
MAX
MAX(...numbers: number[])
Returns the highest-valued number passed into it.
Parameters
...numbers number[]
Numbers.
Return type
number
Examples
MAX(2, 3) // => 3
MAX(-2, -3, -1) // => -1
MAX([-2, -3, -1]) // You can pass in an array, too => -1
CLAMP
CLAMP(input: number, min: number, max: number)
Combines the logic of MIN and MAX - Clamps the input number between the min and max values.
Parameters
input number
The input value to be clamped.
min number
Lowest possible value to clamp the input to.
max number
Highest possible value to clamp the input to.
Return type
number
Examples
CLAMP(5, 0, 10) // => 5 // 5 is between 0 and 10, so value is not clamped
CLAMP(-1, 0, 10) // => 0 // -1 is lower than 0, so value is clamped to 0
CLAMP(11, 0, 10) // => 10 // 11 is higher than 10, so value is clamped to 10
MAP
MAP(value: number, startA: number, endA: number, startB: number, endB: number, clamp?: boolean)
Maps a number from one range to another
Parameters
value number
The input value to be mapped.
startA number
Current value range start.
endA number
Current value range end.
startB number
Target range start.
endB number
Target range end.
clamp boolean
(optional) Clamp the mapped value between target range. Defaults to false.
Return type
number
Examples
MAP(50, 0, 100, 0, 1) // => 0.5 // Map value 50 in range (0-100) to range (0-1)
MAP(50, 0, 100, -100, 100) // => 0 // Map value 50 in range (0-100) to range (-100-100)
MAP(50, 0, 100, 100, 200) // => 150 // Map value 50 in range (0-100) to range (100-200)
MAP(101, 0, 100, 0, 1) // => 1.01 // Map value 101 in range (0-100) to range (0-1)
MAP(101, 0, 100, 0, 1, true) // => 1 // Map and clamp value 101 in range (0-100) to range (0-1)
SOLVE
SOLVE(fn: (x: number) => number, target: number, start?: number, step?: number, accuracy?: number, maxIterations?: number)
Attempt to find the input value that produces a given target result for a given function.
Parameters
fn (x: number) => number
The function to find the input for. Must have exactly one parameter (number) and must return a number.
target number
The target result value.
start number
(optional) The input to start from. Defaults to 0.
step number
(optional) The initial step size. Defaults to 100.
accuracy number
(optional) The desired accuracy. If 0 is specified, the result must match exactly. Defaults to 1e-15.
maxIterations number
(optional) The maximum number of attempts to solve for the input. Defaults to 100.
Return type
number
Examples
// Solves x + 1 = 5:
SOLVE(x => x + 1, 5) // => 4
// Solves SQRT(x) = 5:
SOLVE(x => SQRT(x), 5) // => 25
// Solves x for result 9 (x * x = 9):
SOLVE(x => x * x, 9) // => 3
// Solves x for result 9 (x * x = 9) with all parameters:
SOLVE(
x => x * x, // Function
9, // Goal
0, // Start
10, // Initial step size
0, // Accuracy (0 = exact)
10) // Max attempts
RANDOM
RANDOM(start?: number, end?: number)
Returns a floating-point, pseudo-random number in the range 0-1 (inclusive of 0, but not 1). If you pass in one parameter, it will return a random number between 0 and that number. When you pass in two parameters, it will return a random number between those two numbers.
Parameters
start number
(optional) The lower limit. Defaults to 0.
end number
(optional) The upper limit. Defaults to 1. The value itself is not included in the range.
Return type
number
Examples
RANDOM() // => 0.0057329822878045
RANDOM() // => 0.7147417324368315
RANDOM(100) // => 12.17964480760092
RANDOM(100) // => 60.03195273106292
RANDOM(-10, 10) // => 8.961852679166032
RANDOM(-10, 10) // => -3.672503867219734
RANDOMINT
RANDOMINT(start: number, end: number)
Returns an integer, pseudo-random number in a given range. It will return a random number between those two numbers, including those two numbers.
Parameters
start number
The lower limit.
end number
The upper limit.
Return type
number
Examples
RANDOMINT(0, 2) // => 0 (Result can be 0, 1, or 2)
RANDOMINT(0, 100) // => 78
RANDOMINT(0, 100) // => 48
RANDOMINT(-10, 10) // => 7
RANDOMINT(-10, 10) // => 1
PICK
PICK(array: any[])
Returns an random element from a given array.
Parameters
array any[]
The array.
Return type
any
Examples
PICK([0,1,2]) // => 0 (Result can be 0, 1, or 2)
PICK(cities) // => "London" (from imaginary list of cities)
PLUCK
PLUCK(array: any[])
Returns an random element from a given array, but also removes that element from it!
Parameters
array any[]
The array.
Return type
any
Examples
// Example 1:
const nums = [0, 1, 2, 3, 4];
PLUCK(nums) // => 3
// nums is now [0, 1, 2, 4]
// Example 2:
let cities = ["London", "Paris", "New York", "Tokyo"];
PLUCK(cities) // => "New York"
// cities is now ["London", "Paris", "Tokyo"]
RANGE
RANGE(start: number, end: number, step?: number)
Creates an array of numbers in a given range.
Parameters
start number
The lower limit.
end number
The upper limit.
step number
(optional) The step size. Defaults to 1.
Return type
number[]
Examples
RANGE(0, 2) // => [0, 1, 2]
RANGE(2, 0) // => [2, 1, 0]
// With step size of 2:
RANGE(0, 10, 2) // => [0, 2, 4, 6, 8, 10]
RANGE(10, 0, 2) // => [10, 8, 6, 4, 2, 0]
GUID
GUID(fill?: number | string)
Returns a globally unique identifier (GUID). Each call will return a different GUID.
Parameters
fill number | string
(optional) Value to fill the result with.
Return type
string
Examples
GUID() // => 3fc60027-b39e-43cb-8580-239a1b2b83f4
GUID() // => 1190795d-f387-487a-8995-49394542821e
GUID(0) // => 00000000-0000-0000-0000-000000000000
GUID(16) // => ffffffff-ffff-ffff-ffff-ffffffffffff
GUID('a') // => aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
EMPTYGUID
EMPTYGUID()
Returns a zero-filled globally unique identifier (GUID). Equal to calling GUID(0).
Parameters
Return type
string
Examples
EMPTYGUID() // => 00000000-0000-0000-0000-000000000000
NOT
NOT(boolean: any)
Negates the specified parameter.
Parameters
boolean any
Value to be negated.
Return type
boolean
Examples
NOT(true) // => false
NOT(false) // => true
FOR
FOR(start: number, end: number, function: function, step?: number)
Iterates over the specified range and executes the specified function for each value. Returns the number of iterations.
Parameters
start number
The start value (inclusive).
end number
The end value (inclusive).
function function
The function to be executed for each value.
step number
(optional) The step value.
Return type
number
Examples
FOR(1, 5, i => console.log(i)) // Will log: '1', '2', '3', '4', '5'
FOR(1, 5, i => console.log(i), 2) // Will log: '1', '3', '5'
REPEAT
REPEAT(count: number, function: function)
Repeats the specified function the specified number of times. Returns the number of iterations.
REPEAT(x, func)
is shorthand for FOR(1, x, func)
.
Parameters
count number
The number of times to repeat the function.
function function
The function to be executed for iteration. The function will be called with the iteration number as the first parameter, starting with 1 and ending with the count.
Return type
number
Examples
REPEAT(3, i => console.log(i)) // Will log: '1', '2', '3'. Note that the index starts from 1.
CLONE
CLONE(obj: any)
Creates a (deep) copy of a given object.
Parameters
obj any
The object to clone.
Return type
any
Examples
CLONE({ a: 1, b: 'hi' }) // => { a: 1, b: 'hi' }
COERCE
COERCE(str: any)
Tries to convert a string to what it represents.
Parameters
str any
The string to coerce.
Return type
any
Examples
COERCE('1') // => 1 // Converted to number
COERCE('1.50') // => 1.5 // Converted to number
COERCE('true') // => true // Converted to boolean
COERCE('{ "a": 3 }') // => { a: 3 } // Converted to an object
CSV2JSON
CSV2JSON(csv: string, options?: { separator?: string, lineSeparator?: string, objects?: boolean, skipHeader?: boolean, coerce?: boolean })
Converts a CSV string to a JSON array. Will try to detect the separator automatically. Default newline character is '\n' - can be overriden with the 'lineSeparator' option.
Parameters
csv string
The CSV string to convert.
options { separator?: string, lineSeparator?: string, objects?: boolean, skipHeader?: boolean, coerce?: boolean }
(optional) The options object.
Return type
{ [key: string]: any; }[]
Examples
CSV2JSON('a,b,c \n 1,2,3 \n 4,5,6') // Auto-detects the , separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]
CSV2JSON('a;b;c \n 1;2;3 \n 4;5;6') // Auto-detects the ; separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]
CSV2JSON('a,b,c \r 1,2,3 \r 4,5,6', { lineSeparator: '\r' })
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]
CSV2JSON('a|b|c\n1|2|3\n4|5|6', { separator: '|' }) // Specify a custom separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]
CSV2JSON('a,b,c\n1,2,3\n4,5,6', { objects: false }) // Disable parsing to objects (includes header in result too)
// => [ ['a', 'b', 'c'], [1, 2, 3], [4, 5, 6]]
CSV2JSON('a,b,c\n1,2,3\n4,5,6', { objects: false, skipHeader: true }) // Same as previous, but omits the header row
// => [ [1, 2, 3], [4, 5, 6]]
Last updated