formula-evaluator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Wallwork
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# formula-evaluator
+
+A lightweight, extensible formula engine with variable tracking, nested functions, and operator precedence.
+
+## Installation
+
+```bash
+npm install formula-evaluator
+```
+
+## Quick Start
+
+```js
+import FormulaEvaluator from 'formula-evaluator';
+
+const evaluator = new FormulaEvaluator();
+
+evaluator.evaluate('1 + 2');          // 3
+evaluator.evaluate('sum(1, 2, 3)');   // 6
+evaluator.evaluate('upper("hello")'); // "HELLO"
+```
+
+## Usage
+
+### Constructor
+
+Create an evaluator with an optional global context of variables:
+
+```js
+const evaluator = new FormulaEvaluator({ tax: 0.2, basePrice: 100 });
+```
+
+### `evaluate(formula, localContext?)`
+
+Evaluate a formula string and return the result. An optional local context can be passed to provide or override variables for a single evaluation.
+
+```js
+const evaluator = new FormulaEvaluator({ x: 10 });
+
+evaluator.evaluate('x + 1');              // 11
+evaluator.evaluate('x + y', { y: 5 });    // 15
+evaluator.evaluate('x', { x: 99 });       // 99  (local overrides global)
+```
+
+### `getDependencies(formula)`
+
+Return an array of variable names referenced in a formula. Useful for building dependency graphs or determining which values a formula needs.
+
+```js
+evaluator.getDependencies('x + y');              // ['x', 'y']
+evaluator.getDependencies('sum(a, b, c)');       // ['a', 'b', 'c']
+evaluator.getDependencies('sum(1, 2)');          // []
+evaluator.getDependencies('x + x');              // ['x']  (deduplicated)
+```
+
+### `tokenize(formula)` / `parse(tokens)`
+
+Lower-level methods for accessing the tokenizer and parser directly:
+
+```js
+const tokens = evaluator.tokenize('sum(x, 1)');
+const ast = evaluator.parse(tokens);
+```
+
+## Built-in Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `sum(...args)` | Sum all arguments | `sum(1, 2, 3)` → `6` |
+| `avg(...args)` | Average of all arguments | `avg(2, 4, 6)` → `4` |
+| `upper(str)` | Convert to uppercase | `upper("hi")` → `"HI"` |
+| `join(sep, ...args)` | Join arguments with separator | `join("-", "a", "b")` → `"a-b"` |
+| `if(cond, a, b)` | Conditional: returns `a` if truthy, `b` otherwise | `if(true, "yes", "no")` → `"yes"` |
+
+## Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `+` | Addition | `1 + 2` → `3` |
+| `-` | Subtraction | `5 - 3` → `2` |
+| `=` | Equality check | `5 = 5` → `true` |
+
+## Supported Types
+
+- **Numbers**: `42`, `3.14`, `0.5`
+- **Strings**: `"hello world"`
+- **Booleans**: `true`, `false`
+
+## Adding Custom Functions
+
+You can extend the evaluator by adding functions directly to the `FUNCTIONS` object:
+
+```js
+const evaluator = new FormulaEvaluator();
+
+evaluator.FUNCTIONS.double = (x) => x * 2;
+evaluator.FUNCTIONS.min = (...args) => Math.min(...args);
+
+evaluator.evaluate('double(5)');     // 10
+evaluator.evaluate('min(3, 1, 2)');  // 1
+```
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+To run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "formula-evaluator",
+  "version": "1.0.0",
+  "description": "A lightweight formula evaluator with dependency tracking and static analysis.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "formula",
+    "parser",
+    "evaluator",
+    "ast"
+  ],
+  "author": "Jordan Wallwork",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jordanwallwork/formula-evaluator.git"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,155 @@
+/**
+ * FormulaEvaluator: A lightweight, extensible formula engine
+ * Features: Variable tracking, nested functions, and operator precedence.
+ */
+class FormulaEvaluator {
+  constructor(globalContext = {}) {
+    this.context = globalContext;
+
+    // Core Function Library (Easily extensible)
+    this.FUNCTIONS = {
+      upper: (str) => String(str).toUpperCase(),
+      join: (sep, ...args) => args.join(sep),
+      sum: (...args) => args.reduce((a, b) => Number(a) + Number(b), 0),
+      avg: (...args) => args.reduce((a, b) => a + b, 0) / args.length,
+      if: (cond, a, b) => (cond ? a : b),
+      // Internal Operator Mappings
+      __add: (a, b) => a + b,
+      __sub: (a, b) => a - b,
+      __eq: (a, b) => a === b,
+    };
+
+    this.TOKEN_TYPES = {
+      NUMBER: 'number',
+      STRING: 'string',
+      IDENTIFIER: 'identifier',
+      OPERATOR: 'operator',
+      DELIMITER: 'delimiter',
+      WHITESPACE: 'whitespace'
+    };
+  }
+
+  tokenize(str) {
+    const tokens = [];
+    const rules = [
+      { type: this.TOKEN_TYPES.STRING,     regex: /"([^"]*)"/g },
+      { type: this.TOKEN_TYPES.NUMBER,     regex: /\d*\.?\d+/g },
+      { type: this.TOKEN_TYPES.IDENTIFIER, regex: /[a-zA-Z][\w\d]*/g },
+      { type: this.TOKEN_TYPES.OPERATOR,   regex: /[+=-]/g },
+      { type: this.TOKEN_TYPES.DELIMITER,  regex: /[(),]/g },
+      { type: this.TOKEN_TYPES.WHITESPACE, regex: /\s+/g }
+    ];
+
+    let pos = 0;
+    while (pos < str.length) {
+      let found = false;
+      for (const { type, regex } of rules) {
+        regex.lastIndex = pos;
+        const match = regex.exec(str);
+        if (match && match.index === pos) {
+          if (type !== this.TOKEN_TYPES.WHITESPACE) {
+            tokens.push({
+              type,
+              value: type === this.TOKEN_TYPES.STRING ? match[1] : match[0],
+              start: pos,
+              end: pos + match[0].length
+            });
+          }
+          pos += match[0].length;
+          found = true;
+          break;
+        }
+      }
+      if (!found) throw new Error(`Unexpected character at ${pos}: ${str[pos]}`);
+    }
+    return tokens;
+  }
+
+  // --- Parser Logic ---
+  parse(tokens) {
+    let pos = 0;
+
+    const parseExpression = () => {
+      let node = parseToken();
+
+      const currentToken = tokens[pos];
+      if (currentToken && currentToken.type === this.TOKEN_TYPES.OPERATOR) {
+        const opToken = tokens[pos++];
+        const right = parseExpression();
+        const opMap = { '+': '__add', '-': '__sub', '=': '__eq' };
+        return { type: 'function', name: opMap[opToken.value], args: [node, right] };
+      }
+      return node;
+    };
+
+    const parseToken = () => {
+      const token = tokens[pos++];
+      if (!token) return null;
+
+      if (token.type === this.TOKEN_TYPES.NUMBER) return parseFloat(token.value);
+      if (token.value === 'true') return true;
+      if (token.value === 'false') return false;
+      if (token.type === this.TOKEN_TYPES.STRING) return token.value;
+
+      if (token.type === this.TOKEN_TYPES.IDENTIFIER) {
+        const nextToken = tokens[pos];
+        if (nextToken && nextToken.value === '(') {
+          pos++; // skip (
+          const args = [];
+          while (pos < tokens.length && tokens[pos].value !== ')') {
+            args.push(parseExpression());
+            if (tokens[pos] && tokens[pos].value === ',') pos++;
+          }
+          pos++; // skip )
+          return { type: 'function', name: token.value, args };
+        }
+        return { type: 'variable', name: token.value };
+      }
+
+      if (token.value === '(') {
+        const node = parseExpression();
+        pos++; // skip )
+        return node;
+      }
+    };
+
+    return parseExpression();
+  }
+
+  // --- Execution & Analysis ---
+  evaluate(formula, localContext = {}) {
+    const ast = this.parse(this.tokenize(formula));
+    const ctx = { ...this.context, ...localContext };
+
+    const run = (node) => {
+      if (typeof node !== 'object' || node === null) return node;
+
+      if (node.type === 'variable') {
+        if (!(node.name in ctx)) throw new Error(`Variable "${node.name}" not found`);
+        return ctx[node.name];
+      }
+
+      if (node.type === 'function') {
+        const fn = this.FUNCTIONS[node.name];
+        if (!fn) throw new Error(`Function "${node.name}" not found`);
+        return fn(...node.args.map(run));
+      }
+    };
+
+    return run(ast);
+  }
+
+  getDependencies(formula) {
+    const ast = this.parse(this.tokenize(formula));
+    const deps = new Set();
+    const walk = (node) => {
+      if (typeof node !== 'object' || node === null) return;
+      if (node.type === 'variable') deps.add(node.name);
+      else if (node.type === 'function') node.args.forEach(walk);
+    };
+    walk(ast);
+    return Array.from(deps);
+  }
+}
+
+export default FormulaEvaluator;