@axi-engine/expressions 0.2.2 → 0.2.4

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.
@@ -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,9 +362,9 @@ interface ExpressionEvaluatorContext {
  *
  * @class
  */
-declare class ExpressionEvaluator {
+declare class CoreExpressionEvaluator implements 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
@@ -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

@@ -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.
@@ -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,9 +362,9 @@ interface ExpressionEvaluatorContext {
  *
  * @class
  */
-declare class ExpressionEvaluator {
+declare class CoreExpressionEvaluator implements 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
@@ -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,11 +102,11 @@ 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 = /* @__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
@@ -116,8 +117,7 @@ var ExpressionEvaluator = class {
    * is already registered.
    */
   register(handler) {
-    (0, import_utils4.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.
@@ -134,8 +134,7 @@ var ExpressionEvaluator = class {
    */
   async resolve(expression, data) {
     const key = (0, import_utils4.firstKeyOf)(expression);
-    const handler = this.handlers.get(key);
-    (0, import_utils4.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
@@ -289,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,15 +59,14 @@ function resolveOperandAsScalar(op, source) {
   return value;
 }
 
-// src/expression-evaluator.ts
+// src/core-expression-evaluator.ts
 import {
-  throwIf as throwIf3,
-  throwIfEmpty,
-  firstKeyOf
+  firstKeyOf,
+  Registry
 } from "@axi-engine/utils";
-var ExpressionEvaluator = class {
+var CoreExpressionEvaluator = 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
@@ -78,8 +77,7 @@ var ExpressionEvaluator = class {
    * is already registered.
    */
   register(handler) {
-    throwIf3(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.
@@ -96,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
@@ -119,7 +116,7 @@ var AndExpressionHandler = class {
 };
 
 // src/handlers/chance-expression-handler.ts
-import { isNumber as isNumber2, isString, randInt, throwError as throwError3, throwIf as throwIf4 } 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";
   /**
@@ -144,7 +141,7 @@ var ChanceExpressionHandler = class {
       numericValue = resolvedValue;
     } else if (isString(resolvedValue)) {
       const parsed = parseFloat(resolvedValue.replace("%", "").trim());
-      throwIf4(isNaN(parsed), `Chance value as a string must be a valid number, but got '${resolvedValue}'.`);
+      throwIf3(isNaN(parsed), `Chance value as a string must be a valid number, but got '${resolvedValue}'.`);
       numericValue = parsed;
     } else {
       throwError3(`Chance value must be a number or a string, but got a boolean.`);
@@ -186,7 +183,7 @@ var ExistsExpressionHandler = class {
 };
 
 // src/handlers/in-expression-handler.ts
-import { isScalar as isScalar2, throwIf as throwIf5 } from "@axi-engine/utils";
+import { isScalar as isScalar2, throwIf as throwIf4 } from "@axi-engine/utils";
 var InExpressionHandler = class {
   type = "in";
   /**
@@ -210,7 +207,7 @@ 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());
-    throwIf5(
+    throwIf4(
       !Array.isArray(rawArray),
       `The 'in' expression requires an array, but the provided source resolved to ${typeof rawArray}.`
     );
@@ -251,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.2",
+  "version": "0.2.4",
   "description": "",
   "license": "MIT",
   "repository": {
@@ -33,9 +33,9 @@
     "dist"
   ],
   "devDependencies": {
-    "@axi-engine/utils": "^0.2.5"
+    "@axi-engine/utils": "^0.2.6"
   },
   "peerDependencies": {
-    "@axi-engine/utils": "^0.2.5"
+    "@axi-engine/utils": "^0.2.6"
   }
 }