@healthstudyclub/ncalc-ts v1.0.1

ncalc-ts

NCalc is a mathematical expressions evaluator in JavaScript/TypeScript. NCalc can parse any expression and evaluate the result, including static or dynamic parameters and custom functions.

Project Description

Browser Support

In theory, all browsers supporting ECMAScript 5.1.

In practice, this target has been extensively tested against:

• Firefox 34.0.5
• Safari 8.0.2
• Chrome 39.0.2171
• Explorer 11.0.3

Is NodeJS supported?

The package has been extensively tested against Node.js 14 LTS.

Installation

npm i --s @healthstudyclub/ncalc-ts

or with yarn

yarn @healthstudyclub/ncalc-ts

Usage

For documentation here is the table of content:

• description: overall concepts, usage and extensibility points
• operators: available standard operators and structures
• functions: list of already implemented functions
• parameters: on how to use parameters expressions

Basic

import {Expression} from 'ncalcjs';
const e = new Expression('2 + 3 * 5');
console.log(e.Evaluate()); // 17

Custom Functions

The API compared to C# NCalc is a little different. In NCalcJS you define custom functions in the following way. Each function is expected to be of the type EvaluateFunctionHandler.

const e = new Expression('SecretOperation(3, 6)');

e.EvaluateFunction['SecretOperation'] = (args: FunctionArgs) => {
  args.Result = args.Parameters[0].Evaluate() + args.Parameters[1].Evaluate();
};
console.log(e.Evaluate()); // 9

Handling Errors

You can use the method Expression.HasErrors() to check for any errors that are present in your expression. The errors details are stored in Expression.errors.

import {Expression} from 'ncalcjs';
const e = new Expression('2 + 3 * 5');
if (e.HasErrors()) {
  console.error(e.errors);
}

Known Issues

• Round does not return the correct value

Building

Install all dependencies

npm install

Before we can run our build, we need to install ts-patch that will change our paths configured in tsconfig.json. Note that you have to run this every time after running npm install.

npm run prepare

Build the distribution version

npm run build

ANTLR & Grammar

Note that the files, except for NCalc.g4 in /src/Grammar are automatically generated. Any changes you wish to make there are to be made in NCalc.g4. You will need Java runtime installed on your system to generate these files.

To update the generated files, run this command inside /src/Grammar.

npm run grammar

Contributors

Special thanks to:

• ThomasHambach for creating NcalcJS, the basis for this package.

Related projects

NCalc

NCalc C# implementation.

NCalc-Async

Pure asynchronous C# implementation of NCalc by Peter Liljenberg.

PanoramicData.NCalcExtensions

Extension functions for NCalc in C# to handle many general functions,
including string functions, switch, if, in, typeOf, cast etc.
Developed by David, Dan and all at Panoramic Data.