exprify 1.0.3 → 1.0.6

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,32 @@
-# Exprify
+[![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)
 
-[![Exprify Social Banner](https://raw.githubusercontent.com/code-hemu/Exprify/refs/heads/main/src/assets/capture.jpg)](https://github.com/code-hemu/Exprify)
+[![Exprify 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**) parses a string into an expression tree, evaluates it with a given set of variables, and lets you chain or compose operations together - in the browser and in Node.js.
+
+## Features
+
+| Capability | Example | Docs |
+|---|---|---|
+| **Arithmetic & Variables** | `expr.evaluate("5 + 7 * 2")` | [datatypes/numbers.md](docs/datatypes/numbers.md) |
+| **Unit conversion** | `expr.evaluate("2 inch to cm")` | [datatypes/units.md](docs/datatypes/units.md) |
+| **Matrix operations** | `expr.evaluate("det([-1,2;3,1])")` | [datatypes/matrices.md](docs/datatypes/matrices.md) |
+| **Complex numbers** | `expr.evaluate("9/3 + 2i")` | [datatypes/complex.md](docs/datatypes/complex_numbers.md) |
+| **Symbolic math** | `expr.evaluate('expand("(x+1)^2")')` | [expressions/algebra.md](docs/expressions/algebra.md) |
+| **Arbitrary precision** | `expr.evaluate('bignumber("0.1") + bignumber("0.2")')` | [datatypes/bignumbers.md](docs/datatypes/bignumbers.md) |
+| **Exact fractions** | `expr.evaluate("fraction(1,3) + fraction(1,6)")` | [datatypes/fractions.md](docs/datatypes/fractions.md) |
+| **Calculus & statistics** | `expr.evaluate('integral("x^2", 0, 1)')` | [reference/functions.md](docs/reference/functions.md) |
+| **Lambda expressions** | `expr.evaluate('map([1,2,3], x -> x^2)')` | [expressions/customization.md](docs/expressions/customization.md) |
+| **Expression chaining** | `c.evaluate("sqrt(x)").evaluate("ans * 2").done()` | [core/chaining.md](docs/core/chaining.md) |
+| **State serialization** | `expr.exportState()` / `expr.importState(state)` | [core/serialization.md](docs/core/serialization.md) |
+| **Degree-mode trig** | `expr.evaluate("sind(90)")` | [reference/functions.md](docs/reference/functions.md) |
 
 ## Installation
 
@@ -12,245 +36,172 @@ npm install exprify
 
 ## Quick Start
 
+**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
 ```
 
-## Browser Usage
+**CommonJS:**
+
+```js
+const Exprify = require("exprify");
+
+const expr = new Exprify();
+expr.evaluate("5 + 7 * 2");        // 19
+```
+
+**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
+
+`package.json`'s `exports` field routes each import style to the correct build automatically.
+
+| Consumer | Resolved file | Notes |
+|---|---|---|
+| `import Exprify from "exprify"` | `dist/exprify.esm.js` | Default export is the `Exprify` class |
+| `require("exprify")` | `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"` | `dist/exprify.js` | Unminified UMD for bundlers that prefer it |
+
+> The `.cjs` extension keeps the CommonJS bundle loadable via `require()` even though the package uses `"type": "module"`.
 
 ## API
 
 ### `new Exprify()`
 
-Creates a new evaluator instance with isolated state for:
+Creates a new evaluator instance with isolated state for variables, functions, units, and a compiled-expression cache.
 
-- variables
-- functions
-- units
-- compiled-expression cache
+### `expr.evaluate(expression, scope?)`
 
-### `expr.evaluate(expression)`
-
-Parses and evaluates an expression string.
+Parses and evaluates an expression string. An optional `scope` object overrides variables for that single call only.
 
 ```js
-expr.evaluate("10 + 5 * 2");
-// 20
+expr.evaluate("10 + 5 * 2");               // 20
+
+expr.setVariable("x", 100);
+expr.evaluate("x + 1", { x: 5 });          // 6
 ```
 
 ### `expr.parse(expression)`
 
-Returns `{ tokens, ast }`.
+Returns `{ tokens, ast }` - the raw token list and abstract syntax tree.
 
 ```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");
 ```
 
 ### `expr.compile(expression)`
 
-Compiles an expression once and returns a reusable function.
+Compiles an expression once and returns a reusable function - ideal for hot paths.
 
 ```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 and retrieves named values that persist across evaluations.
 
 ```js
 expr.setVariable("x", 10);
 expr.setVariable("y", 5);
-
-console.log(expr.evaluate("x + y * 2"));
-// 20
+expr.evaluate("x + y * 2");                // 20
 ```
 
 ### `expr.addFunction(name, fn)`
 
-Registers a custom JavaScript function.
+Registers a custom JavaScript function, making it callable inside expressions.
 
 ```js
 expr.addFunction("double", (n) => n * 2);
-
-console.log(expr.evaluate("double(5) + 3"));
-// 13
+expr.evaluate("double(5) + 3");            // 13
 ```
 
-### Inline Function Definitions
+### `expr.chain()`
 
-You can define functions inside expressions.
+Returns a fluent `Chain` object. Each step stores its result as `ans` for the next expression.
 
 ```js
-expr.evaluate("hyp(a, b) = sqrt(a ^ 2 + b ^ 2)");
-
-console.log(expr.evaluate("hyp(3, 4)"));
-// 5
+const c = expr.chain();
+c.setVariable("x", 25);
+c.evaluate("sqrt(x) + 3");                 // ans = 8
+c.evaluate("ans * 2");                     // ans = 16
+c.done();                                  // 16
 ```
 
-## Features
-
-### Arithmetic
-
-```js
-expr.evaluate("2 + 3 * 4");
-// 14
-
-expr.evaluate("(2 + 3) * 4");
-// 20
+### `expr.exportState()` / `expr.importState(state)`
 
-expr.evaluate("11n ^ 2n");
-// 121n
-```
-
-### Strings, Booleans, Complex Numbers
+Serializes and restores the full engine state - variables, functions, and units.
 
 ```js
-expr.evaluate('"Hello " + "World"');
-// "Hello World"
+const state = expr.exportState();
+// { variables: {...}, functions: [...], units: {...} }
 
-expr.evaluate("true && false");
-// false
-
-expr.evaluate("9 / 3 + 2i");
-// "3 + 2i"
+const expr2 = new Exprify();
+expr2.importState(state);
 ```
 
-### 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)"}
-```
+### Inline Function Definitions
 
-### Parse and AST Utilities
+Functions can be defined directly inside expressions and reused immediately.
 
 ```js
-expr.evaluate('leafCount("e^(i*pi)-1")');
-// 4
-
-expr.evaluate('leafCount(parse("{a: 22/7, b: 10^(1/2)}"))');
-// 5
+expr.evaluate("hyp(a, b) = sqrt(a^2 + b^2)");
+expr.evaluate("hyp(3, 4)");                // 5
 ```
 
-### 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:
-
-- 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)`
+| 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]` |
 
 ## 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
 
@@ -258,13 +209,15 @@ Build output is written to `dist/`.
 npm test
 ```
 
-## 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.

package/bin/cli.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { stdin, stdout, stderr, exit, argv, version } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+} catch {
+  pkg = { version: 'unknown' };
+}
+
+let Exprify;
+try {
+  const mod = await import('../src/core/exprify.js');
+  Exprify = mod.default || mod.Exprify;
+} catch {
+  stderr.write('Error: Could not load Exprify module\n');
+  exit(1);
+}
+
+const expr = new Exprify();
+
+const USAGE = `Usage: exprify [options] [expression...]
+
+Options:
+  --help           Show this help message
+  --version        Show version number
+  --parse <expr>   Parse expression and show token/AST structure
+  --tokens <expr>  Tokenize expression and show tokens
+
+If no expression is provided and stdin is a TTY, starts interactive REPL.
+If stdin is piped, reads expression from stdin.
+
+Examples:
+  exprify "2 + 2"
+  exprify "sqrt(16)" "5 * 3"
+  exprify --parse "x ^ 2 + 2 * x + 1"
+  echo "2 + 2" | exprify
+`;
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+};
+
+function formatResult(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'object' || Array.isArray(value)) {
+    return JSON.stringify(value, null, 2);
+  }
+  return String(value);
+}
+
+function printError(msg) {
+  stderr.write(COLORS.red + 'Error: ' + COLORS.reset + msg + '\n');
+}
+
+function evaluateAndPrint(expression, mode) {
+  try {
+    if (mode === 'parse') {
+      const result = expr.parse(expression);
+      console.log(JSON.stringify(result, null, 2));
+    } else if (mode === 'tokens') {
+      const result = expr.tokenize(expression);
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const result = expr.evaluate(expression);
+      console.log(formatResult(result));
+    }
+  } catch (err) {
+    printError(err.message);
+    exit(1);
+  }
+}
+
+const args = argv.slice(2);
+
+if (args.length === 0) {
+  if (stdin.isTTY) {
+    startREPL();
+  } else {
+    let input = '';
+    stdin.setEncoding('utf-8');
+    stdin.on('data', (chunk) => {
+      input += chunk;
+    });
+    stdin.on('end', () => {
+      const exprStr = input.trim();
+      if (exprStr) evaluateAndPrint(exprStr);
+    });
+  }
+  exit(0);
+}
+
+const flag = args[0];
+
+if (flag === '--help' || flag === '-h') {
+  console.log(USAGE);
+  exit(0);
+}
+
+if (flag === '--version' || flag === '-v') {
+  console.log(pkg.version);
+  exit(0);
+}
+
+if (flag === '--parse' || flag === '--tokens') {
+  if (args.length < 2) {
+    printError('Missing expression argument');
+    console.log(USAGE);
+    exit(2);
+  }
+  const mode = flag.slice(2);
+  for (let i = 1; i < args.length; i++) {
+    evaluateAndPrint(args[i], mode);
+  }
+  exit(0);
+}
+
+for (const arg of args) {
+  evaluateAndPrint(arg);
+}
+
+function startREPL() {
+  console.log(`Exprify v${pkg.version} - interactive REPL`);
+  console.log('Type an expression or .help for commands\n');
+
+  const rl = createInterface({
+    input: stdin,
+    output: stdout,
+    prompt: COLORS.cyan + '» ' + COLORS.reset,
+    completer: (line) => {
+      const completions = [
+        'help',
+        '.help',
+        '.exit',
+        'pi',
+        'e',
+        'i',
+        'PHI',
+        'TAU',
+        'INFINITY',
+        'NaN',
+        'sin',
+        'cos',
+        'tan',
+        'sqrt',
+        'abs',
+        'log',
+        'exp',
+        'map',
+        'filter',
+        'sum',
+        'prod',
+        'mean',
+        'max',
+        'min',
+        'if',
+        'parse',
+        'leafCount',
+        'random',
+        'simplify',
+        'expand',
+        'factor',
+        'solve',
+        'derivative',
+        'integral',
+        'sigma',
+        'limit',
+        'substitute',
+        'det',
+        'transpose',
+        'inverse',
+        'trace',
+        'rank',
+      ];
+      const hits = completions.filter((c) => c.startsWith(line));
+      return [hits.length ? hits : completions, line];
+    },
+  });
+
+  rl.on('line', (line) => {
+    const input = line.trim();
+
+    if (!input) {
+      rl.prompt();
+      return;
+    }
+
+    if (input === '.exit' || input === 'exit' || input === 'quit') {
+      rl.close();
+      return;
+    }
+
+    if (input === '.help' || input === 'help') {
+      console.log(`\n  ${COLORS.bold}Commands:${COLORS.reset}`);
+      console.log('  .exit       Exit the REPL');
+      console.log('  .help       Show this message');
+      console.log('  <expr>      Evaluate an expression');
+      console.log('  Ctrl+C      Cancel / exit');
+      console.log('');
+      rl.prompt();
+      return;
+    }
+
+    try {
+      const result = expr.evaluate(input);
+      console.log(COLORS.green + formatResult(result) + COLORS.reset);
+    } catch (err) {
+      console.log(COLORS.red + 'Error: ' + COLORS.reset + err.message);
+    }
+
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    console.log('');
+    exit(0);
+  });
+
+  rl.prompt();
+}