Backend API
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.
| Formula | Description | Implementation | Example |
| string | Converts an object into a string. Returns empty string for undefined value | swell | string(3) ⇒ ‘3’, string(null) ⇒ ‘’ string(undefined) ⇒ ‘’ |
| lower | Convert the string to lowercase | swell | lower(’Hello World’) ⇒ ‘hello world’ |
| upper | Converts the string to uppercase | swell | upper(’Hello World’) ⇒ ‘HELLO WORLD’ |
| trim | Trims whitespace off the ends of a string | swell | trim(’ oops ‘) ⇒ ‘oops’ |
| alphanum | Generates a random alpha-numeric string of specified length | swell | alphanum(5, ‘ASDF’) ⇒ ‘DASDD’ |
| slug | Converts a string into something that can be used as a URL slug | swell | slug(’one@two.three’) ⇒ ‘one-two-three’ |
| underscore | Convert the string to underscore format | swell | underscore(’foo-bar’) ⇒ ‘foo_bar’ |
| truncate | Truncates the string | swell | truncate(’A long time ago in a galaxy far, far away’, 15) ⇒ ‘A long time ago…’ |
| md5 | Generates an MD5 hash | swell | md5(string) |
| match | Tests if the string matches the regex | swell | match(/foo/, ‘foobar’) ⇒ true |
| replace | String replacement via regex | swell | replace(/foo/, ‘foobar’, ‘goo’) ⇒ ‘goobar’ |
| Formula | Description | Implmetation | Example |
| length | Returns the length of an array or string | swell | length([1, 2]) ⇒ 2, length (’foo’) ⇒ 3 |
| contains | Returns true if the array, string or object contains the value | swell | contains(3, [1, 2, 3] ⇒ true, contains(1, {a: 1, b: 2} ⇒ true |
| join | Joins an array of items by delimiter | swell | join(’-’, ‘runs’, ‘in’, ‘circles’) ⇒ ‘runs-in-circles’ |
| array_some_value_match | Determines whether there is a matching array element | swell | array_some_value_match( [{price: 10}, {price: 5}], ‘price’, ‘≥’, 8 ) ⇒ true |
| sum | Calculates the sum value of an array | mathjs | sum([1, 2, 3, 4]) ⇒ 10 |
| mean | Calculates the average of an array | mathjs | mean([1, 2, 3, 4]) ⇒ 2.5 |
| min | Calculates the minimum value in an array | mathjs | min([1, 2, 3, 4]) ⇒ 1 |
| max | Calculates the maximum value in an array | mathjs | max([1, 2, 3, 4]) ⇒ 4 |
| Formula | Description | Implementation | Example |
| date | Converts value to a Date (epoch time). Returns the current date/time if the value is undefined | swell | date(null) ⇒ (current date/time), date(’2022-09-02T21:46:05.064Z') ⇒ (date), date(1662154892571) ⇒ (date) |
| now | The current date/time (epoch time) | swell | now() ⇒ (current date/time) |
| year | Returns the year part of the date | swell | year(undefined) ⇒ 2022, year(’2021-01-04’) ⇒ 2021 |
| month | Returns the month part of the date (zero-based index) | swell | month(undefined) ⇒ 8 // september 16, 2022, month(’2021-01-04’) ⇒ 0 |
| day | Returns the day of month part of the date | swell | day(undefined) ⇒ 16 // september 16, 2022, day(’2021-01-04’) ⇒ 4 |
| Formula | Description | Implementation | Example |
| add | Adds numbers, concats strings | swell | 3 + 4 = 7, ’pew’ + ‘pew’ ⇒ ‘pewpew’ |
| subtract | Subtract numbers | swell | 3 - 4 ⇒ -1 |
| multiply | Multiplication | swell | 3 * 4 ⇒ 12 |
| divide | Division | swell | 12 / 3 ⇒ 4 |
| abs | Absolute value | mathjs | abs(-4) ⇒ 4 |
| mod | Modulus (remainder) | mathjs | mod(12, 5) ⇒ 2 |
| round | Rounds a value to the nearest integer or decimal. | mathjs | round(3.3) ⇒ 3, round(3.33, 1) ⇒ 3.3 |
| random / randomInt | Generates a random number between min and max | mathjs | randomInt(1, 10) ⇒ 5, randomInt(1, 10) ⇒ 3 |
| ceil | Ceiling | mathjs | ceil(4.2) ⇒ 5 |
| floor | Floor | mathjs | floor(4.2) ⇒ 4 |
| Formula | Description | Implementation | Example |
| boolean | Converts the value to a boolean | mathjs | boolean(0) ⇒ false |
| defined | Determines whether the value is defined | swell | defined(null) ⇒ false, defined(’pew’) ⇒ true |
| if | Conditional if/else | swell | if(true, 1, 2) ⇒ 1, if(false, 1, 2) ⇒ 2 |
| case | An if/else with many cases | swell | case(true, 1, true, 2, 3) ⇒ 1, case(false, 1, true, 2, 3) ⇒ 2, case(false, 1, false, 2, 3) ⇒ 3 |
| not | Logical not. | swell | not(true) ⇒ false |
| and | Logical and. Supports multiple arguments. | swell | and(true, false, ‘hey’) ⇒ false |
| or | Logical or. Supports multiple arguments. | swell | or(true, false, ‘bye’) ⇒ true |
| equal | Equals | swell | 3 == 3 ⇒ true |
| unequal | Not equals | swell | 3 ≠ 3 ⇒ false |
| larger | Comparison | swell | 3 > 4 ⇒ false |
| largerEq | Comparison | swell | 3 ≥ 4 ⇒ false |
| smaller | Comparison | swell | 3 < 4 ⇒ true |
| smallerEq | Comparison | swell | 3 ≤ 4 ⇒ true |
| Formula | Description | Implementation | Example |
| true | constant | mathjs | true |
| false | constant | mathjs | false |
| null | constant | mathjs | null |