@axi-engine/expressions 0.2.1

package/dist/index.js

@@ -0,0 +1,319 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AndExpressionHandler: () => AndExpressionHandler,
+  ChanceExpressionHandler: () => ChanceExpressionHandler,
+  ComparisonExpressionHandler: () => ComparisonExpressionHandler,
+  ExistsExpressionHandler: () => ExistsExpressionHandler,
+  ExpressionEvaluator: () => ExpressionEvaluator,
+  InExpressionHandler: () => InExpressionHandler,
+  LiteralExpressionHandler: () => LiteralExpressionHandler,
+  NotExpressionHandler: () => NotExpressionHandler,
+  OrExpressionHandler: () => OrExpressionHandler,
+  createExpressionEvaluator: () => createExpressionEvaluator,
+  isArithmeticOperand: () => isArithmeticOperand,
+  isOperand: () => isOperand,
+  isReferenceOperand: () => isReferenceOperand,
+  isValueOperand: () => isValueOperand,
+  resolveOperand: () => resolveOperand,
+  resolveOperandAsScalar: () => resolveOperandAsScalar
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/guards.ts
+var import_utils = require("@axi-engine/utils");
+function isValueOperand(val) {
+  return !(0, import_utils.isNullOrUndefined)(val) && typeof val === "object" && "value" in val;
+}
+function isReferenceOperand(val) {
+  return !(0, import_utils.isNullOrUndefined)(val) && typeof val === "object" && "path" in val;
+}
+function isArithmeticOperand(val) {
+  return !(0, import_utils.isNullOrUndefined)(val) && typeof val === "object" && "arithmetic" in val;
+}
+function isOperand(val) {
+  return isValueOperand(val) || isReferenceOperand(val) || isArithmeticOperand(val);
+}
+
+// src/resolve-operand.ts
+var import_utils2 = require("@axi-engine/utils");
+function resolveOperand(op, source) {
+  if (isValueOperand(op)) {
+    return op.value;
+  }
+  if (isReferenceOperand(op)) {
+    return source.get(op.path);
+  }
+  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}`);
+    }
+  }
+  (0, import_utils2.throwIf)(true, `Unknown operand type: ${JSON.stringify(op)}`);
+  return void 0;
+}
+function resolveOperandAsScalar(op, source) {
+  const value = resolveOperand(op, source);
+  (0, import_utils2.throwIf)(
+    !(0, import_utils2.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 ExpressionEvaluator = class {
+  /** @internal A map of registered expression handlers. */
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Registers a new `ExpressionHandler` with the evaluator.
+   * This is the primary mechanism for extending the expression language with
+   * custom logic and new expression types.
+   *
+   * @param handler The `ExpressionHandler` instance to register.
+   * @throws {Error} Throws an error if a handler for the same expression type
+   * 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);
+  }
+  /**
+   * Resolves a given expression against a data source.
+   *
+   * This is the main entry point for the evaluation process. It identifies the
+   * expression type by its key, finds the corresponding handler, creates the
+   * evaluation context, and delegates the evaluation task to the handler.
+   *
+   * @param expression The expression object to evaluate.
+   * @param data The `DataSource` to be used for resolving any `ReferenceOperand`s
+   * within the expression tree.
+   * @returns A promise that resolves to `true` or `false` based on the
+   * 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 context = {
+      resolve: (expression2) => this.resolve(expression2, data),
+      source: () => data
+    };
+    return handler.resolve(expression, context);
+  }
+};
+
+// src/handlers/and-expression-handler.ts
+var AndExpressionHandler = class {
+  type = "and";
+  async resolve(exp, context) {
+    const res = [];
+    for (let childExp of exp.and) {
+      res.push(await context.resolve(childExp));
+    }
+    return exp.and.length === res.filter((val) => val).length;
+  }
+};
+
+// src/handlers/chance-expression-handler.ts
+var import_utils4 = require("@axi-engine/utils");
+var ChanceExpressionHandler = class {
+  type = "chance";
+  /**
+   * Resolves the `chance` expression.
+   *
+   * The method first resolves the operand to a scalar value. It supports both
+   * numbers (e.g., `50`) and strings (e.g., `"50"`, `"50%"`), which are parsed
+   * into a numeric percentage. It then generates a random integer from 0 to 99
+   * and returns `true` if this random number is less than the resolved chance value.
+   *
+   * @param exp The `ChanceExpression` object to resolve.
+   * @param context The context for the expression evaluation, providing access to the data source.
+   * @returns {Promise<boolean>} A promise that resolves to `true` if the random roll
+   * succeeds, and `false` otherwise.
+   * @throws {Error} If the operand resolves to a value that cannot be parsed into
+   * a number (e.g., a boolean or a non-numeric string).
+   */
+  async resolve(exp, context) {
+    const resolvedValue = resolveOperandAsScalar(exp.chance, context.source());
+    let numericValue;
+    if ((0, import_utils4.isNumber)(resolvedValue)) {
+      numericValue = resolvedValue;
+    } else if ((0, import_utils4.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}'.`);
+      numericValue = parsed;
+    } else {
+      (0, import_utils4.throwIf)(true, `Chance value must be a number or a string, but got a boolean.`);
+    }
+    const randomRoll = (0, import_utils4.randInt)(0, 100);
+    return randomRoll < numericValue;
+  }
+};
+
+// src/handlers/comparision-expression-handler.ts
+var ComparisonExpressionHandler = class {
+  type = "comparison";
+  async resolve(exp, context) {
+    const left = resolveOperandAsScalar(exp.comparison.left, context.source());
+    const right = resolveOperandAsScalar(exp.comparison.right, context.source());
+    switch (exp.comparison.op) {
+      case "==":
+        return left === right;
+      case "<=":
+        return left <= right;
+      case "<":
+        return left < right;
+      case ">=":
+        return left >= right;
+      case ">":
+        return left > right;
+      case "!=":
+        return left !== right;
+    }
+  }
+};
+
+// src/handlers/exists-expression-handler.ts
+var ExistsExpressionHandler = class {
+  type = "exists";
+  async resolve(exp, context) {
+    return context.source().has(exp.exists);
+  }
+};
+
+// src/handlers/in-expression-handler.ts
+var import_utils5 = require("@axi-engine/utils");
+var InExpressionHandler = class {
+  type = "in";
+  /**
+   * Resolves the `in` expression.
+   *
+   * The method performs the following steps:
+   * 1. Resolves the `value` operand to a scalar.
+   * 2. Obtains the source array, which can be a literal array from the expression
+   *    or the result of resolving the `array` operand.
+   * 3. Ensures the source is a valid array.
+   * 4. Resolves every item within the source array to a scalar value.
+   * 5. Checks if the value from step 1 is included in the resolved array from step 4.
+   *
+   * @param exp The `InExpression` object to resolve.
+   * @param context The context for the expression evaluation, providing the data source.
+   * @returns {Promise<boolean>} A promise that resolves to `true` if the value is found
+   * in the array, and `false` otherwise.
+   * @throws {Error} If the source for the array does not resolve to an array.
+   * @throws {Error} If any operand within the process fails to resolve correctly.
+   */
+  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)(
+      !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())
+    );
+    return resolvedArray.includes(value);
+  }
+};
+
+// src/handlers/literal-expression-handler.ts
+var LiteralExpressionHandler = class {
+  type = "literal";
+  async resolve(exp, _context) {
+    return exp.literal;
+  }
+};
+
+// src/handlers/not-expression-handler.ts
+var NotExpressionHandler = class {
+  type = "not";
+  async resolve(exp, context) {
+    return !await context.resolve(exp.not);
+  }
+};
+
+// src/handlers/or-expression-handler.ts
+var OrExpressionHandler = class {
+  type = "or";
+  async resolve(exp, context) {
+    const res = [];
+    for (let childExp of exp.or) {
+      res.push(await context.resolve(childExp));
+    }
+    return res.filter((val) => val).length > 0;
+  }
+};
+
+// src/setup.ts
+function createExpressionEvaluator(additionalHandlers) {
+  const evaluator = new ExpressionEvaluator();
+  evaluator.register(new AndExpressionHandler());
+  evaluator.register(new ChanceExpressionHandler());
+  evaluator.register(new ComparisonExpressionHandler());
+  evaluator.register(new ExistsExpressionHandler());
+  evaluator.register(new InExpressionHandler());
+  evaluator.register(new LiteralExpressionHandler());
+  evaluator.register(new NotExpressionHandler());
+  evaluator.register(new OrExpressionHandler());
+  if (additionalHandlers) {
+    additionalHandlers.forEach((handler) => evaluator.register(handler));
+  }
+  return evaluator;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AndExpressionHandler,
+  ChanceExpressionHandler,
+  ComparisonExpressionHandler,
+  ExistsExpressionHandler,
+  ExpressionEvaluator,
+  InExpressionHandler,
+  LiteralExpressionHandler,
+  NotExpressionHandler,
+  OrExpressionHandler,
+  createExpressionEvaluator,
+  isArithmeticOperand,
+  isOperand,
+  isReferenceOperand,
+  isValueOperand,
+  resolveOperand,
+  resolveOperandAsScalar
+});

package/dist/index.mjs

@@ -0,0 +1,281 @@
+// src/guards.ts
+import { isNullOrUndefined } from "@axi-engine/utils";
+function isValueOperand(val) {
+  return !isNullOrUndefined(val) && typeof val === "object" && "value" in val;
+}
+function isReferenceOperand(val) {
+  return !isNullOrUndefined(val) && typeof val === "object" && "path" in val;
+}
+function isArithmeticOperand(val) {
+  return !isNullOrUndefined(val) && typeof val === "object" && "arithmetic" in val;
+}
+function isOperand(val) {
+  return isValueOperand(val) || isReferenceOperand(val) || isArithmeticOperand(val);
+}
+
+// src/resolve-operand.ts
+import { isNumber, isScalar, throwIf } from "@axi-engine/utils";
+function resolveOperand(op, source) {
+  if (isValueOperand(op)) {
+    return op.value;
+  }
+  if (isReferenceOperand(op)) {
+    return source.get(op.path);
+  }
+  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}`);
+    }
+  }
+  throwIf(true, `Unknown operand type: ${JSON.stringify(op)}`);
+  return void 0;
+}
+function resolveOperandAsScalar(op, source) {
+  const value = resolveOperand(op, source);
+  throwIf(
+    !isScalar(value),
+    `Expected a scalar value (string, number, boolean), but got ${typeof value}.`
+  );
+  return value;
+}
+
+// src/expression-evaluator.ts
+import {
+  throwIf as throwIf2,
+  throwIfEmpty,
+  firstKeyOf
+} from "@axi-engine/utils";
+var ExpressionEvaluator = class {
+  /** @internal A map of registered expression handlers. */
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Registers a new `ExpressionHandler` with the evaluator.
+   * This is the primary mechanism for extending the expression language with
+   * custom logic and new expression types.
+   *
+   * @param handler The `ExpressionHandler` instance to register.
+   * @throws {Error} Throws an error if a handler for the same expression type
+   * 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);
+  }
+  /**
+   * Resolves a given expression against a data source.
+   *
+   * This is the main entry point for the evaluation process. It identifies the
+   * expression type by its key, finds the corresponding handler, creates the
+   * evaluation context, and delegates the evaluation task to the handler.
+   *
+   * @param expression The expression object to evaluate.
+   * @param data The `DataSource` to be used for resolving any `ReferenceOperand`s
+   * within the expression tree.
+   * @returns A promise that resolves to `true` or `false` based on the
+   * evaluation result.
+   */
+  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 context = {
+      resolve: (expression2) => this.resolve(expression2, data),
+      source: () => data
+    };
+    return handler.resolve(expression, context);
+  }
+};
+
+// src/handlers/and-expression-handler.ts
+var AndExpressionHandler = class {
+  type = "and";
+  async resolve(exp, context) {
+    const res = [];
+    for (let childExp of exp.and) {
+      res.push(await context.resolve(childExp));
+    }
+    return exp.and.length === res.filter((val) => val).length;
+  }
+};
+
+// src/handlers/chance-expression-handler.ts
+import { isNumber as isNumber2, isString, randInt, throwIf as throwIf3 } from "@axi-engine/utils";
+var ChanceExpressionHandler = class {
+  type = "chance";
+  /**
+   * Resolves the `chance` expression.
+   *
+   * The method first resolves the operand to a scalar value. It supports both
+   * numbers (e.g., `50`) and strings (e.g., `"50"`, `"50%"`), which are parsed
+   * into a numeric percentage. It then generates a random integer from 0 to 99
+   * and returns `true` if this random number is less than the resolved chance value.
+   *
+   * @param exp The `ChanceExpression` object to resolve.
+   * @param context The context for the expression evaluation, providing access to the data source.
+   * @returns {Promise<boolean>} A promise that resolves to `true` if the random roll
+   * succeeds, and `false` otherwise.
+   * @throws {Error} If the operand resolves to a value that cannot be parsed into
+   * a number (e.g., a boolean or a non-numeric string).
+   */
+  async resolve(exp, context) {
+    const resolvedValue = resolveOperandAsScalar(exp.chance, context.source());
+    let numericValue;
+    if (isNumber2(resolvedValue)) {
+      numericValue = resolvedValue;
+    } else if (isString(resolvedValue)) {
+      const parsed = parseFloat(resolvedValue.replace("%", "").trim());
+      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.`);
+    }
+    const randomRoll = randInt(0, 100);
+    return randomRoll < numericValue;
+  }
+};
+
+// src/handlers/comparision-expression-handler.ts
+var ComparisonExpressionHandler = class {
+  type = "comparison";
+  async resolve(exp, context) {
+    const left = resolveOperandAsScalar(exp.comparison.left, context.source());
+    const right = resolveOperandAsScalar(exp.comparison.right, context.source());
+    switch (exp.comparison.op) {
+      case "==":
+        return left === right;
+      case "<=":
+        return left <= right;
+      case "<":
+        return left < right;
+      case ">=":
+        return left >= right;
+      case ">":
+        return left > right;
+      case "!=":
+        return left !== right;
+    }
+  }
+};
+
+// src/handlers/exists-expression-handler.ts
+var ExistsExpressionHandler = class {
+  type = "exists";
+  async resolve(exp, context) {
+    return context.source().has(exp.exists);
+  }
+};
+
+// src/handlers/in-expression-handler.ts
+import { isScalar as isScalar2, throwIf as throwIf4 } from "@axi-engine/utils";
+var InExpressionHandler = class {
+  type = "in";
+  /**
+   * Resolves the `in` expression.
+   *
+   * The method performs the following steps:
+   * 1. Resolves the `value` operand to a scalar.
+   * 2. Obtains the source array, which can be a literal array from the expression
+   *    or the result of resolving the `array` operand.
+   * 3. Ensures the source is a valid array.
+   * 4. Resolves every item within the source array to a scalar value.
+   * 5. Checks if the value from step 1 is included in the resolved array from step 4.
+   *
+   * @param exp The `InExpression` object to resolve.
+   * @param context The context for the expression evaluation, providing the data source.
+   * @returns {Promise<boolean>} A promise that resolves to `true` if the value is found
+   * in the array, and `false` otherwise.
+   * @throws {Error} If the source for the array does not resolve to an array.
+   * @throws {Error} If any operand within the process fails to resolve correctly.
+   */
+  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());
+    throwIf4(
+      !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) => isScalar2(item) ? item : resolveOperandAsScalar(item, context.source())
+    );
+    return resolvedArray.includes(value);
+  }
+};
+
+// src/handlers/literal-expression-handler.ts
+var LiteralExpressionHandler = class {
+  type = "literal";
+  async resolve(exp, _context) {
+    return exp.literal;
+  }
+};
+
+// src/handlers/not-expression-handler.ts
+var NotExpressionHandler = class {
+  type = "not";
+  async resolve(exp, context) {
+    return !await context.resolve(exp.not);
+  }
+};
+
+// src/handlers/or-expression-handler.ts
+var OrExpressionHandler = class {
+  type = "or";
+  async resolve(exp, context) {
+    const res = [];
+    for (let childExp of exp.or) {
+      res.push(await context.resolve(childExp));
+    }
+    return res.filter((val) => val).length > 0;
+  }
+};
+
+// src/setup.ts
+function createExpressionEvaluator(additionalHandlers) {
+  const evaluator = new ExpressionEvaluator();
+  evaluator.register(new AndExpressionHandler());
+  evaluator.register(new ChanceExpressionHandler());
+  evaluator.register(new ComparisonExpressionHandler());
+  evaluator.register(new ExistsExpressionHandler());
+  evaluator.register(new InExpressionHandler());
+  evaluator.register(new LiteralExpressionHandler());
+  evaluator.register(new NotExpressionHandler());
+  evaluator.register(new OrExpressionHandler());
+  if (additionalHandlers) {
+    additionalHandlers.forEach((handler) => evaluator.register(handler));
+  }
+  return evaluator;
+}
+export {
+  AndExpressionHandler,
+  ChanceExpressionHandler,
+  ComparisonExpressionHandler,
+  ExistsExpressionHandler,
+  ExpressionEvaluator,
+  InExpressionHandler,
+  LiteralExpressionHandler,
+  NotExpressionHandler,
+  OrExpressionHandler,
+  createExpressionEvaluator,
+  isArithmeticOperand,
+  isOperand,
+  isReferenceOperand,
+  isValueOperand,
+  resolveOperand,
+  resolveOperandAsScalar
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@axi-engine/expressions",
+  "version": "0.2.1",
+  "description": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axijs/engine.git",
+    "directory": "packages/expressions"
+  },
+  "keywords": [
+    "axi-engine",
+    "typescript",
+    "gamedev"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run --root ../../ src/",
+    "build": "tsup",
+    "prebuild": "npm test",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@axi-engine/utils": "^0.2.3"
+  },
+  "peerDependencies": {
+    "@axi-engine/utils": "^0.2.3"
+  }
+}