json-formula

JsonFormula

Class represents an instance of a JsonFormula Expression that can be executed later on with multiple instances of JSON Data. The instance of the class has a search function that can be used to evaluate the expression on a json payload.

Kind: global class

new JsonFormula([customFunctions], [stringToNumber], [debug])

Param Type Default Description
[customFunctions] object {} custom functions needed by a hosting application.
[stringToNumber] function 'null' A function that converts string values to numbers. Can be used to convert currencies/dates to numbers
[debug] array [] will be populated with any errors/warnings

jsonFormula.search(expression, json, [globals], [language]) ⇒ \*

Evaluates the JsonFormula on a particular json payload and return the result

Kind: instance method of JsonFormula
Returns: \* - the result of the expression being evaluated

Param Type Default Description
expression string   the json-formula expression to evaluate
json object | array   the json data on which the expression needs to be evaluated
[globals] object {} global objects that can be accessed via custom functions.
[language] string "en-US" BCP-47 language tag

Example

const jf = new JsonFormula();
const result = jf.search('toDate(d) | day(@) & "/" & month(@)', {d: "2025-11-12"});
// returns "12/11"

jsonFormula.run(ast, json, [language], globals) ⇒ \*

Execute a previously compiled expression against a json object and return the result. Use this method for better performance when you will evaluate the same expression multiple times with different data.

Kind: instance method of JsonFormula
Returns: \* - the result of the expression being evaluated

Param Type Default Description
ast object   The abstract syntax tree returned from compile()
json object | array   the json data on which the expression needs to be evaluated
[language] string "en-US" BCP-47 language tag
globals \*   set of objects available in global scope

Example

const globals = {
  $days: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
};
const jf = new JsonFormula();
const ast = jf.compile('value($days, num)', ['$days']); // compile the expression once
const result1 = jf.run(ast, {num: 2}, 'en-US', globals); // returns "Wed"
const result2 = jf.run(ast, {num: 3}, 'en-US', globals); // returns "Thu"

jsonFormula.compile(expression, [allowedGlobalNames])

Creates a compiled expression that can be executed later on with some data.

Kind: instance method of JsonFormula

Param Type Default Description
expression string   the expression to evaluate
[allowedGlobalNames] Array.<string> [] An array of names of the global variables being used in the expression.

jsonFormula(json, globals, expression, [customFunctions], [stringToNumber], [debug], [language]) ⇒ \*

Compile and execute a json-formula expression. If executing the same expression multiple times, it is more efficient to create a class instance of JsonFormula and call the search() method or the compile()/run() methods multiple times.

Kind: global function
Returns: \* - the result of the expression being evaluated

Param Type Default Description
json object | array   the json data on which the expression needs to be evaluated
globals object   global objects that can be accessed via custom functions.
expression string   the expression to evaluate
[customFunctions] object {} custom functions needed by a hosting application.
[stringToNumber] function 'null' A function that converts string values to numbers. Can be used to convert currencies/dates to numbers
[debug] array [] will be populated with any errors/warnings
[language] string "en-US" BCP-47 language tag

CustomFunctionDefinition : object

Kind: global typedef
Properties

Name Type Description
_func function The function implementation
[_signature] array Function signature metadata

Example

// simple custom functions definition
  const customFunctions = {
    true_fn: {
      _func: () => true,
      _signature: [],
    },
    false_fn: {
      _func: () => false,
      _signature: [],
    },
  };

Example

// custom function with a signature for its parameters
  const customFunctions = {
    padEnd: {
      _func: args => {
        const src = args[0];
        const length = args[1];
        const padChar = args[2];
        if (Array.isArray(src)) return src.map(s => s.padEnd(length, padChar));
        return src.padEnd(length, padChar);
      },
      _signature: [
        { types: [TYPE_STRING, TYPE_ARRAY_STRING] },
        { types: [TYPE_NUMBER] },
        { types: [TYPE_STRING] },
      ],
    }
  }
  // May also register functions is via the `register()` or `registerWithParams()` methods. e.g.

   const regFormula = `${register("${fn_name}", &${code})`;
   // Run the registration formula after which, the registered function may be called
   this.search(regFormula, {});

globals : object

An object where each key MUST begin with a $ character, representing global variables that can be accessed inside a json-formula expression. The value of each key can be of any data type supported by json.

Kind: global typedef
Example

const globals = {
  $num: 42,
  $arr: [1, 2, 3],
  $days: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
};
jsonFormula({}, globals, '$arr * $num') // returns [42, 84, 126]
This site is open source. Improve this page.