Formulon




Formulon is a Parser for Salesforce Formulas completely written in ECMA Script 2015. It is the engine behind formulon.io.

Featured on Phil's Tip of the Week

Use Cases

- Test your Salesforce formulas using the web interface without the need of creating records
- Parse formula input programmatically and evaluate correctness outside of a Salesforce org
- In general if you use the Metadata API to add/change formulas, you could benefit from parsing formulas before submitting back to Salesforce

Usage

$3

This method will return a object holding value and its metadata

``javascript
import { parse } from 'formulon'
`

#### Examples

`javascript
parse('IF(TRUE, "True String", "False String")')
// {
// type: 'literal',
// value: 'True String',
// dataType: 'text',
// options: { length: 11 }
// }
`

type: Metadata from the parser (always literal)
value: The value of the result always as a string
dataType: The type of the return (currently number, text, checkbox, date, time, datetime, geolocation or null)
options: different options per data type

#### Data Types

Currently the following data types are supported (naming is taken from the Salesforce Field Types):

- Number (Integer or Float depending on the options)
- Text
- Checkbox (TRUE or FALSE)
- Date (as UTC Date with time components set to 0)
- Time (as UTC Date with date set to 1970-01-01)
- Datetime (as UTC Date)
- Geolocation (as lat, long array)
- Null (js null value)

#### Options

Options depend on the data type:

##### Number

- Length: Number of digits to the left of the decimal point
- Scale: Number of digits to the right of the decimal point

##### Text

- Length: Number of characters

##### Checkbox

no options

#### Errors

Whenever an error occurs, an according object is returned:

`javascript
parse('IF(TRUE)')
// {
// type: 'error',
// errorType: 'ArgumentError',
// message: "Incorrect number of parameters for function 'IF()'. Expected 3, received 1",
// function: 'if',
// expected: 3,
// received: 1,
// }
`

#### Identifiers (Variables)

It's possible to specify formulas that contain variables. In that case pass the value of the variable in as a second argument:

`javascript
parse('IF(Variable__c, "True String", "False String")', {Variable__c: {type: 'literal', dataType: 'checkbox', value: true}})
// {
// type: 'literal',
// value: 'True String',
// dataType: 'text',
// options: { length: 11 }
// }
`

You'll have to provide the variable in the form:

`javascript
{
type: 'literal',
value: ,
dataType: ,
options:
}
`

$3

Utility function that returns a list of used variables

`javascript
extract('IF(Variable__c, Variable__c, AnotherVariable__c)')
// [ 'Variable__c', 'AnotherVariable__c' ]
`

$3

Return the abstract syntax tree built from the formula.

`javascript
ast('IF(Variable__c, "True String", "False String")')
// {
// "type": "callExpression",
// "id": "if",
// "arguments": [
// {
// "type": "identifier",
// "name": "Variable__c"
// },
// {
// "type": "literal",
// "value": "True String",
// "dataType": "text",
// "options": {
// "length": 11
// }
// },
// {
// "type": "literal",
// "value": "False String",
// "dataType": "text",
// "options": {
// "length": 12
// }
// }
// ]
// }
``

Contributors

Formulon exists thanks to the following people who have contributed.

- Jordan Henderson
- Leif Gensert
- James Melville
- Michael Mason
- Kyle Crouse
- Austin Turner