@axi-engine/expressions 0.2.3 → 0.2.4

package/dist/index.d.mts

@@ -302,6 +302,53 @@ interface ExpressionEvaluatorContext {
      */
     source(): DataSource;
 }
+
+/**
+ * Defines the contract for a class that can evaluate a specific type of expression.
+ *
+ * Each expression type in the system (e.g., `comparison`, `and`, `in`) must have a
+ * corresponding class that implements this interface. The `ExpressionEvaluator` uses these
+ * handlers to delegate the actual evaluation logic.
+ *
+ * @interface
+ * @template T - The specific `Expression` subtype that this handler is responsible for.
+ *   This provides strong typing within the `resolve` method.
+ */
+interface ExpressionHandler<T extends Expression = Expression> {
+    /**
+     * The unique key for the expression type this handler processes.
+     * This must match one of the keys in the `ExpressionDefinitions` interface.
+     */
+    type: ExpressionName;
+    /**
+     * The core evaluation logic for the expression.
+     *
+     * @param exp The specific expression object to be evaluated, strongly typed to `T`.
+     * @param context The `ExpressionEvaluatorContext` which provides tools for the
+     *   handler, such as a way to recursively resolve child expressions or access the
+     *   data source.
+     * @returns {Promise<boolean>} A promise that resolves to the boolean result of the evaluation.
+     */
+    resolve(exp: T, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+/**
+ *
+ * Defines the contract for an engine capable of evaluating logical expression trees.
+ *
+ * @interface
+ */
+interface ExpressionEvaluator {
+    /**
+     * Evaluates a logical expression against a provided data source.
+     *
+     * @param expression The expression tree to evaluate.
+     * @param data The data source used to resolve variable references within the expression.
+     * @returns A promise that resolves to `true` or `false` based on the evaluation result.
+     */
+    resolve(expression: Expression, data: DataSource): Promise<boolean>;
+}
+
 /**
  * The class responsible for evaluating expression trees.
  *
@@ -315,7 +362,7 @@ interface ExpressionEvaluatorContext {
  *
  * @class
  */
-declare class ExpressionEvaluator {
+declare class CoreExpressionEvaluator implements ExpressionEvaluator {
     /** @internal A map of registered expression handlers. */
     handlers: Registry<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
     /**
@@ -344,35 +391,6 @@ declare class ExpressionEvaluator {
     resolve(expression: Expression, data: DataSource): Promise<boolean>;
 }
 
-/**
- * Defines the contract for a class that can evaluate a specific type of expression.
- *
- * Each expression type in the system (e.g., `comparison`, `and`, `in`) must have a
- * corresponding class that implements this interface. The `ExpressionEvaluator` uses these
- * handlers to delegate the actual evaluation logic.
- *
- * @interface
- * @template T - The specific `Expression` subtype that this handler is responsible for.
- *   This provides strong typing within the `resolve` method.
- */
-interface ExpressionHandler<T extends Expression = Expression> {
-    /**
-     * The unique key for the expression type this handler processes.
-     * This must match one of the keys in the `ExpressionDefinitions` interface.
-     */
-    type: ExpressionName;
-    /**
-     * The core evaluation logic for the expression.
-     *
-     * @param exp The specific expression object to be evaluated, strongly typed to `T`.
-     * @param context The `ExpressionEvaluatorContext` which provides tools for the
-     *   handler, such as a way to recursively resolve child expressions or access the
-     *   data source.
-     * @returns {Promise<boolean>} A promise that resolves to the boolean result of the evaluation.
-     */
-    resolve(exp: T, context: ExpressionEvaluatorContext): Promise<boolean>;
-}
-
 declare class AndExpressionHandler implements ExpressionHandler<AndExpression> {
     type: ExpressionName;
     resolve(exp: AndExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
@@ -461,30 +479,30 @@ declare class OrExpressionHandler implements ExpressionHandler<OrExpression> {
 }
 
 /**
- * A factory function that creates and initializes an `ExpressionEvaluator` instance.
- *
- * This is the recommended way to set up the evaluator, as it comes pre-configured
- * with handlers for all core expression types (logical, comparison, chance, etc.).
- * It also provides a simple way to extend the evaluator with custom logic by passing
- * additional handlers.
- *
- * @param {ExpressionHandler[]} [additionalHandlers] - An optional array of custom
- *   `ExpressionHandler` instances to register in addition to the core ones. This allows for
- *   extending the expression language with new capabilities.
- * @returns {ExpressionEvaluator} A fully configured `ExpressionEvaluator` instance,
- *   ready for resolving expressions.
- *
- * @example
- * // Basic setup with only core handlers
- * const coreEvaluator = createExpressionEvaluator();
- * const result = await coreEvaluator.resolve(someExpression, dataSource);
- *
- * @example
- * // Setup with a custom handler for a new expression type
- * const customHandlers = [new MyCustomExpressionHandler()];
- * const extendedEvaluator = createExpressionEvaluator(customHandlers);
- * const customResult = await extendedEvaluator.resolve(myCustomExpression, dataSource);
+ * A builder class for configuring and creating a `CoreExpressionEvaluator`.
+ * Allows enabling standard handlers or registering custom ones via a fluent API.
+ */
+declare class ExpressionEvaluatorBuilder {
+    private handlers;
+    /**
+     * Adds the complete set of standard expression handlers to the configuration.
+     * This is the recommended starting point for most applications.
+     */
+    withDefaults(): this;
+    /**
+     * Registers one or more custom expression handlers.
+     * @param handler A single handler instance or an array of handlers.
+     */
+    add(handler: ExpressionHandler | ExpressionHandler[]): this;
+    /**
+     * @return CoreExpressionEvaluator
+     */
+    build(): CoreExpressionEvaluator;
+}
+/**
+ * Entry point to start configuring the expression evaluator.
+ * @returns A new builder instance.
  */
-declare function createExpressionEvaluator(additionalHandlers?: ExpressionHandler[]): ExpressionEvaluator;
+declare function configureExpressions(): ExpressionEvaluatorBuilder;
 
-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 };
+export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, CoreExpressionEvaluator, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, type ExpressionEvaluator, ExpressionEvaluatorBuilder, 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, configureExpressions, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveMath, resolveOperand, resolveOperandAsScalar };

package/dist/index.d.ts

@@ -302,6 +302,53 @@ interface ExpressionEvaluatorContext {
      */
     source(): DataSource;
 }
+
+/**
+ * Defines the contract for a class that can evaluate a specific type of expression.
+ *
+ * Each expression type in the system (e.g., `comparison`, `and`, `in`) must have a
+ * corresponding class that implements this interface. The `ExpressionEvaluator` uses these
+ * handlers to delegate the actual evaluation logic.
+ *
+ * @interface
+ * @template T - The specific `Expression` subtype that this handler is responsible for.
+ *   This provides strong typing within the `resolve` method.
+ */
+interface ExpressionHandler<T extends Expression = Expression> {
+    /**
+     * The unique key for the expression type this handler processes.
+     * This must match one of the keys in the `ExpressionDefinitions` interface.
+     */
+    type: ExpressionName;
+    /**
+     * The core evaluation logic for the expression.
+     *
+     * @param exp The specific expression object to be evaluated, strongly typed to `T`.
+     * @param context The `ExpressionEvaluatorContext` which provides tools for the
+     *   handler, such as a way to recursively resolve child expressions or access the
+     *   data source.
+     * @returns {Promise<boolean>} A promise that resolves to the boolean result of the evaluation.
+     */
+    resolve(exp: T, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+/**
+ *
+ * Defines the contract for an engine capable of evaluating logical expression trees.
+ *
+ * @interface
+ */
+interface ExpressionEvaluator {
+    /**
+     * Evaluates a logical expression against a provided data source.
+     *
+     * @param expression The expression tree to evaluate.
+     * @param data The data source used to resolve variable references within the expression.
+     * @returns A promise that resolves to `true` or `false` based on the evaluation result.
+     */
+    resolve(expression: Expression, data: DataSource): Promise<boolean>;
+}
+
 /**
  * The class responsible for evaluating expression trees.
  *
@@ -315,7 +362,7 @@ interface ExpressionEvaluatorContext {
  *
  * @class
  */
-declare class ExpressionEvaluator {
+declare class CoreExpressionEvaluator implements ExpressionEvaluator {
     /** @internal A map of registered expression handlers. */
     handlers: Registry<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
     /**
@@ -344,35 +391,6 @@ declare class ExpressionEvaluator {
     resolve(expression: Expression, data: DataSource): Promise<boolean>;
 }
 
-/**
- * Defines the contract for a class that can evaluate a specific type of expression.
- *
- * Each expression type in the system (e.g., `comparison`, `and`, `in`) must have a
- * corresponding class that implements this interface. The `ExpressionEvaluator` uses these
- * handlers to delegate the actual evaluation logic.
- *
- * @interface
- * @template T - The specific `Expression` subtype that this handler is responsible for.
- *   This provides strong typing within the `resolve` method.
- */
-interface ExpressionHandler<T extends Expression = Expression> {
-    /**
-     * The unique key for the expression type this handler processes.
-     * This must match one of the keys in the `ExpressionDefinitions` interface.
-     */
-    type: ExpressionName;
-    /**
-     * The core evaluation logic for the expression.
-     *
-     * @param exp The specific expression object to be evaluated, strongly typed to `T`.
-     * @param context The `ExpressionEvaluatorContext` which provides tools for the
-     *   handler, such as a way to recursively resolve child expressions or access the
-     *   data source.
-     * @returns {Promise<boolean>} A promise that resolves to the boolean result of the evaluation.
-     */
-    resolve(exp: T, context: ExpressionEvaluatorContext): Promise<boolean>;
-}
-
 declare class AndExpressionHandler implements ExpressionHandler<AndExpression> {
     type: ExpressionName;
     resolve(exp: AndExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
@@ -461,30 +479,30 @@ declare class OrExpressionHandler implements ExpressionHandler<OrExpression> {
 }
 
 /**
- * A factory function that creates and initializes an `ExpressionEvaluator` instance.
- *
- * This is the recommended way to set up the evaluator, as it comes pre-configured
- * with handlers for all core expression types (logical, comparison, chance, etc.).
- * It also provides a simple way to extend the evaluator with custom logic by passing
- * additional handlers.
- *
- * @param {ExpressionHandler[]} [additionalHandlers] - An optional array of custom
- *   `ExpressionHandler` instances to register in addition to the core ones. This allows for
- *   extending the expression language with new capabilities.
- * @returns {ExpressionEvaluator} A fully configured `ExpressionEvaluator` instance,
- *   ready for resolving expressions.
- *
- * @example
- * // Basic setup with only core handlers
- * const coreEvaluator = createExpressionEvaluator();
- * const result = await coreEvaluator.resolve(someExpression, dataSource);
- *
- * @example
- * // Setup with a custom handler for a new expression type
- * const customHandlers = [new MyCustomExpressionHandler()];
- * const extendedEvaluator = createExpressionEvaluator(customHandlers);
- * const customResult = await extendedEvaluator.resolve(myCustomExpression, dataSource);
+ * A builder class for configuring and creating a `CoreExpressionEvaluator`.
+ * Allows enabling standard handlers or registering custom ones via a fluent API.
+ */
+declare class ExpressionEvaluatorBuilder {
+    private handlers;
+    /**
+     * Adds the complete set of standard expression handlers to the configuration.
+     * This is the recommended starting point for most applications.
+     */
+    withDefaults(): this;
+    /**
+     * Registers one or more custom expression handlers.
+     * @param handler A single handler instance or an array of handlers.
+     */
+    add(handler: ExpressionHandler | ExpressionHandler[]): this;
+    /**
+     * @return CoreExpressionEvaluator
+     */
+    build(): CoreExpressionEvaluator;
+}
+/**
+ * Entry point to start configuring the expression evaluator.
+ * @returns A new builder instance.
  */
-declare function createExpressionEvaluator(additionalHandlers?: ExpressionHandler[]): ExpressionEvaluator;
+declare function configureExpressions(): ExpressionEvaluatorBuilder;
 
-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 };
+export { type AndExpression, AndExpressionHandler, type ArithmeticOperand, type ChanceExpression, ChanceExpressionHandler, type ComparisonExpression, ComparisonExpressionHandler, type ComparisonOperationType, CoreExpressionEvaluator, type ExistsExpression, ExistsExpressionHandler, type Expression, type ExpressionDefinitions, type ExpressionEvaluator, ExpressionEvaluatorBuilder, 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, configureExpressions, isArithmeticOperand, isOperand, isReferenceOperand, isValueOperand, resolveMath, resolveOperand, resolveOperandAsScalar };

package/dist/index.js

@@ -23,13 +23,14 @@ __export(index_exports, {
   AndExpressionHandler: () => AndExpressionHandler,
   ChanceExpressionHandler: () => ChanceExpressionHandler,
   ComparisonExpressionHandler: () => ComparisonExpressionHandler,
+  CoreExpressionEvaluator: () => CoreExpressionEvaluator,
   ExistsExpressionHandler: () => ExistsExpressionHandler,
-  ExpressionEvaluator: () => ExpressionEvaluator,
+  ExpressionEvaluatorBuilder: () => ExpressionEvaluatorBuilder,
   InExpressionHandler: () => InExpressionHandler,
   LiteralExpressionHandler: () => LiteralExpressionHandler,
   NotExpressionHandler: () => NotExpressionHandler,
   OrExpressionHandler: () => OrExpressionHandler,
-  createExpressionEvaluator: () => createExpressionEvaluator,
+  configureExpressions: () => configureExpressions,
   isArithmeticOperand: () => isArithmeticOperand,
   isOperand: () => isOperand,
   isReferenceOperand: () => isReferenceOperand,
@@ -101,9 +102,9 @@ function resolveOperandAsScalar(op, source) {
   return value;
 }
 
-// src/expression-evaluator.ts
+// src/core-expression-evaluator.ts
 var import_utils4 = require("@axi-engine/utils");
-var ExpressionEvaluator = class {
+var CoreExpressionEvaluator = class {
   /** @internal A map of registered expression handlers. */
   handlers = new import_utils4.Registry();
   /**
@@ -287,31 +288,65 @@ var OrExpressionHandler = class {
 };
 
 // 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());
-  additionalHandlers?.forEach((handler) => evaluator.register(handler));
-  return evaluator;
+function createDefaultExpressionHandlers() {
+  return [
+    new AndExpressionHandler(),
+    new ChanceExpressionHandler(),
+    new ComparisonExpressionHandler(),
+    new ExistsExpressionHandler(),
+    new InExpressionHandler(),
+    new LiteralExpressionHandler(),
+    new NotExpressionHandler(),
+    new OrExpressionHandler()
+  ];
+}
+var ExpressionEvaluatorBuilder = class {
+  handlers = [];
+  /**
+   * Adds the complete set of standard expression handlers to the configuration.
+   * This is the recommended starting point for most applications.
+   */
+  withDefaults() {
+    this.handlers.push(...createDefaultExpressionHandlers());
+    return this;
+  }
+  /**
+   * Registers one or more custom expression handlers.
+   * @param handler A single handler instance or an array of handlers.
+   */
+  add(handler) {
+    if (!Array.isArray(handler)) {
+      this.handlers.push(handler);
+    } else {
+      this.handlers.push(...handler);
+    }
+    return this;
+  }
+  /**
+   * @return CoreExpressionEvaluator
+   */
+  build() {
+    const evaluator = new CoreExpressionEvaluator();
+    this.handlers.forEach((handler) => evaluator.register(handler));
+    return evaluator;
+  }
+};
+function configureExpressions() {
+  return new ExpressionEvaluatorBuilder();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AndExpressionHandler,
   ChanceExpressionHandler,
   ComparisonExpressionHandler,
+  CoreExpressionEvaluator,
   ExistsExpressionHandler,
-  ExpressionEvaluator,
+  ExpressionEvaluatorBuilder,
   InExpressionHandler,
   LiteralExpressionHandler,
   NotExpressionHandler,
   OrExpressionHandler,
-  createExpressionEvaluator,
+  configureExpressions,
   isArithmeticOperand,
   isOperand,
   isReferenceOperand,

package/dist/index.mjs

@@ -59,12 +59,12 @@ function resolveOperandAsScalar(op, source) {
   return value;
 }
 
-// src/expression-evaluator.ts
+// src/core-expression-evaluator.ts
 import {
   firstKeyOf,
   Registry
 } from "@axi-engine/utils";
-var ExpressionEvaluator = class {
+var CoreExpressionEvaluator = class {
   /** @internal A map of registered expression handlers. */
   handlers = new Registry();
   /**
@@ -248,30 +248,64 @@ var OrExpressionHandler = class {
 };
 
 // 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());
-  additionalHandlers?.forEach((handler) => evaluator.register(handler));
-  return evaluator;
+function createDefaultExpressionHandlers() {
+  return [
+    new AndExpressionHandler(),
+    new ChanceExpressionHandler(),
+    new ComparisonExpressionHandler(),
+    new ExistsExpressionHandler(),
+    new InExpressionHandler(),
+    new LiteralExpressionHandler(),
+    new NotExpressionHandler(),
+    new OrExpressionHandler()
+  ];
+}
+var ExpressionEvaluatorBuilder = class {
+  handlers = [];
+  /**
+   * Adds the complete set of standard expression handlers to the configuration.
+   * This is the recommended starting point for most applications.
+   */
+  withDefaults() {
+    this.handlers.push(...createDefaultExpressionHandlers());
+    return this;
+  }
+  /**
+   * Registers one or more custom expression handlers.
+   * @param handler A single handler instance or an array of handlers.
+   */
+  add(handler) {
+    if (!Array.isArray(handler)) {
+      this.handlers.push(handler);
+    } else {
+      this.handlers.push(...handler);
+    }
+    return this;
+  }
+  /**
+   * @return CoreExpressionEvaluator
+   */
+  build() {
+    const evaluator = new CoreExpressionEvaluator();
+    this.handlers.forEach((handler) => evaluator.register(handler));
+    return evaluator;
+  }
+};
+function configureExpressions() {
+  return new ExpressionEvaluatorBuilder();
 }
 export {
   AndExpressionHandler,
   ChanceExpressionHandler,
   ComparisonExpressionHandler,
+  CoreExpressionEvaluator,
   ExistsExpressionHandler,
-  ExpressionEvaluator,
+  ExpressionEvaluatorBuilder,
   InExpressionHandler,
   LiteralExpressionHandler,
   NotExpressionHandler,
   OrExpressionHandler,
-  createExpressionEvaluator,
+  configureExpressions,
   isArithmeticOperand,
   isOperand,
   isReferenceOperand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/expressions",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "",
   "license": "MIT",
   "repository": {