@axi-engine/expressions 0.2.1 → 0.2.3

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ScalarType, PathType, DataSource } from '@axi-engine/utils';
+import { ScalarType, PathType, DataSource, Registry } from '@axi-engine/utils';
 
 /**
  * Represents an operand that is a direct, static value.
@@ -227,6 +227,27 @@ type Expression = ExpressionDefinitions[keyof ExpressionDefinitions];
 /** The union of all possible expression names (keys). uses in ExpressionHandler */
 type ExpressionName = keyof ExpressionDefinitions;
 
+/**
+ * A safe utility function that performs a basic mathematical operation on two operands.
+ *
+ * This function includes built-in type checking. It first ensures
+ * that both `left` and `right` operands are numbers before performing the calculation.
+ * If the type check fails or if an unsupported operator is provided, it will throw
+ * a descriptive error.
+ *
+ * @param op The mathematical operator to apply ('+', '-', '*', '/').
+ * @param left The left-hand operand. It is validated to be a number.
+ * @param right The right-hand operand. It is validated to be a number.
+ * @returns {number} The numerical result of the calculation.
+ * @throws {Error} If either `left` or `right` is not a number.
+ * @throws {Error} If the `op` is not a recognized `MathOperationType`.
+ *
+ * @example
+ * const result = resolveMath('+', 10, 5); // returns 15
+ * const product = resolveMath('*', 2, 3); // returns 6
+ */
+declare function resolveMath(op: MathOperationType, left: unknown, right: unknown): number;
+
 /**
  * Recursively resolves an Operand into its final scalar value.
  *
@@ -296,7 +317,7 @@ interface ExpressionEvaluatorContext {
  */
 declare class ExpressionEvaluator {
     /** @internal A map of registered expression handlers. */
-    handlers: Map<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
+    handlers: Registry<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
     /**
      * Registers a new `ExpressionHandler` with the evaluator.
      * This is the primary mechanism for extending the expression language with
@@ -466,4 +487,4 @@ declare class OrExpressionHandler implements ExpressionHandler<OrExpression> {
  */
 declare function createExpressionEvaluator(additionalHandlers?: ExpressionHandler[]): ExpressionEvaluator;
 
-export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, ExpressionEvaluator, type ExpressionEvaluatorContext, type ExpressionHandler, type ExpressionName, type InExpression, InExpressionHandler, type LiteralExpression, LiteralExpressionHandler, type MathOperationType, type NotExpression, NotExpressionHandler, type Operand, type OrExpression, OrExpressionHandler, type ReferenceOperand, type ValueOperand, createExpressionEvaluator, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveOperand, resolveOperandAsScalar };
+export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, ExpressionEvaluator, type ExpressionEvaluatorContext, type ExpressionHandler, type ExpressionName, type InExpression, InExpressionHandler, type LiteralExpression, LiteralExpressionHandler, type MathOperationType, type NotExpression, NotExpressionHandler, type Operand, type OrExpression, OrExpressionHandler, type ReferenceOperand, type ValueOperand, createExpressionEvaluator, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveMath, resolveOperand, resolveOperandAsScalar };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ScalarType, PathType, DataSource } from '@axi-engine/utils';
+import { ScalarType, PathType, DataSource, Registry } from '@axi-engine/utils';
 
 /**
  * Represents an operand that is a direct, static value.
@@ -227,6 +227,27 @@ type Expression = ExpressionDefinitions[keyof ExpressionDefinitions];
 /** The union of all possible expression names (keys). uses in ExpressionHandler */
 type ExpressionName = keyof ExpressionDefinitions;
 
+/**
+ * A safe utility function that performs a basic mathematical operation on two operands.
+ *
+ * This function includes built-in type checking. It first ensures
+ * that both `left` and `right` operands are numbers before performing the calculation.
+ * If the type check fails or if an unsupported operator is provided, it will throw
+ * a descriptive error.
+ *
+ * @param op The mathematical operator to apply ('+', '-', '*', '/').
+ * @param left The left-hand operand. It is validated to be a number.
+ * @param right The right-hand operand. It is validated to be a number.
+ * @returns {number} The numerical result of the calculation.
+ * @throws {Error} If either `left` or `right` is not a number.
+ * @throws {Error} If the `op` is not a recognized `MathOperationType`.
+ *
+ * @example
+ * const result = resolveMath('+', 10, 5); // returns 15
+ * const product = resolveMath('*', 2, 3); // returns 6
+ */
+declare function resolveMath(op: MathOperationType, left: unknown, right: unknown): number;
+
 /**
  * Recursively resolves an Operand into its final scalar value.
  *
@@ -296,7 +317,7 @@ interface ExpressionEvaluatorContext {
  */
 declare class ExpressionEvaluator {
     /** @internal A map of registered expression handlers. */
-    handlers: Map<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
+    handlers: Registry<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
     /**
      * Registers a new `ExpressionHandler` with the evaluator.
      * This is the primary mechanism for extending the expression language with
@@ -466,4 +487,4 @@ declare class OrExpressionHandler implements ExpressionHandler<OrExpression> {
  */
 declare function createExpressionEvaluator(additionalHandlers?: ExpressionHandler[]): ExpressionEvaluator;
 
-export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, ExpressionEvaluator, type ExpressionEvaluatorContext, type ExpressionHandler, type ExpressionName, type InExpression, InExpressionHandler, type LiteralExpression, LiteralExpressionHandler, type MathOperationType, type NotExpression, NotExpressionHandler, type Operand, type OrExpression, OrExpressionHandler, type ReferenceOperand, type ValueOperand, createExpressionEvaluator, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveOperand, resolveOperandAsScalar };
+export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, ExpressionEvaluator, type ExpressionEvaluatorContext, type ExpressionHandler, type ExpressionName, type InExpression, InExpressionHandler, type LiteralExpression, LiteralExpressionHandler, type MathOperationType, type NotExpression, NotExpressionHandler, type Operand, type OrExpression, OrExpressionHandler, type ReferenceOperand, type ValueOperand, createExpressionEvaluator, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveMath, resolveOperand, resolveOperandAsScalar };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   isOperand: () => isOperand,
   isReferenceOperand: () => isReferenceOperand,
   isValueOperand: () => isValueOperand,
+  resolveMath: () => resolveMath,
   resolveOperand: () => resolveOperand,
   resolveOperandAsScalar: () => resolveOperandAsScalar
 });
@@ -54,8 +55,29 @@ function isOperand(val) {
   return isValueOperand(val) || isReferenceOperand(val) || isArithmeticOperand(val);
 }
 
-// src/resolve-operand.ts
+// src/resolve-math.ts
 var import_utils2 = require("@axi-engine/utils");
+function resolveMath(op, left, right) {
+  (0, import_utils2.throwIf)(
+    !(0, import_utils2.isNumber)(left) || !(0, import_utils2.isNumber)(right),
+    `Require number operands, but got ${typeof left} and ${typeof right}.`
+  );
+  switch (op) {
+    case "+":
+      return Number(left) + Number(right);
+    case "-":
+      return Number(left) - Number(right);
+    case "*":
+      return Number(left) * Number(right);
+    case "/":
+      return Number(left) / Number(right);
+    default:
+      return (0, import_utils2.throwError)(`Unknown arithmetic operator: ${op}`);
+  }
+}
+
+// src/resolve-operand.ts
+var import_utils3 = require("@axi-engine/utils");
 function resolveOperand(op, source) {
   if (isValueOperand(op)) {
     return op.value;
@@ -66,40 +88,24 @@ function resolveOperand(op, source) {
   if (isArithmeticOperand(op)) {
     const leftVal = resolveOperand(op.arithmetic.left, source);
     const rightVal = resolveOperand(op.arithmetic.right, source);
-    (0, import_utils2.throwIf)(
-      !(0, import_utils2.isNumber)(leftVal) || !(0, import_utils2.isNumber)(rightVal),
-      `Arithmetic operations require number operands, but got ${typeof leftVal} and ${typeof rightVal}.`
-    );
-    switch (op.arithmetic.op) {
-      case "+":
-        return Number(leftVal) + Number(rightVal);
-      case "-":
-        return Number(leftVal) - Number(rightVal);
-      case "*":
-        return Number(leftVal) * Number(rightVal);
-      case "/":
-        return Number(leftVal) / Number(rightVal);
-      default:
-        (0, import_utils2.throwIf)(true, `Unknown arithmetic operator: ${op.arithmetic.op}`);
-    }
+    return resolveMath(op.arithmetic.op, leftVal, rightVal);
   }
-  (0, import_utils2.throwIf)(true, `Unknown operand type: ${JSON.stringify(op)}`);
-  return void 0;
+  return (0, import_utils3.throwError)(`Unknown operand type: ${JSON.stringify(op)}`);
 }
 function resolveOperandAsScalar(op, source) {
   const value = resolveOperand(op, source);
-  (0, import_utils2.throwIf)(
-    !(0, import_utils2.isScalar)(value),
+  (0, import_utils3.throwIf)(
+    !(0, import_utils3.isScalar)(value),
     `Expected a scalar value (string, number, boolean), but got ${typeof value}.`
   );
   return value;
 }
 
 // src/expression-evaluator.ts
-var import_utils3 = require("@axi-engine/utils");
+var import_utils4 = require("@axi-engine/utils");
 var ExpressionEvaluator = class {
   /** @internal A map of registered expression handlers. */
-  handlers = /* @__PURE__ */ new Map();
+  handlers = new import_utils4.Registry();
   /**
    * Registers a new `ExpressionHandler` with the evaluator.
    * This is the primary mechanism for extending the expression language with
@@ -110,8 +116,7 @@ var ExpressionEvaluator = class {
    * is already registered.
    */
   register(handler) {
-    (0, import_utils3.throwIf)(this.handlers.has(handler.type), `Expression handler for: '${handler.type}' expression already registered`);
-    this.handlers.set(handler.type, handler);
+    this.handlers.register(handler.type, handler);
   }
   /**
    * Resolves a given expression against a data source.
@@ -127,9 +132,8 @@ var ExpressionEvaluator = class {
    * evaluation result.
    */
   async resolve(expression, data) {
-    const key = (0, import_utils3.firstKeyOf)(expression);
-    const handler = this.handlers.get(key);
-    (0, import_utils3.throwIfEmpty)(handler, `Can't find expression handler for: '${key}' expression`);
+    const key = (0, import_utils4.firstKeyOf)(expression);
+    const handler = this.handlers.getOrThrow(key);
     const context = {
       resolve: (expression2) => this.resolve(expression2, data),
       source: () => data
@@ -151,7 +155,7 @@ var AndExpressionHandler = class {
 };
 
 // src/handlers/chance-expression-handler.ts
-var import_utils4 = require("@axi-engine/utils");
+var import_utils5 = require("@axi-engine/utils");
 var ChanceExpressionHandler = class {
   type = "chance";
   /**
@@ -172,16 +176,16 @@ var ChanceExpressionHandler = class {
   async resolve(exp, context) {
     const resolvedValue = resolveOperandAsScalar(exp.chance, context.source());
     let numericValue;
-    if ((0, import_utils4.isNumber)(resolvedValue)) {
+    if ((0, import_utils5.isNumber)(resolvedValue)) {
       numericValue = resolvedValue;
-    } else if ((0, import_utils4.isString)(resolvedValue)) {
+    } else if ((0, import_utils5.isString)(resolvedValue)) {
       const parsed = parseFloat(resolvedValue.replace("%", "").trim());
-      (0, import_utils4.throwIf)(isNaN(parsed), `Chance value as a string must be a valid number, but got '${resolvedValue}'.`);
+      (0, import_utils5.throwIf)(isNaN(parsed), `Chance value as a string must be a valid number, but got '${resolvedValue}'.`);
       numericValue = parsed;
     } else {
-      (0, import_utils4.throwIf)(true, `Chance value must be a number or a string, but got a boolean.`);
+      (0, import_utils5.throwError)(`Chance value must be a number or a string, but got a boolean.`);
     }
-    const randomRoll = (0, import_utils4.randInt)(0, 100);
+    const randomRoll = (0, import_utils5.randInt)(0, 100);
     return randomRoll < numericValue;
   }
 };
@@ -218,7 +222,7 @@ var ExistsExpressionHandler = class {
 };
 
 // src/handlers/in-expression-handler.ts
-var import_utils5 = require("@axi-engine/utils");
+var import_utils6 = require("@axi-engine/utils");
 var InExpressionHandler = class {
   type = "in";
   /**
@@ -242,13 +246,13 @@ var InExpressionHandler = class {
   async resolve(exp, context) {
     const value = resolveOperandAsScalar(exp.in.value, context.source());
     const rawArray = Array.isArray(exp.in.array) ? exp.in.array : resolveOperand(exp.in.array, context.source());
-    (0, import_utils5.throwIf)(
+    (0, import_utils6.throwIf)(
       !Array.isArray(rawArray),
       `The 'in' expression requires an array, but the provided source resolved to ${typeof rawArray}.`
     );
     const typedArray = rawArray;
     const resolvedArray = typedArray.map(
-      (item) => (0, import_utils5.isScalar)(item) ? item : resolveOperandAsScalar(item, context.source())
+      (item) => (0, import_utils6.isScalar)(item) ? item : resolveOperandAsScalar(item, context.source())
     );
     return resolvedArray.includes(value);
   }
@@ -293,9 +297,7 @@ function createExpressionEvaluator(additionalHandlers) {
   evaluator.register(new LiteralExpressionHandler());
   evaluator.register(new NotExpressionHandler());
   evaluator.register(new OrExpressionHandler());
-  if (additionalHandlers) {
-    additionalHandlers.forEach((handler) => evaluator.register(handler));
-  }
+  additionalHandlers?.forEach((handler) => evaluator.register(handler));
   return evaluator;
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -314,6 +316,7 @@ function createExpressionEvaluator(additionalHandlers) {
   isOperand,
   isReferenceOperand,
   isValueOperand,
+  resolveMath,
   resolveOperand,
   resolveOperandAsScalar
 });

package/dist/index.mjs

@@ -13,8 +13,29 @@ function isOperand(val) {
   return isValueOperand(val) || isReferenceOperand(val) || isArithmeticOperand(val);
 }
 
+// src/resolve-math.ts
+import { isNumber, throwError, throwIf } from "@axi-engine/utils";
+function resolveMath(op, left, right) {
+  throwIf(
+    !isNumber(left) || !isNumber(right),
+    `Require number operands, but got ${typeof left} and ${typeof right}.`
+  );
+  switch (op) {
+    case "+":
+      return Number(left) + Number(right);
+    case "-":
+      return Number(left) - Number(right);
+    case "*":
+      return Number(left) * Number(right);
+    case "/":
+      return Number(left) / Number(right);
+    default:
+      return throwError(`Unknown arithmetic operator: ${op}`);
+  }
+}
+
 // src/resolve-operand.ts
-import { isNumber, isScalar, throwIf } from "@axi-engine/utils";
+import { isScalar, throwError as throwError2, throwIf as throwIf2 } from "@axi-engine/utils";
 function resolveOperand(op, source) {
   if (isValueOperand(op)) {
     return op.value;
@@ -25,29 +46,13 @@ function resolveOperand(op, source) {
   if (isArithmeticOperand(op)) {
     const leftVal = resolveOperand(op.arithmetic.left, source);
     const rightVal = resolveOperand(op.arithmetic.right, source);
-    throwIf(
-      !isNumber(leftVal) || !isNumber(rightVal),
-      `Arithmetic operations require number operands, but got ${typeof leftVal} and ${typeof rightVal}.`
-    );
-    switch (op.arithmetic.op) {
-      case "+":
-        return Number(leftVal) + Number(rightVal);
-      case "-":
-        return Number(leftVal) - Number(rightVal);
-      case "*":
-        return Number(leftVal) * Number(rightVal);
-      case "/":
-        return Number(leftVal) / Number(rightVal);
-      default:
-        throwIf(true, `Unknown arithmetic operator: ${op.arithmetic.op}`);
-    }
+    return resolveMath(op.arithmetic.op, leftVal, rightVal);
   }
-  throwIf(true, `Unknown operand type: ${JSON.stringify(op)}`);
-  return void 0;
+  return throwError2(`Unknown operand type: ${JSON.stringify(op)}`);
 }
 function resolveOperandAsScalar(op, source) {
   const value = resolveOperand(op, source);
-  throwIf(
+  throwIf2(
     !isScalar(value),
     `Expected a scalar value (string, number, boolean), but got ${typeof value}.`
   );
@@ -56,13 +61,12 @@ function resolveOperandAsScalar(op, source) {
 
 // src/expression-evaluator.ts
 import {
-  throwIf as throwIf2,
-  throwIfEmpty,
-  firstKeyOf
+  firstKeyOf,
+  Registry
 } from "@axi-engine/utils";
 var ExpressionEvaluator = class {
   /** @internal A map of registered expression handlers. */
-  handlers = /* @__PURE__ */ new Map();
+  handlers = new Registry();
   /**
    * Registers a new `ExpressionHandler` with the evaluator.
    * This is the primary mechanism for extending the expression language with
@@ -73,8 +77,7 @@ var ExpressionEvaluator = class {
    * is already registered.
    */
   register(handler) {
-    throwIf2(this.handlers.has(handler.type), `Expression handler for: '${handler.type}' expression already registered`);
-    this.handlers.set(handler.type, handler);
+    this.handlers.register(handler.type, handler);
   }
   /**
    * Resolves a given expression against a data source.
@@ -91,8 +94,7 @@ var ExpressionEvaluator = class {
    */
   async resolve(expression, data) {
     const key = firstKeyOf(expression);
-    const handler = this.handlers.get(key);
-    throwIfEmpty(handler, `Can't find expression handler for: '${key}' expression`);
+    const handler = this.handlers.getOrThrow(key);
     const context = {
       resolve: (expression2) => this.resolve(expression2, data),
       source: () => data
@@ -114,7 +116,7 @@ var AndExpressionHandler = class {
 };
 
 // src/handlers/chance-expression-handler.ts
-import { isNumber as isNumber2, isString, randInt, throwIf as throwIf3 } from "@axi-engine/utils";
+import { isNumber as isNumber2, isString, randInt, throwError as throwError3, throwIf as throwIf3 } from "@axi-engine/utils";
 var ChanceExpressionHandler = class {
   type = "chance";
   /**
@@ -142,7 +144,7 @@ var ChanceExpressionHandler = class {
       throwIf3(isNaN(parsed), `Chance value as a string must be a valid number, but got '${resolvedValue}'.`);
       numericValue = parsed;
     } else {
-      throwIf3(true, `Chance value must be a number or a string, but got a boolean.`);
+      throwError3(`Chance value must be a number or a string, but got a boolean.`);
     }
     const randomRoll = randInt(0, 100);
     return randomRoll < numericValue;
@@ -256,9 +258,7 @@ function createExpressionEvaluator(additionalHandlers) {
   evaluator.register(new LiteralExpressionHandler());
   evaluator.register(new NotExpressionHandler());
   evaluator.register(new OrExpressionHandler());
-  if (additionalHandlers) {
-    additionalHandlers.forEach((handler) => evaluator.register(handler));
-  }
+  additionalHandlers?.forEach((handler) => evaluator.register(handler));
   return evaluator;
 }
 export {
@@ -276,6 +276,7 @@ export {
   isOperand,
   isReferenceOperand,
   isValueOperand,
+  resolveMath,
   resolveOperand,
   resolveOperandAsScalar
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/expressions",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "",
   "license": "MIT",
   "repository": {
@@ -24,18 +24,18 @@
     }
   },
   "scripts": {
-    "test": "vitest run --root ../../ src/",
     "build": "tsup",
     "prebuild": "npm test",
+    "test": "vitest run --root ../../ src/",
     "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json"
   },
   "files": [
     "dist"
   ],
   "devDependencies": {
-    "@axi-engine/utils": "^0.2.3"
+    "@axi-engine/utils": "^0.2.6"
   },
   "peerDependencies": {
-    "@axi-engine/utils": "^0.2.3"
+    "@axi-engine/utils": "^0.2.6"
   }
 }