NCalcJS
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. You may also want to look at the example running on CloudFlare workers https://github.com/ThomasHambach/expression.worker
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
Get the package from npm.org (https://www.npmjs.com/package/ncalcjs) by running
npm i --s ncalcjs
or with yarn
yarn ncalcjs
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 commond inside /src/Grammar
.
antlr4 -Dlanguage=TypeScript NCalc.g4
Contributors
Special thanks to https://github.com/Thaina for creating the basis of this package's ANTLR4 grammar file. Original C# version available at: https://github.com/Thaina/NCalc2/blob/master/grammer/NCalc.g
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.
Expression.worker
Starter kit to run NCalcJS in a cloudflare worker.