formula-evaluator 1.0.0 → 1.2.0

package/README.md

@@ -86,18 +86,91 @@ const ast = evaluator.parse(tokens);
 - **Strings**: `"hello world"`
 - **Booleans**: `true`, `false`
 
-## Adding Custom Functions
+### `registerFunction(name, fn)`
 
-You can extend the evaluator by adding functions directly to the `FUNCTIONS` object:
+Register a custom function that can be called in formulas. Returns the evaluator instance so calls can be chained.
 
 ```js
 const evaluator = new FormulaEvaluator();
 
-evaluator.FUNCTIONS.double = (x) => x * 2;
-evaluator.FUNCTIONS.min = (...args) => Math.min(...args);
+evaluator
+  .registerFunction('double', (x) => x * 2)
+  .registerFunction('clamp', (val, min, max) => Math.min(Math.max(val, min), max));
 
-evaluator.evaluate('double(5)');     // 10
-evaluator.evaluate('min(3, 1, 2)');  // 1
+evaluator.evaluate('double(5)');        // 10
+evaluator.evaluate('clamp(15, 0, 10)'); // 10
+```
+
+Custom functions receive their arguments already evaluated, so they work naturally with variables, operators, and nested calls:
+
+```js
+evaluator.registerFunction('double', (x) => x * 2);
+
+evaluator.evaluate('double(n)', { n: 4 });   // 8
+evaluator.evaluate('double(3) + 1');          // 7
+evaluator.evaluate('double(sum(1, 2))');      // 6
+```
+
+You can also override built-in functions:
+
+```js
+evaluator.registerFunction('sum', (...args) => args.reduce((a, b) => a + b, 0));
+```
+
+### `listFunctions()`
+
+Returns the names of all registered public functions (excludes internal operator mappings):
+
+```js
+evaluator.listFunctions(); // ['upper', 'join', 'sum', 'avg', 'if']
+
+evaluator.registerFunction('double', (x) => x * 2);
+evaluator.listFunctions(); // ['upper', 'join', 'sum', 'avg', 'if', 'double']
+```
+
+## Function Registry
+
+For advanced use cases you can work with the function registry directly. The `createFunctionRegistry` factory and the `builtinFunctions` map are available as named exports:
+
+```js
+import { createFunctionRegistry, builtinFunctions } from 'formula-evaluator';
+```
+
+### `createFunctionRegistry(initialFunctions?)`
+
+Creates a standalone registry pre-loaded with the built-in functions. Useful when you want to prepare a set of functions before constructing an evaluator, or share a registry definition across modules.
+
+```js
+import { createFunctionRegistry } from 'formula-evaluator';
+
+const registry = createFunctionRegistry({
+  double: (x) => x * 2,
+});
+
+registry.register('triple', (x) => x * 3);
+registry.has('sum');          // true  (built-in)
+registry.has('double');       // true  (initial)
+registry.has('triple');       // true  (registered)
+registry.get('double')(5);    // 10
+registry.list();              // ['upper', 'join', 'sum', 'avg', 'if', 'double', 'triple']
+registry.unregister('triple');
+registry.has('triple');       // false
+```
+
+Built-in functions are protected and cannot be unregistered:
+
+```js
+registry.unregister('sum'); // throws Error: Cannot unregister built-in function "sum"
+```
+
+### `builtinFunctions`
+
+A frozen object containing the default function implementations. Useful for inspection or when building a custom registry from scratch:
+
+```js
+import { builtinFunctions } from 'formula-evaluator';
+
+Object.keys(builtinFunctions); // ['upper', 'join', 'sum', 'avg', 'if', '__add', '__sub', '__eq']
 ```
 
 ## Development

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "formula-evaluator",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A lightweight formula evaluator with dependency tracking and static analysis.",
   "main": "src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./functions": "./src/functions.js"
   },
   "type": "module",
   "files": [

package/src/functions.js

@@ -0,0 +1,256 @@
+/**
+ * @module functions
+ * Built-in function library and registry for the formula evaluator.
+ */
+
+/**
+ * A function that can be called during formula evaluation.
+ * @callback FormulaFunction
+ * @param {...*} args - Evaluated arguments from the formula
+ * @returns {*} The computed result
+ */
+
+/**
+ * A function definition containing the implementation and a human-readable description.
+ * @typedef {Object} FunctionDef
+ * @property {FormulaFunction} fn - The function implementation
+ * @property {string} description - A human-readable description of what the function does
+ */
+
+/**
+ * Built-in functions included in every new evaluator instance.
+ * Each entry contains a `fn` implementation and a human-readable `description`.
+ * @type {Readonly<Record<string, FunctionDef>>}
+ */
+export const builtinFunctions = Object.freeze({
+  upper: {
+    fn: (str) => String(str).toUpperCase(),
+    description: 'Converts a value to an uppercase string',
+  },
+
+  join: {
+    fn: (sep, ...args) => args.join(sep),
+    description: 'Joins arguments with a separator',
+  },
+
+  sum: {
+    fn: (...args) => args.reduce((a, b) => Number(a) + Number(b), 0),
+    description: 'Sums all arguments numerically',
+  },
+
+  avg: {
+    fn: (...args) => args.reduce((a, b) => a + b, 0) / args.length,
+    description: 'Returns the arithmetic mean of all arguments',
+  },
+
+  if: {
+    fn: (cond, a, b) => (cond ? a : b),
+    description: 'Returns the second argument if the condition is truthy, otherwise the third',
+  },
+
+  coalesce: {
+    fn: (...args) => args.find(a => a != null),
+    description: 'Returns the first non-null/non-undefined value',
+  },
+
+  isblank: {
+    fn: (val) => val === '' || val == null,
+    description: 'Returns true if a value is an empty string or null/undefined',
+  },
+
+  and: {
+    fn: (...args) => args.every(Boolean),
+    description: 'Returns true if all arguments are truthy',
+  },
+
+  or: {
+    fn: (...args) => args.some(Boolean),
+    description: 'Returns true if any argument is truthy',
+  },
+
+  iferr: {
+    fn: (val) => val,
+    description: 'Returns the first argument, or the second if the first throws an error',
+  },
+
+  round: {
+    fn: (n, d) => Number(Math.round(n + 'e' + d) + 'e-' + d),
+    description: 'Rounds a number to a specific decimal precision',
+  },
+
+  clamp: {
+    fn: (val, min, max) => Math.min(Math.max(val, min), max),
+    description: 'Restricts a number to a given range',
+  },
+
+  abs: {
+    fn: (n) => Math.abs(n),
+    description: 'Returns the absolute value of a number',
+  },
+
+  concat: {
+    fn: (...args) => args.join(''),
+    description: 'Concatenates all arguments without a separator',
+  },
+
+  /** @private */
+  __add: {
+    fn: (a, b) => a + b,
+    description: 'Addition operator',
+  },
+
+  /** @private */
+  __sub: {
+    fn: (a, b) => a - b,
+    description: 'Subtraction operator',
+  },
+
+  /** @private */
+  __eq: {
+    fn: (a, b) => a === b,
+    description: 'Equality operator',
+  },
+
+  /** @private */
+  __gt: {
+    fn: (a, b) => a > b,
+    description: 'Greater-than operator',
+  },
+
+  /** @private */
+  __gte: {
+    fn: (a, b) => a >= b,
+    description: 'Greater-than-or-equal operator',
+  },
+
+  /** @private */
+  __lt: {
+    fn: (a, b) => a < b,
+    description: 'Less-than operator',
+  },
+
+  /** @private */
+  __lte: {
+    fn: (a, b) => a <= b,
+    description: 'Less-than-or-equal operator',
+  },
+});
+
+/**
+ * @typedef {Object} FunctionRegistry
+ * @property {(name: string, fn: FormulaFunction, description?: string) => void} register - Register a new function
+ * @property {(name: string) => FormulaFunction|undefined} get - Retrieve a function by name
+ * @property {(name: string) => boolean} has - Check whether a function is registered
+ * @property {(name: string) => boolean} unregister - Remove a custom (non-built-in) function
+ * @property {() => string[]} list - List public function names (excludes internal __ operators)
+ * @property {() => Array<{name: string, description: string}>} describe - List public function names and descriptions
+ * @property {() => Record<string, FunctionDef>} getAll - Get a snapshot of all registered function definitions
+ */
+
+/**
+ * Creates a function registry pre-loaded with the built-in functions.
+ *
+ * Use this to build a standalone registry, or let {@link FormulaEvaluator}
+ * create one automatically via its constructor.
+ *
+ * @param {Record<string, FormulaFunction>} [initialFunctions={}] - Extra functions to register on creation
+ * @returns {FunctionRegistry} A new registry instance
+ *
+ * @example
+ * import { createFunctionRegistry } from 'formula-evaluator/functions';
+ *
+ * const registry = createFunctionRegistry({
+ *   double: (x) => x * 2,
+ * });
+ * registry.register('triple', (x) => x * 3, 'Triples a number');
+ * registry.get('double')(5); // 10
+ * registry.list(); // ['upper', 'join', 'sum', 'avg', 'if', 'double', 'triple']
+ * registry.describe(); // [{ name: 'upper', description: 'Converts a value to an uppercase string' }, ...]
+ */
+export function createFunctionRegistry(initialFunctions = {}) {
+  /** @type {Record<string, FunctionDef>} */
+  const functions = { ...builtinFunctions };
+
+  for (const [name, val] of Object.entries(initialFunctions)) {
+    functions[name] = typeof val === 'function'
+      ? { fn: val, description: '' }
+      : { ...val };
+  }
+
+  return {
+    /**
+     * Registers a function under the given name.
+     * @param {string} name - Function name (used in formula strings)
+     * @param {FormulaFunction} fn - The implementation
+     * @param {string} [description=''] - A human-readable description of the function
+     * @throws {Error} If name is not a non-empty string or fn is not a function
+     */
+    register(name, fn, description = '') {
+      if (typeof name !== 'string' || !name) {
+        throw new Error('Function name must be a non-empty string');
+      }
+      if (typeof fn !== 'function') {
+        throw new Error('Function implementation must be a function');
+      }
+      functions[name] = { fn, description };
+    },
+
+    /**
+     * Retrieves a function implementation by name.
+     * @param {string} name
+     * @returns {FormulaFunction|undefined}
+     */
+    get(name) {
+      return functions[name]?.fn;
+    },
+
+    /**
+     * Checks whether a function is registered.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+      return name in functions;
+    },
+
+    /**
+     * Removes a custom function. Built-in functions cannot be unregistered.
+     * @param {string} name
+     * @returns {boolean} `true` if the function was removed
+     * @throws {Error} If attempting to unregister a built-in function
+     */
+    unregister(name) {
+      if (name in builtinFunctions) {
+        throw new Error(`Cannot unregister built-in function "${name}"`);
+      }
+      return delete functions[name];
+    },
+
+    /**
+     * Lists all public function names (excludes internal `__` operators).
+     * @returns {string[]}
+     */
+    list() {
+      return Object.keys(functions).filter(name => !name.startsWith('__'));
+    },
+
+    /**
+     * Returns names and descriptions of all public functions
+     * (excludes internal `__` operators).
+     * @returns {Array<{name: string, description: string}>}
+     */
+    describe() {
+      return Object.entries(functions)
+        .filter(([name]) => !name.startsWith('__'))
+        .map(([name, { description }]) => ({ name, description }));
+    },
+
+    /**
+     * Returns a shallow copy of all registered function definitions.
+     * @returns {Record<string, FunctionDef>}
+     */
+    getAll() {
+      return { ...functions };
+    },
+  };
+}

package/src/index.js

@@ -1,24 +1,43 @@
 /**
- * FormulaEvaluator: A lightweight, extensible formula engine
- * Features: Variable tracking, nested functions, and operator precedence.
+ * @module formula-evaluator
+ * A lightweight, extensible formula engine with variable tracking,
+ * nested functions, and operator precedence.
+ */
+
+import { createFunctionRegistry } from './functions.js';
+
+export { builtinFunctions, createFunctionRegistry } from './functions.js';
+
+/**
+ * Evaluates string-based formulas with support for variables, functions,
+ * and arithmetic operators.
+ *
+ * @example
+ * const evaluator = new FormulaEvaluator({ tax: 0.2 });
+ * evaluator.registerFunction('discount', (price, pct) => price * (1 - pct));
+ * evaluator.evaluate('discount(100, tax)'); // 80
  */
 class FormulaEvaluator {
+  /**
+   * Creates a new FormulaEvaluator instance.
+   *
+   * @param {Record<string, *>} [globalContext={}] - Variables available to every evaluation
+   */
   constructor(globalContext = {}) {
+    /** @type {Record<string, *>} */
     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,
-    };
+    /**
+     * Internal function registry.
+     * @private
+     * @type {import('./functions.js').FunctionRegistry}
+     */
+    this._functions = createFunctionRegistry();
 
+    /**
+     * Token type constants used by the tokenizer.
+     * @type {Readonly<Record<string, string>>}
+     */
     this.TOKEN_TYPES = {
       NUMBER: 'number',
       STRING: 'string',
@@ -29,13 +48,62 @@ class FormulaEvaluator {
     };
   }
 
+  /**
+   * Registers a custom function that can be called in formulas.
+   *
+   * @param {string} name - The function name (used in formula strings)
+   * @param {import('./functions.js').FormulaFunction} fn - The function implementation
+   * @param {string} [description=''] - A human-readable description of the function
+   * @returns {this} The evaluator instance, for chaining
+   * @throws {Error} If name is not a non-empty string or fn is not a function
+   *
+   * @example
+   * evaluator
+   *   .registerFunction('double', (x) => x * 2, 'Doubles a number')
+   *   .registerFunction('clamp', (val, min, max) => Math.min(Math.max(val, min), max), 'Restricts a number to a range');
+   *
+   * evaluator.evaluate('double(5)');       // 10
+   * evaluator.evaluate('clamp(15, 0, 10)'); // 10
+   */
+  registerFunction(name, fn, description = '') {
+    this._functions.register(name, fn, description);
+    return this;
+  }
+
+  /**
+   * Lists the names of all registered public functions
+   * (excludes internal operator mappings).
+   *
+   * @returns {string[]} Array of function names
+   */
+  listFunctions() {
+    return this._functions.list();
+  }
+
+  /**
+   * Returns the names and descriptions of all registered public functions
+   * (excludes internal operator mappings).
+   *
+   * @returns {Array<{name: string, description: string}>}
+   */
+  describeFunctions() {
+    return this._functions.describe();
+  }
+
+  /**
+   * Tokenizes a formula string into an array of tokens.
+   *
+   * @param {string} str - The formula string to tokenize
+   * @returns {Array<{type: string, value: string, start: number, end: number}>} The token array
+   * @throws {Error} If an unexpected character is encountered
+   */
   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.OPERATOR,   regex: />=|<=|[+=\-><]/g },
       { type: this.TOKEN_TYPES.DELIMITER,  regex: /[(),]/g },
       { type: this.TOKEN_TYPES.WHITESPACE, regex: /\s+/g }
     ];
@@ -65,7 +133,12 @@ class FormulaEvaluator {
     return tokens;
   }
 
-  // --- Parser Logic ---
+  /**
+   * Parses an array of tokens into an abstract syntax tree (AST).
+   *
+   * @param {Array<{type: string, value: string}>} tokens - Tokens produced by {@link tokenize}
+   * @returns {*} The root AST node
+   */
   parse(tokens) {
     let pos = 0;
 
@@ -76,7 +149,7 @@ class FormulaEvaluator {
       if (currentToken && currentToken.type === this.TOKEN_TYPES.OPERATOR) {
         const opToken = tokens[pos++];
         const right = parseExpression();
-        const opMap = { '+': '__add', '-': '__sub', '=': '__eq' };
+        const opMap = { '+': '__add', '-': '__sub', '=': '__eq', '>': '__gt', '>=': '__gte', '<': '__lt', '<=': '__lte' };
         return { type: 'function', name: opMap[opToken.value], args: [node, right] };
       }
       return node;
@@ -116,7 +189,19 @@ class FormulaEvaluator {
     return parseExpression();
   }
 
-  // --- Execution & Analysis ---
+  /**
+   * Evaluates a formula string and returns the result.
+   *
+   * @param {string} formula - The formula to evaluate
+   * @param {Record<string, *>} [localContext={}] - Variables scoped to this evaluation
+   *   (overrides global context for matching keys)
+   * @returns {*} The evaluation result
+   * @throws {Error} If a referenced variable or function is not found
+   *
+   * @example
+   * evaluator.evaluate('sum(1, 2, 3)');           // 6
+   * evaluator.evaluate('x + 1', { x: 10 });       // 11
+   */
   evaluate(formula, localContext = {}) {
     const ast = this.parse(this.tokenize(formula));
     const ctx = { ...this.context, ...localContext };
@@ -130,7 +215,16 @@ class FormulaEvaluator {
       }
 
       if (node.type === 'function') {
-        const fn = this.FUNCTIONS[node.name];
+        // iferr requires lazy evaluation: catch errors from the first arg
+        if (node.name === 'iferr') {
+          try {
+            return run(node.args[0]);
+          } catch {
+            return run(node.args[1]);
+          }
+        }
+
+        const fn = this._functions.get(node.name);
         if (!fn) throw new Error(`Function "${node.name}" not found`);
         return fn(...node.args.map(run));
       }
@@ -139,6 +233,15 @@ class FormulaEvaluator {
     return run(ast);
   }
 
+  /**
+   * Returns the variable names referenced in a formula (excludes function names).
+   *
+   * @param {string} formula - The formula to analyze
+   * @returns {string[]} Deduplicated array of variable names
+   *
+   * @example
+   * evaluator.getDependencies('sum(x, y) + z'); // ['x', 'y', 'z']
+   */
   getDependencies(formula) {
     const ast = this.parse(this.tokenize(formula));
     const deps = new Set();