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

parse

This method will return a object holding value and its metadata

import { parse } from 'formulon'

Examples

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:

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:

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:

{
  type: 'literal',
  value: <the actual value as a JS type>,
  dataType: <the salesforce field type specified above>,
  options: <salesforce field options>
}

extract

Utility function that returns a list of used variables

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

ast

Return the abstract syntax tree built from the formula.

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.

leifg / formulon