exprify 1.0.0 → 1.0.2

package/README.md

@@ -1,135 +1,270 @@
-# Exprify — Math Expression Parser & Evaluator
-
-[![Exprify Social Banner](https://raw.githubusercontent.com/code-hemu/Exprify/refs/heads/main/src/assets/capture.jpg)](https://github.com/code-hemu/Exprify)
-
-Exprify is a JavaScript expression parser and evaluator supporting math operations, variables, and custom functions.
-
-## 🔧 Manual Build
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/code-hemu/Exprify.git
-   cd Exprify
-
-2. Install dependencies and build:
-   ```bash
-   npm install
-   npm run build
-   
-The output will be generated in a dist/ folder.
-
-## 🚀 Quick Start
-### Node.js / ES Modules
-```Javascript
-import Exprify from "exprify";
-const expr = new Exprify();
-console.log(expr.evaluate("5 + 7 * 2")); 
-// → 19
-```
-### Browser (UMD)
-```html
-<script src="exprify.js"></script>
-<script>
-  const expr = new Exprify();
-  console.log(expr.evaluate("10 + 5 * 2"));
-</script>
-```
-## 🧠 Examples
-### ➕ Basic Math
-```Javascript
-expr.evaluate("10 + 5 * 2"); 
-// → 20
-```
-### 🧮 Parentheses
-```Javascript
-expr.evaluate("(10 + 5) * 2"); 
-// → 30
-```
-### 🔢 Variables
-```Javascript
-expr.setVariable("x", 10);
-expr.setVariable("y", 5);
-
-expr.evaluate("x + y * 2");
-// → 20
-```
-### 🔧 Custom Functions
-```Javascript
-expr.addFunction("double", (x) => x * 2);
-
-expr.evaluate("#double(5) + 3");
-// → 13
-```
-
-### 📊 Built-in Functions
-```Javascript
-expr.evaluate("#max(10, 25, 7)"); 
-// → 25
-
-expr.evaluate("#min(10, 25, 7)"); 
-// → 7
-```
-## 🤿 Other Examples
-```Javascript
-//Create a new Exprify object with Exprify class
-const expr = new Exprify();
-
-//Simple Expression evaluation
-console.log(expr.evaluate(`25+5*2`)); // → 35
-
-//Nested expression evaluation
-console.log(expr.evaluate(`((52/8+2)+56*((25/2)*4+(8-2)))*2`)); // → 6289
-
-//BigInt Expression evaluation
-console.log(expr.evaluate(`11n ^2n`)); // → 121n 
-
-//String concatenation: '+' Operator behaves as concatenation operator
-console.log(expr.evaluate(`"Hello " + "World"`)); // → "Hello World"
-
-//Invalid Expression: One operand is a string and another one is number
-console.log(expr.evaluate(`"45" + 5`)); // → datatype error
-
-//Invalid Expression: One operand is a number and another one is boolean
-console.log(expr.evaluate(`45 * true`)); // → datatype error
-
-//Invalid Expression: unclosed quoted text
-console.log(expr.evaluate(`"Hello World `)); // → unclosed error
-```
-
-## 🧩 Built-in Functions
-Exprify has some built-in functions, here is a complete list
-|  Function | Details | Example |
-| - | - |- |
-|**#max(...)**| #max() function returns the largest number of the provided numerical arguments | ```"#max(45,50,20, 4+9*(6+4))" //returns 94 ```|
-|**#min(...)**| #min() function returns the smallest number of the provided numerical arguments | ```"#min(45,50,20, 4+9*(6+4))" //returns 20 ```|
-|**#and(...)** <br> or <br> **#&&**| **#and()** or **#&&** tests each of its arguments , if all are true then it will return true | ```"#and(true , true, false)" //returns false ``` <br> <br> ```"#&&(true , true, false)" //returns false ```|
-|**#or(...)** <br> or <br> **#\|\|** | **#or()** or **#\|\|()** tests each of its arguments , if any of its arguments is true then it will return true | ```"#or(true , true, false)" //returns true ``` <br> <br> ```"#\|\|(true , true, false)" //returns true```|
-|**#not(x)** <br> or <br> **#!**| **#not()** or **#!()** changes 'true' value to a 'false' value and 'false' value to a 'true' value | ```"#not(true)" //returns false ``` <br> <br> ```"#!(true)" //returns false ``` |
-|**#greaterThan(...)** <br> or <br> **#>**| **#greaterThan()** or **#>()** takes 2 parameters and compare if that the 1st parameter is greater than the second parameter or not | ```"#greaterThan(67 , 5)" //returns true ``` <br> <br>```"#>(67 , 5)" //returns true ``` |
-|**#lessThan(...)** <br> or <br> **#<**| **#lessThan()** or **#<()** takes 2 parameters and compare if that the 1st parameter is less than the second parameter or not | ```"#lessThan(67 , 5)" //returns false ``` <br> <br>```"#<(67 , 5)" //returns false ``` |
-|**#isEqual(...)** <br> or <br> **#==**| **#isEqual()** or **#==()** takes 2 parameters and compare if that the both parameter is same numerical value or not | ```"#isEqual(60 , 50+10)" //returns true ``` <br> <br>```"#==(60 , 50+10)" //returns true ``` |
-|**#if(...)**| **#if()** takes 3 parameters. 1st parameter is a condition parameter, if the condition is true then it returns 2nd parameter otherwise it returns 3rd parameter (if the 3rd parameter is not specified then its default value false will be return) | ```"#if(true , 5, 80)" //returns 80 ``` <br> <br> ```"#if(#<(50,100) , '50 is less than 100', '100 is less than 50')" //returns '50 is less than 100' ```|
-
-
-## 📜 License
-Exprify is freely distributable under the terms of the GPL-3.0 License. Copyright (c) [Nirmal Paul](https://github.com/nirmalpaul383/) (N Paul).
-
-
-## 🤝 Contributing
-
-Contributions are welcome!
-
-1. Fork the repo
-
-2. Create your branch:
-   ```bash
-   git checkout -b feature/your-feature
-   
-3. Commit changes:
-   ```bash   
-   git commit -m "Add your feature"
-   
-4. Push and open a PR 🚀
-
-## ⭐ Support
-If you like [this project](https://github.com/code-hemu/Exprify), give it a ⭐ on GitHub! This project is originally made by [Nirmal Paul](https://github.com/nirmalpaul383/) (N Paul) and replicate by [ViewPoint](https://github.com/nirmalpaul383/ViewPoint). The Main Developer's (N Paul) [youtube page](https://www.youtube.com/channel/UCY6JY8bTlR7hZEvhy6Pldxg/), [facebook page](https://facebook.com/a.new.way.Technical/).
-
+# Exprify
+
+[![Exprify Social Banner](https://raw.githubusercontent.com/code-hemu/Exprify/refs/heads/main/src/assets/capture.jpg)](https://github.com/code-hemu/Exprify)
+
+Exprify is a JavaScript expression parser and evaluator for math-heavy apps. It supports arithmetic, variables, custom functions, unit conversion, matrices, complex numbers, symbolic helpers, and a growing set of linear algebra utilities.
+
+## Installation
+
+```bash
+npm install exprify
+```
+
+## Quick Start
+
+```js
+import Exprify from "exprify";
+
+const expr = new Exprify();
+
+console.log(expr.evaluate("5 + 7 * 2"));
+// 19
+
+expr.setVariable("x", 10);
+console.log(expr.evaluate("x + 5"));
+// 15
+```
+
+## Browser Usage
+
+```html
+<script src="https://unpkg.com/exprify"></script>
+<script>
+  const expr = new Exprify();
+  console.log(expr.evaluate("(10 + 5) * 2"));
+</script>
+```
+
+`unpkg` resolves to the browser bundle from `dist/exprify.min.js`.
+
+## API
+
+### `new Exprify()`
+
+Creates a new evaluator instance with isolated state for:
+
+- variables
+- functions
+- units
+- compiled-expression cache
+
+### `expr.evaluate(expression)`
+
+Parses and evaluates an expression string.
+
+```js
+expr.evaluate("10 + 5 * 2");
+// 20
+```
+
+### `expr.parse(expression)`
+
+Returns `{ tokens, ast }`.
+
+```js
+const parsed = expr.parse("2 inch to cm");
+console.log(parsed.tokens);
+console.log(parsed.ast);
+```
+
+### `expr.compile(expression)`
+
+Compiles an expression once and returns a reusable function.
+
+```js
+const area = expr.compile("width * height");
+
+console.log(area({ width: 6, height: 4 }));
+// 24
+```
+
+### `expr.setVariable(name, value)` / `expr.getVariable(name)`
+
+Stores and reuses values across evaluations.
+
+```js
+expr.setVariable("x", 10);
+expr.setVariable("y", 5);
+
+console.log(expr.evaluate("x + y * 2"));
+// 20
+```
+
+### `expr.addFunction(name, fn)`
+
+Registers a custom JavaScript function.
+
+```js
+expr.addFunction("double", (n) => n * 2);
+
+console.log(expr.evaluate("double(5) + 3"));
+// 13
+```
+
+### Inline Function Definitions
+
+You can define functions inside expressions.
+
+```js
+expr.evaluate("hyp(a, b) = sqrt(a ^ 2 + b ^ 2)");
+
+console.log(expr.evaluate("hyp(3, 4)"));
+// 5
+```
+
+## Features
+
+### Arithmetic
+
+```js
+expr.evaluate("2 + 3 * 4");
+// 14
+
+expr.evaluate("(2 + 3) * 4");
+// 20
+
+expr.evaluate("11n ^ 2n");
+// 121n
+```
+
+### Strings, Booleans, Complex Numbers
+
+```js
+expr.evaluate('"Hello " + "World"');
+// "Hello World"
+
+expr.evaluate("true && false");
+// false
+
+expr.evaluate("9 / 3 + 2i");
+// "3 + 2i"
+```
+
+### Unit Conversion
+
+```js
+expr.evaluate("2 inch to cm");
+// "5.08 cm"
+
+expr.evaluate("5 cm + 2 inch");
+// "10.08 cm"
+
+expr.evaluate("5cm + 0.2 m in inch");
+// "9.84251968503937 inch"
+
+expr.evaluate("a = 5.08 cm + 2 inch");
+expr.evaluate("a to inch");
+// "4 inch"
+```
+
+### Matrices
+
+Exprify supports matrix literals with `;` as row separators.
+
+```js
+expr.evaluate("a = [1, 2, 3; 4, 5, 6]");
+// {"exprify":"DenseMatrix","data":[[1,2,3],[4,5,6]],"size":[2,3]}
+
+expr.evaluate("a[2, 3]");
+// 6
+
+expr.evaluate("a[1:2, 2]");
+// "2\n5"
+
+expr.evaluate("a[3, 1:3] = [7, 8, 9]");
+// "7\t8\t9"
+
+expr.evaluate("det([-1, 2; 3, 1])");
+// -7
+```
+
+### Linear Algebra Helpers
+
+```js
+expr.evaluate("lup([[2, 1], [1, 4]])");
+// {"L":{"exprify":"DenseMatrix",...},"U":{"exprify":"DenseMatrix",...},"p":[0,1]}
+
+expr.evaluate("lyap([[-2, 0], [1, -4]], [[3, 1], [1, 3]])");
+// {"exprify":"DenseMatrix","data":[[0.75,0.2916666666666667],[0.2916666666666667,0.44791666666666663]],"size":[2,2]}
+
+expr.evaluate("qr([[1, -1, 4], [1, 4, -2], [1, 4, 2], [1, -1, 0]])");
+// {"Q":{"exprify":"DenseMatrix",...},"R":{"exprify":"DenseMatrix",...}}
+
+expr.evaluate("polynomialRoot(-6, 11, -6, 1)");
+// [1,3,2]
+```
+
+Available helpers currently include `det`, `lsolve`, `lup`, `lyap`, `qr`, and `polynomialRoot`.
+
+### Algebra Helpers
+
+```js
+expr.evaluate('simplify("2x + x")');
+// "3 * x"
+
+expr.evaluate('derivative("2x^2 + 3x + 4", "x")');
+// "4 * x + 3"
+
+expr.evaluate('rationalize("2x/y - y/(x+1)", true)');
+// {"numerator":"2 * x ^ 2 + 2 * x - y ^ 2","denominator":"x * y + y","coefficients":[],"variables":["x","y"],"expression":"(2 * x ^ 2 + 2 * x - y ^ 2) / (x * y + y)"}
+```
+
+### Parse and AST Utilities
+
+```js
+expr.evaluate('leafCount("e^(i*pi)-1")');
+// 4
+
+expr.evaluate('leafCount(parse("{a: 22/7, b: 10^(1/2)}"))');
+// 5
+```
+
+### Built-in Functions
+
+Common built-ins include:
+
+- `max`, `min`, `abs`, `round`, `floor`, `ceil`, `sqrt`, `pow`
+- `sin`, `cos`, `tan`, `asin`, `acos`, `atan`
+- `log`, `log10`, `exp`, `random`
+- `clamp`, `if`, `length`, `typeof`
+- `det`, `lsolve`, `lup`, `lyap`, `qr`, `polynomialRoot`
+- `simplify`, `derivative`, `rationalize`, `leafCount`, `parse`
+
+## Return Types
+
+Depending on the expression, `evaluate()` may return:
+
+- numbers / bigint / booleans
+- strings
+- formatted unit strings like `"5.08 cm"`
+- formatted complex strings like `"3 + 2i"`
+- matrix wrapper JSON strings such as `{"exprify":"DenseMatrix",...}`
+- JSON strings for structured helper outputs like `lup()` or `rationalize(..., true)`
+
+## Manual Build
+
+```bash
+git clone https://github.com/code-hemu/Exprify.git
+cd Exprify
+npm install
+npm run build
+```
+
+Build output is written to `dist/`.
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+Exprify is licensed under GPL-3.0. Copyright (c) [Nirmal Paul](https://github.com/nirmalpaul383/).
+
+## Contributing
+
+1. Fork the repository.
+2. Create a branch: `git checkout -b feature/your-feature`
+3. Commit your changes: `git commit -m "Add your feature"`
+4. Push your branch and open a pull request.