Expressions can be parsed and executed in one go with the evaluate function.

TIP

When evaluating the same expression multiple times, it is always more performant to use parse to get the parsed expression first then calling execute on with the expression. See Parse & execute for more details.

Example

import { ESCalcLite } from "escalc-lite"

const result = ESCalcLite.evaluate('1 + 2')
console.log(result)
//3

Parameters

Parameters are declared in expression in three potential ways:

• Writing out the parameter name as is e.g. x
• Wrapping the parameter name in square brackets e.g. [x]
• Wrapping the parameter name in braces e.g.

Values for the parameters can be specified in the evaluate call in the second parameter, for example:

import { ESCalcLite } from "escalc-lite"

const result = ESCalcLite.evaluate('1 + x', { params: { x: 100 }})
console.log(result)
//101

Functions

Implementation for custom functions can be specified as the second argument to the evaluate call, for example:

const plusOne: ESCalcLiteExpressionFunction = (args) => {
  const result = args[0].evaluate()
  if (typeof result !== 'number') {
    return null
  }
  return result + 1
}
const result = ESCalcLite.evaluate('PlusOne(10)', {
  functions: { PlusOne: plusOne },
})
console.log(result)
//11

Lazy parameters

If a parameter needs to be calculated on demand it can be provided as a lazy parameter. When executing the expression whenever the parameter is needed, its function is run to retrieve its value.

import { ESCalcLite } from "escalc-lite"

const result = ESCalcLite.evaluate('1 + x', { lazyParams: { x: () => 100 }})
console.log(result)
//101

Options

export type ESCalcLiteEvaluateOptions = Partial<{
  // Map of parameters that are used when executing the expression
  params: Record<string, ESCalcLiteParameter>
  // Map of parameters that are evaluated on demand
  lazyParams: Record<string, ESCalcLiteLazyParameter>
  // Map of functions that are used when executing the expression
  functions: Record<string, ESCalcLiteExpressionFunction>
  // A set of operators that can be overridden to change how they behave when execution an expression
  valueCalculator: ESCalcLiteValueCalculator
  // Factory that creates literals values such as numbers and booleans
  literalFactory: ESCalcLiteLiteralFactory
}>