Swell's formula engine is used to evaluate expressions in the context of requests and record data. Formulas are able to handle basic logic, arithmetic, and string manipulation, and they can be applied when defining custom fields on any of Swell's default models or used within your own custom models.

Supported formula usage within model definitions:

  • Fields can be based on a formula
  • Field default values can use $formula
  • Field increment.pattern can also us $formula

Supported formula usage within model features:

  • Task schedule can use formula

Supported formula usage within model framework:

  • Used to validate formula fields (that's so meta)

Below is a list of supported formula based on type.

FormulaDescriptionImplementationExample
stringConverts an object into a string. Returns empty string for undefined valueswellstring(3) ⇒ ‘3’, string(null) ⇒ ‘’ string(undefined) ⇒ ‘’
lowerConvert the string to lowercaseswelllower(’Hello World’) ⇒ ‘hello world’
upperConverts the string to uppercaseswellupper(’Hello World’) ⇒ ‘HELLO WORLD’
trimTrims whitespace off the ends of a stringswelltrim(’ oops ‘) ⇒ ‘oops’
alphanumGenerates a random alpha-numeric string of specified lengthswellalphanum(5, ‘ASDF’) ⇒ ‘DASDD’
slugConverts a string into something that can be used as a URL slugswellslug(’one@two.three’) ⇒ ‘one-two-three’
underscoreConvert the string to underscore formatswellunderscore(’foo-bar’) ⇒ ‘foo_bar’
truncateTruncates the stringswelltruncate(’A long time ago in a galaxy far, far away’, 15) ⇒ ‘A long time ago…’
md5Generates an MD5 hashswellmd5(string)
matchTests if the string matches the regexswellmatch(/foo/, ‘foobar’) ⇒ true
replaceString replacement via regexswellreplace(/foo/, ‘foobar’, ‘goo’) ⇒ ‘goobar’
FormulaDescriptionImplmetationExample
lengthReturns the length of an array or stringswelllength([1, 2]) ⇒ 2, length (’foo’) ⇒ 3
containsReturns true if the array, string or object contains the valueswellcontains(3, [1, 2, 3] ⇒ true, contains(1, {a: 1, b: 2} ⇒ true
joinJoins an array of items by delimiterswelljoin(’-’, ‘runs’, ‘in’, ‘circles’) ⇒ ‘runs-in-circles’
array_some_value_matchDetermines whether there is a matching array elementswellarray_some_value_match( [{price: 10}, {price: 5}], ‘price’, ‘≥’, 8 ) ⇒ true
sumCalculates the sum value of an arraymathjssum([1, 2, 3, 4]) ⇒ 10
meanCalculates the average of an arraymathjsmean([1, 2, 3, 4]) ⇒ 2.5
minCalculates the minimum value in an arraymathjsmin([1, 2, 3, 4]) ⇒ 1
maxCalculates the maximum value in an arraymathjsmax([1, 2, 3, 4]) ⇒ 4
FormulaDescriptionImplementationExample
dateConverts value to a Date (epoch time). Returns the current date/time if the value is undefinedswelldate(null) ⇒ (current date/time), date(’2022-09-02T21:46:05.064Z') ⇒ (date), date(1662154892571) ⇒ (date)
nowThe current date/time (epoch time)swellnow() ⇒ (current date/time)
yearReturns the year part of the dateswellyear(undefined) ⇒ 2022, year(’2021-01-04’) ⇒ 2021
monthReturns the month part of the date (zero-based index)swellmonth(undefined) ⇒ 8 // september 16, 2022, month(’2021-01-04’) ⇒ 0
dayReturns the day of month part of the dateswellday(undefined) ⇒ 16 // september 16, 2022, day(’2021-01-04’) ⇒ 4
FormulaDescriptionImplementationExample
addAdds numbers, concats stringsswell3 + 4 = 7, ’pew’ + ‘pew’ ⇒ ‘pewpew’
subtractSubtract numbersswell3 - 4 ⇒ -1
multiplyMultiplicationswell3 * 4 ⇒ 12
divideDivisionswell12 / 3 ⇒ 4
absAbsolute valuemathjsabs(-4) ⇒ 4
modModulus (remainder)mathjsmod(12, 5) ⇒ 2
roundRounds a value to the nearest integer or decimal.mathjsround(3.3) ⇒ 3, round(3.33, 1) ⇒ 3.3
random / randomIntGenerates a random number between min and maxmathjsrandomInt(1, 10) ⇒ 5, randomInt(1, 10) ⇒ 3
ceilCeilingmathjsceil(4.2) ⇒ 5
floorFloormathjsfloor(4.2) ⇒ 4
FormulaDescriptionImplementationExample
booleanConverts the value to a booleanmathjsboolean(0) ⇒ false
definedDetermines whether the value is definedswelldefined(null) ⇒ false, defined(’pew’) ⇒ true
ifConditional if/elseswellif(true, 1, 2) ⇒ 1, if(false, 1, 2) ⇒ 2
caseAn if/else with many casesswellcase(true, 1, true, 2, 3) ⇒ 1, case(false, 1, true, 2, 3) ⇒ 2, case(false, 1, false, 2, 3) ⇒ 3
notLogical not.swellnot(true) ⇒ false
andLogical and. Supports multiple arguments.swelland(true, false, ‘hey’) ⇒ false
orLogical or. Supports multiple arguments.swellor(true, false, ‘bye’) ⇒ true
equalEqualsswell3 == 3 ⇒ true
unequalNot equalsswell3 ≠ 3 ⇒ false
largerComparisonswell3 > 4 ⇒ false
largerEqComparisonswell3 ≥ 4 ⇒ false
smallerComparisonswell3 < 4 ⇒ true
smallerEqComparisonswell3 ≤ 4 ⇒ true
FormulaDescriptionImplementationExample
trueconstantmathjstrue
falseconstantmathjsfalse
nullconstantmathjsnull