exprify 1.0.4 → 1.0.7

package/HISTORY.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows semantic versioning.
+
+## [1.0.5] - 2026-06-12
+
+### Added
+
+- ESLint (v10 flat config) with strict rules, Prettier formatting, and TypeScript JSDoc type checking
+- Husky pre-commit hook with lint-staged for automatic linting and formatting on commit
+- Dependabot config for weekly automated dependency pull requests
+- CodeQL security analysis workflow on push/PR/schedule
+- Bundle size monitoring via size-limit (min.js: 30 KB, esm.js: 60 KB)
+- Jest coverage reporting (`npm run test:coverage`) with CI artifact upload
+- Node.js 24 to CI test matrix (previously 20 and 22 only)
+- `.editorconfig` for cross-editor consistency
+- `// @ts-check` annotations to all 14 source files
+- `engines` field requiring Node >=18
+
+### Changed
+
+- Upgraded Rollup from v2 to v4 with updated plugin versions
+- Replaced rimraf with built-in `fs.rmSync` for the clean script
+- Replaced nodemon with Node.js built-in `--watch` flag for the dev script
+- CI workflow now runs lint, typecheck, size check, and coverage in addition to tests
+- Switched CI workflows to Node 24 for publish and audit jobs
+- Added `--no-warnings` flag to test scripts to suppress ExperimentalWarning
+
+### Fixed
+
+- All ESLint errors (no-unused-vars, no-undef, eqeqeq, prefer-const, camelcase, etc.)
+- All TypeScript type errors (err unknown type, null checks, variable store reference)
+- lint-staged Windows ENOENT error by switching from package.json config to `lint-staged.config.js` with direct `node` invocation
+
+### Removed
+
+- Unused Babel dependencies (@babel/cli, @babel/core, @babel/preset-env)
+- Unused rollup-plugin-strip-banner, glob, and rimraf dev dependencies
+- `overrides` section (test-exclude, glob pins) — no longer needed with Jest 30
+- `nodemon` devDependency (replaced by `node --watch`)
+
+## [1.0.1] - 2026-04-05
+
+### Fixed
+
+- Corrected the import path in `src/index.js` to match the actual filename casing of `src/core/Exprify.js`.
+- Resolved a cross-platform build issue where Rollup failed on Linux-based CI environments because of case-sensitive path resolution.

package/README.md

@@ -1,8 +1,33 @@
-# Exprify
+[![Exprify Banner](https://raw.githubusercontent.com/code-hemu/Exprify/refs/heads/main/docs/assets/capture.jpg)](https://github.com/code-hemu/Exprify)
 
-[![Exprify Social Banner](https://raw.githubusercontent.com/code-hemu/Exprify/refs/heads/main/docs/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.
+**Exprify** (Math **Expr**ession + Simp**lify**) is a fast, lightweight JavaScript expression parser and evaluator. It is designed for math applications, scientific computing, data visualization tools, calculators, and other complex workflows that run in the browser and in Node.js. It supports basic arithmetic, variables, user-defined functions, and built-in operators for comparison, logic, and string manipulation.
+
+
+[![Version](https://img.shields.io/npm/v/exprify)](https://www.npmjs.com/package/exprify)
+[![Downloads](https://img.shields.io/npm/dt/exprify)](https://www.npmjs.com/package/exprify)
+[![License](https://img.shields.io/github/license/code-hemu/exprify)](https://github.com/code-hemu/exprify/blob/master/LICENSE)
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/exprify/badge?style=rounded)](https://www.jsdelivr.com/package/npm/exprify)
+[![unpkg](https://img.shields.io/badge/CDN-unpkg-blue)](https://unpkg.com/exprify)
+[![Issues](https://img.shields.io/github/issues/code-hemu/exprify)](https://github.com/code-hemu/exprify/issues)
+[![Contributors](https://img.shields.io/github/contributors/code-hemu/exprify)](https://github.com/code-hemu/exprify/graphs/contributors)
+[![Sponsor](https://img.shields.io/github/sponsors/code-hemu)](https://github.com/sponsors/code-hemu)
+[![Open Source](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/code-hemu/exprify)
+
+## Features
+
+- **Arithmetic & Variables** - `expr.evaluate("5 + 7 * 2")` · [docs](docs/datatypes/numbers.md)
+- **Unit conversion** - `expr.evaluate("2 inch to cm")` · [docs](docs/datatypes/units.md)
+- **Matrix operations** - `expr.evaluate("det([-1,2;3,1])")` · [docs](docs/datatypes/matrices.md)
+- **Complex numbers** - `expr.evaluate("9/3 + 2i")` · [docs](docs/datatypes/complex_numbers.md)
+- **Symbolic math** - `expr.evaluate('expand("(x+1)^2")')` · [docs](docs/expressions/algebra.md)
+- **Arbitrary precision** - `expr.evaluate('bignumber("0.1") + bignumber("0.2")')` · [docs](docs/datatypes/bignumbers.md)
+- **Exact fractions** - `expr.evaluate("fraction(1,3) + fraction(1,6)")` · [docs](docs/datatypes/fractions.md)
+- **Calculus & statistics** - `expr.evaluate('integral("x^2", 0, 1)')` · [docs](docs/reference/functions.md)
+- **Lambda expressions** - `expr.evaluate('map([1,2,3], x -> x^2)')` · [docs](docs/expressions/customization.md)
+- **Expression chaining** - `c.evaluate("sqrt(x)").evaluate("ans * 2").done()` · [docs](docs/core/chaining.md)
+- **State serialization** - `expr.exportState()` / `expr.importState(state)` · [docs](docs/core/serialization.md)
+- **Degree-mode trig** - `expr.evaluate("sind(90)")` · [docs](docs/reference/functions.md)
 
 ## Installation
 
@@ -12,270 +37,178 @@ npm install exprify
 
 ## Quick Start
 
-**ESM** (Node.js, bundlers):
+**ESM** (Node.js / bundlers):
 
 ```js
 import Exprify from "exprify";
 
 const expr = new Exprify();
 
-console.log(expr.evaluate("5 + 7 * 2"));
-// 19
+expr.evaluate("5 + 7 * 2");        // 19
 
 expr.setVariable("x", 10);
-console.log(expr.evaluate("x + 5"));
-// 15
+expr.evaluate("x + 5");            // 15
 ```
 
-**CommonJS** (`require`):
+**CommonJS:**
 
 ```js
 const Exprify = require("exprify");
 
 const expr = new Exprify();
-console.log(expr.evaluate("5 + 7 * 2"));
-// 19
+expr.evaluate("5 + 7 * 2");        // 19
 ```
 
-## Browser Usage
+**Browser (CDN):**
 
 ```html
 <script src="https://unpkg.com/exprify"></script>
 <script>
   const expr = new Exprify();
-  console.log(expr.evaluate("(10 + 5) * 2"));
+  expr.evaluate("(10 + 5) * 2");   // 30
 </script>
 ```
 
-`unpkg` resolves to the browser bundle from `dist/exprify.min.js`.
-
-## Module Formats
-
-The package ships a separate build for each consumer, and `package.json`'s `exports` field routes each import style to the right file:
-
-| Consumer | Resolved file | Notes |
-| --- | --- | --- |
-| `import Exprify from "exprify"` (ESM) | `dist/exprify.esm.js` | Default export is the `Exprify` class. |
-| `const Exprify = require("exprify")` (CJS) | `dist/exprify.cjs.cjs` | `module.exports` is the `Exprify` class. |
-| `<script src="https://unpkg.com/exprify">` | `dist/exprify.min.js` | UMD build; exposes `Exprify` as a global. |
-| `import "exprify/dist/exprify.js"` (UMD) | `dist/exprify.js` | Unminified UMD for bundlers that prefer it. |
-
-The `.cjs` extension on the CommonJS bundle keeps it loadable as CJS even though the package is `"type": "module"`, so `require()` and `import` both work without configuration.
-
-## API
+## API Reference
 
 ### `new Exprify()`
 
-Creates a new evaluator instance with isolated state for:
+Creates a new evaluator instance with fully isolated state. Each instance maintains its own independent registry of variables, custom functions, unit definitions, and a compiled-expression cache - so multiple instances never interfere with each other.
 
-- variables
-- functions
-- units
-- compiled-expression cache
+```js
+const expr = new Exprify();
+```
 
-### `expr.evaluate(expression)`
+### `expr.evaluate(expression, scope?)`
 
-Parses and evaluates an expression string.
+Parses and evaluates an expression string, returning the computed result. An optional `scope` object lets you pass temporary variable values that apply only to that single call - they do not modify the instance's stored state.
 
 ```js
-expr.evaluate("10 + 5 * 2");
-// 20
+expr.evaluate("10 + 5 * 2");               // 20
+
+expr.setVariable("x", 100);
+expr.evaluate("x + 1", { x: 5 });          // 6  (x = 100 is unchanged)
 ```
 
 ### `expr.parse(expression)`
 
-Returns `{ tokens, ast }`.
+Parses an expression without evaluating it. Returns a `{ tokens, ast }` object containing the raw token list and the abstract syntax tree - useful for debugging, introspection, or building custom tooling on top of the parser.
 
 ```js
-const parsed = expr.parse("2 inch to cm");
-console.log(parsed.tokens);
-console.log(parsed.ast);
+const { tokens, ast } = expr.parse("2 inch to cm");
+// tokens: [...], ast: { type: "UnitConversion", ... }
 ```
 
 ### `expr.compile(expression)`
 
-Compiles an expression once and returns a reusable function.
+Compiles an expression once and returns a reusable callable function. The compiled form skips parsing on every subsequent invocation, making this the right choice for hot paths or any expression evaluated repeatedly with different inputs.
 
 ```js
 const area = expr.compile("width * height");
-
-console.log(area({ width: 6, height: 4 }));
-// 24
+area({ width: 6, height: 4 });             // 24
+area({ width: 3, height: 9 });             // 27
 ```
 
 ### `expr.setVariable(name, value)` / `expr.getVariable(name)`
 
-Stores and reuses values across evaluations.
+Stores a named value that persists across all future evaluations on this instance. `getVariable` retrieves a previously stored value by name.
 
 ```js
 expr.setVariable("x", 10);
 expr.setVariable("y", 5);
+expr.evaluate("x + y * 2");                // 20
 
-console.log(expr.evaluate("x + y * 2"));
-// 20
+expr.getVariable("x");                     // 10
 ```
 
 ### `expr.addFunction(name, fn)`
 
-Registers a custom JavaScript function.
+Registers a plain JavaScript function under a given name, making it available to call inside any expression evaluated on this instance. The function receives its arguments as individual parameters, exactly as written in the expression.
 
 ```js
 expr.addFunction("double", (n) => n * 2);
+expr.evaluate("double(5) + 3");            // 13
 
-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
+expr.addFunction("clamp", (val, lo, hi) => Math.min(Math.max(val, lo), hi));
+expr.evaluate("clamp(150, 0, 100)");       // 100
 ```
 
-### Strings, Booleans, Complex Numbers
-
-```js
-expr.evaluate('"Hello " + "World"');
-// "Hello World"
-
-expr.evaluate("true && false");
-// false
-
-expr.evaluate("9 / 3 + 2i");
-// "3 + 2i"
-```
+### `expr.chain()`
 
-### Unit Conversion
+Returns a fluent `Chain` object for building multi-step calculations. Each call to `.evaluate()` on the chain stores its result in the special variable `ans`, which the next expression can reference directly. Call `.done()` at the end to extract the final value.
 
 ```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"
+const c = expr.chain();
+c.setVariable("x", 25);
+c.evaluate("sqrt(x) + 3");                 // computes 8, stored as ans
+c.evaluate("ans * 2");                     // computes 16, stored as ans
+c.done();                                  // 16
 ```
 
-### 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.exportState()` / `expr.importState(state)`
 
-expr.evaluate("det([-1, 2; 3, 1])");
-// -7
-```
-
-### Linear Algebra Helpers
+Serializes the complete engine state - all variables, registered functions, and unit definitions - into a plain object that can be stored, transmitted, or restored later. `importState` loads a previously exported snapshot into a fresh instance, fully reconstructing that environment.
 
 ```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",...}}
+const state = expr.exportState();
+// { 
+//    variables: { x: 10, y: 5 }, 
+//    functions: ["double", "clamp"], 
+//     units: {...} 
+//  }
 
-expr.evaluate("polynomialRoot(-6, 11, -6, 1)");
-// [1,3,2]
+const expr2 = new Exprify();
+expr2.importState(state);
+expr2.evaluate("x + y");                   // 15
 ```
 
-Available helpers currently include `det`, `lsolve`, `lup`, `lyap`, `qr`, and `polynomialRoot`.
+### Inline Function Definitions
 
-### Algebra Helpers
+Functions can be defined directly inside an expression using the `name(params) = body` syntax. Once defined, they behave exactly like functions registered via `addFunction` and remain available for the lifetime of the instance.
 
 ```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)"}
+expr.evaluate("hyp(a, b) = sqrt(a^2 + b^2)");
+expr.evaluate("hyp(3, 4)");                // 5
+expr.evaluate("hyp(5, 12)");              // 13
 ```
 
-### 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
-```
+This is particularly convenient for one-off helpers that do not warrant a full `addFunction` call, or for expressions that define and immediately use a function in a single evaluation step.
 
-### Built-in Functions
+## Built-in Functions (Selected)
 
-Common built-ins include:
+| Function | Description | Example | Result |
+|---|---|---|---|
+| `abs` | Absolute value | `abs(-5)` | `5` |
+| `round` | Round to nearest integer | `round(3.7)` | `4` |
+| `floor` | Round down | `floor(3.7)` | `3` |
+| `ceil` | Round up | `ceil(3.2)` | `4` |
 
-- `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`
+> See the [full searchable function reference](docs/reference/functions.md) for all ~130 built-in functions.
 
 ## Return Types
 
-Depending on the expression, `evaluate()` may return:
+| Type | Example expression | Result |
+|---|---|---|
+| Number / BigInt / Boolean | `2 + 2`, `true && false` | `4`, `false` |
+| String | `"hello" + " world"` | `"hello world"` |
+| Unit string | `2 inch to cm` | `"5.08 cm"` |
+| Complex string | `3 + 2i` | `"3 + 2i"` |
+| Matrix JSON | `[1,2;3,4]` | `{"exprify":"DenseMatrix",...}` |
+| Structured JSON | `lup(...)`, `rationalize(..., true)` | JSON object string |
+| Function | `x -> x^2` | Native JS function |
+| Array | `1:5` | `[1,2,3,4,5]` |
 
-- 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
+git clone https://github.com/code-hemu/exprify.git
 cd Exprify
 npm install
 npm run build
 ```
 
-Build output is written to `dist/`.
+Output is written to `dist/`.
 
 ## Testing
 
@@ -283,21 +216,15 @@ Build output is written to `dist/`.
 npm test
 ```
 
-Tested in CI across Node 20 and 22 (see `.github/workflows/ci.yml`).
-
-## Publishing
-
-The package is published to the public npm registry via `npm publish`. The `npm-publish.yml` workflow runs on GitHub release events. See `.github/workflows/npm-publish.yml` for details.
-
-`package-lock.json` is committed but is not shipped in the published tarball (see `.npmignore`); consumers generate their own lockfile when installing.
-
-## License
-
-Exprify is licensed under GPL-3.0. Copyright (c) [Nirmal Paul](https://github.com/nirmalpaul383/).
+Tested in CI across Node 20 and 22. See `.github/workflows/ci.yml` for details.
 
 ## 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.
+4. Push and open a pull request.
+
+## License
+
+Exprify is licensed under **GPL-3.0**. Copyright © [Nirmal Paul](https://github.com/nirmalpaul383/).

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.0.5     | ❌ |
+| 1.0.6     | ✅ |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Exprify, please report it privately by opening a security advisory at:
+
+https://github.com/code-hemu/exprify/security/advisories/new
+
+You can expect an acknowledgment within 48 hours and a detailed response within 5 business days. If the vulnerability is accepted, a fix will be coordinated through a private release and published as a patch version. If declined, you will receive an explanation of why the issue does not constitute a security risk.
+
+Please do **not** report security vulnerabilities through public GitHub issues, discussions, or pull requests.