Skip to content

a lightweight and precise math expression parser and evaluator for JavaScript and TypeScript

License

Notifications You must be signed in to change notification settings

olamide203/hyoka

Repository files navigation

hyoka

Version License

hyoka

hyoka is a simple math expression parser and evaluator for JavaScript and TypeScript. it uses decimal.js to ensure precision of floating point calculations.

Features

  • Supports implicit multiplication and parenthesis grouping
  • Binary and unary operators are supported
  • Supports mathematical functions
  • Precision and rounding mode can be configured

Installation

This library can be used in both node.js and in the browser.

Using npm:

npm install hyoka

Using yarn:

yarn add hyoka

in the browser:

  • UMD
<script src="https://cdn.jsdelivr.net/npm/hyoka@latest/dist/umd/hyoka.js"></script>
  • ESM
<script src="https://cdn.jsdelivr.net/npm/hyoka@latest/dist/esm/hyoka.mjs" type="module"></script>

Usage

// using ES6 import
import {Expression} from 'hyoka';
// or using require
const { Expression } = require('hyoka');
new Expression('0.1 + 0.2').evaluate(); // 0.3
new Expression('2 * 6 / 3').evaluate(); // 4

// using unary prefix operators
new Expression('- 1 + 2').evaluate(); // 1
new Expression('+ 1 - - 2').evaluate(); // 3

// implicit multiplication
new Expression('2(6 / 3)').evaluate(); // 4

//Trig Functions
new Expression('sin(π)').evaluate(); // 0
new Expression('cos(pi / 2)').evaluate(); // -0.5

// Even more complex expressions
new Expression('2(4(6 / 3 + 2) + 2^3 / - 2(2.5!))').evaluate(); //5.413192236417259652

Configuration

hyoka configuration extends that of decimal.js. this means that all configuration options of decimal.js are available. the following configuration options are available:

  • precision: the number of digits of precision to use
  • rounding: the rounding mode to use
  • modulo: the modulo to use
  • toExpNeg: the exponent of 10 to use for negative zero
  • toExpPos: the exponent of 10 to use for positive zero
  • minE: the minimum exponent value
  • maxE: the maximum exponent value
  • crypto: whether to use the crypto module for random number generation
  • angles: the unit of angles to use for trig functions
  • decimalPlaces: the number of decimal places of returned value

The config options can be set using the config method on the Expression class:

import {Expression} from 'hyoka';
Expression.config({
  precision: 20,
  rounding: 4,
  angles: 'degrees'
});

new Expression('sin(30)').evaluate(); // 0.5

config options can also be passed to the evaluate method. this will override the global config options for that evaluation only:

import {Expression} from 'hyoka';
Expression.config({
  precision: 20,
  rounding: 4,
  angles: 'degrees'
});

// using local config options
new Expression('sin(π/6)').evaluate({angles: 'radians'}); // 0.5
new Expression('1/3').evaluate({decimalPlaces: 3}); // 0.333

// using global config options
new Expression('sin(30)').evaluate(); // 0.5

Supported Operators

Operator Description type Associativity
+ Addition Binary Infix Left
- Subtraction Binary Infix Left
* Multiplication Binary Infix Left
/ Division Binary Infix Left
% Modulo Binary Infix Left
^ Exponentiation Binary Infix Right
- Unary minus Unary Prefix
+ Unary plus Unary Prefix
! Factorial Unary Postfix

Supported Functions

Function Description
acos returns the inverse cosine of an expression
asin returns the inverse sine of an expression
atan returns the inverse tangent of an expression
cos returns the cosine of an expression
gammln returns the natural log of Γ(x) where x is a valid expression
max returns the maximum value from a set of expressions
min returns the minimum value from a set of expressions
sin returns the sine of an expression
tan returns the tangent of an expression
ln returns the natural log of an expression