@axi-engine/expressions 0.2.1

package/README.md

@@ -0,0 +1,179 @@
+# @axi-engine/expressions
+
+[![NPM version](https://img.shields.io/npm/v/@axi-engine/expressions.svg)](https://www.npmjs.com/package/@axi-engine/expressions)
+
+A flexible, type-safe, and extensible engine for evaluating declarative logical expressions.
+It allows you to define complex game logic (like quest conditions, dialogue triggers, or AI behavior) in data files (e.g., JSON) instead of hard-coding it.
+
+## Key Features
+
+-   **Declarative Logic:** Define complex conditions as data, making them easy to author, modify, and store.
+-   **Type-Safe:** Built entirely with TypeScript, providing strong type checking and autocompletion.
+-   **Extensible:** Easily add your own custom expression types and logic by creating new handlers.
+-   **Asynchronous by Design:** Core evaluation is promise-based, allowing for future async operations.
+-   **Decoupled:**  Depends only on @axi-engine/utils for shared types and a simple DataSource interface, making it easy to integrate with any state management system.
+
+## Installation
+
+```bash
+npm install @axi-engine/expressions
+```
+
+## Core Concepts
+
+- **`Expression`**: A plain JavaScript object that defines a logical condition (e.g., `comparison`, `and`, `or`).
+- **`DataSource`**: A simple interface (`{ get(path), has(path) }`) that provides the data against which expressions are evaluated. This can be your game's state manager, a local scope, or any other data source.
+- **`ExpressionEvaluator`**: The main class that takes an `Expression` and a `DataSource` and resolves them to a boolean result.
+
+## Basic Usage
+
+Here's how to set up the evaluator and resolve a simple expression.
+
+```typescript
+import { createExpressionEvaluator } from '@axi-engine/expressions';
+import type { Expression } from '@axi-engine/expressions';
+import type { DataSource } from '@axi-engine/utils';
+
+// 1. Create the evaluator (it comes with all core handlers pre-registered)
+const evaluator = createExpressionEvaluator();
+
+// 2. Define a data source that provides the state
+const myGameDataSource: DataSource = {
+  get: (path) => {
+    const state = new Map<string, any>([
+      ['player.level', 10],
+      ['player.class', 'mage'],
+      ['gate.locked', true],
+    ]);
+    return state.get(path.join('.'));
+  },
+  has: (path) => { /* ... */ }
+};
+
+// 3. Define an expression, for example in a JSON file or directly in code
+const canOpenGate: Expression = {
+  and: [
+    {
+      comparison: {
+        op: '>=',
+        left: { path: ['player', 'level'] },
+        right: { value: 5 }
+      }
+    },
+    {
+      comparison: {
+        op: '==',
+        left: { path: ['gate', 'locked'] },
+        right: { value: true }
+      }
+    }
+  ]
+};
+
+// 4. Resolve the expression
+async function checkCondition() {
+  const result = await evaluator.resolve(canOpenGate, myGameDataSource);
+  console.log('Can the player open the gate?', result); // -> true
+}
+
+checkCondition();
+```
+
+## Built-in Expressions
+
+Here are some examples of the core expression types available out of the box.
+
+| Type             | Example                                                                                 | Description                                                                                                           |
+|:-----------------|:----------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------|
+| **`comparison`** | `{ "comparison": { "op": ">", "left": { "path": "p.hp" }, "right": { "value": 50 } } }` | Compares two values.                                                                                                  |
+| **`and`**        | `{ "and": [ { ...expr1 }, { ...expr2 } ] }`                                             | Returns `true` if all child expressions are true.                                                                     |
+| **`or`**         | `{ "or": [ { ...expr1 }, { ...expr2 } ] }`                                              | Returns `true` if at least one child expression is true.                                                              |
+| **`not`**        | `{ "not": { "exists": "p.curse" } }`                                                    | Inverts the result of a child expression.                                                                             |
+| **`exists`**     | `{ "exists": "p.inventory.key" }`                                                       | Returns `true` if a value exists at the given path.                                                                   |
+| **`in`**         | `{ "in": { "value": { "path": "p.class" }, "array": ["mage", "warlock"] } }`            | Checks if a value is present in an array. The array can also be a reference: `"array": { "path": "q.valid_classes" }` |
+| **`chance`**     | `{ "chance": { "value": 15.5 } }`                                                       | Returns `true` based on a 15.5% probability.                                                                          |
+| **`literal`**    | `{ "literal": true }`                                                                   | Directly returns `true` or `false`. Useful for debugging.                                                             |
+
+## Extending with Custom Expressions
+
+Adding your own expression types is straightforward. Let's create a `between` expression.
+
+**1. Define the Expression Type**
+Create an interface for your new expression.
+
+```typescript
+// my-expressions.ts
+import type { Operand } from '@axi-engine/expressions';
+
+export interface BetweenExpression {
+  between: {
+    value: Operand,
+    min: Operand,
+    max: Operand
+  }
+}
+```
+
+**2. Augment the Global Definitions**
+
+Use TypeScript's declaration merging to make the evaluator aware of your new type.
+
+```typescript
+// my-expressions.ts
+import type { ExpressionDefinitions } from '@axi-engine/expressions';
+
+declare module '@axi-engine/expressions' {
+  export interface ExpressionDefinitions {
+    between: BetweenExpression;
+  }
+}
+```
+
+**3. Create the Handler**
+
+Write the class that contains the evaluation logic.
+
+```typescript
+// BetweenExpressionHandler.ts
+import { ExpressionHandler, resolveOperandAsScalar } from '@axi-engine/expressions';
+import { isNumber } from '@axi-engine/utils';
+
+class BetweenExpressionHandler implements ExpressionHandler<BetweenExpression> {
+  type: 'between' = 'between';
+
+  async resolve(exp: BetweenExpression, context: ExpressionEvaluatorContext) {
+    const value = resolveOperandAsScalar(exp.between.value, context.source());
+    const min = resolveOperandAsScalar(exp.between.min, context.source());
+    const max = resolveOperandAsScalar(exp.between.max, context.source());
+
+    if (isNumber(value) && isNumber(min) && isNumber(max)) {
+      return value >= min && value <= max;
+    }
+    return false;
+  }
+}
+```
+
+**4. Register the Handler**
+
+Pass your new handler to the factory function during initialization.
+
+```typescript
+import { createExpressionEvaluator } from '@axi-engine/expressions';
+
+const myHandlers = [new BetweenExpressionHandler()];
+const evaluator = createExpressionEvaluator(myHandlers);
+
+// Now you can use it!
+const expression = {
+  between: { value: { path: 'player.level' }, min: { value: 10 }, max: { value: 20 } }
+};
+```
+
+## API Reference
+
+[**Browse the API Documentation here**](https://github.com/axijs/engine/tree/main/packages/expressions/docs/api)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,469 @@
+import { ScalarType, PathType, DataSource } from '@axi-engine/utils';
+
+/**
+ * Represents an operand that is a direct, static value.
+ */
+type ValueOperand = {
+    value: ScalarType;
+};
+/**
+ * Represents an operand that is a reference to a value,
+ * which will be resolved from the context (scope) using a path.
+ */
+type ReferenceOperand = {
+    path: PathType;
+};
+/**
+ * Represents an operand that is a mathematical calculation.
+ * The result of this calculation is used as the operand's value.
+ *
+ * @example
+ * // Represents the expression: player.hp + 10
+ * {
+ *   "arithmetic": {
+ *     "op": "+",
+ *     "left": { "path": "player.hp" },
+ *     "right": { "value": 10 }
+ *   }
+ * }
+ */
+type ArithmeticOperand = {
+    arithmetic: {
+        op: MathOperationType;
+        left: Operand;
+        right: Operand;
+    };
+};
+/**
+ * Represents an operand within a logical expression.
+ * It can be either a direct value (ValueOperand) or a reference to one (ReferenceOperand).
+ */
+type Operand = ValueOperand | ReferenceOperand | ArithmeticOperand;
+/**
+ * Defines the set of allowed operators for a `ComparisonExpression`.
+ */
+type ComparisonOperationType = '<' | '>' | '<=' | '>=' | '==' | '!=';
+/**
+ * Defines the set of allowed operators for an `ArithmeticOperand`.
+ */
+type MathOperationType = '+' | '-' | '*' | '/';
+
+/**
+ * Type guard that checks if a value is a `ValueOperand`.
+ * A `ValueOperand` represents a direct, literal value.
+ *
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `ValueOperand`, otherwise `false`.
+ */
+declare function isValueOperand(val: unknown): val is ValueOperand;
+/**
+ * Type guard that checks if a value is a `ReferenceOperand`.
+ * A `ReferenceOperand` represents a reference to a value via a path.
+ *
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `ReferenceOperand`, otherwise `false`.
+ */
+declare function isReferenceOperand(val: unknown): val is ReferenceOperand;
+/**
+ * Type guard that checks if a value is an `ArithmeticOperand`.
+ * An `ArithmeticOperand` represents a mathematical calculation.
+ *
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is an `ArithmeticOperand`, otherwise `false`.
+ */
+declare function isArithmeticOperand(val: unknown): val is ArithmeticOperand;
+/**
+ * Type guard that checks if a value is any valid `Operand` type.
+ *
+ * @param val The value to check.
+ * @returns {boolean} `true` if the value is a `ValueOperand`, `ReferenceOperand`,
+ * or `ArithmeticOperand`, otherwise `false`.
+ */
+declare function isOperand(val: unknown): val is Operand;
+
+/**
+ * Represents an expression that resolves to a hardcoded boolean value.
+ * This is primarily useful for debugging, testing, or creating temporary stubs
+ * in a larger expression tree.
+ * @example
+ * { "literal": true }
+ */
+interface LiteralExpression {
+    literal: boolean;
+}
+/**
+ * Represents a comparison between two operands.
+ * It evaluates the left and right operands and compares them using the specified operator.
+ * @example
+ * {
+ *   "comparison": {
+ *     "op": ">=",
+ *     "left": { "path": "player.level" },
+ *     "right": { "value": 10 }
+ *   }
+ * }
+ */
+interface ComparisonExpression {
+    comparison: {
+        op: ComparisonOperationType;
+        left: Operand;
+        right: Operand;
+    };
+}
+/**
+ * Represents an expression that checks for the existence of a variable at a given path.
+ */
+interface ExistsExpression {
+    exists: PathType;
+}
+/**
+ * Represents a logical AND operation.
+ * It evaluates an array of child expressions and resolves to `true` only if
+ * *all* of them resolve to `true`.
+ * @example
+ * {
+ *   "and": [
+ *     { "exists": "player.key" },
+ *     { "comparison": { "op": "==", "left": { "path": "gate.locked" }, "right": { "value": true } } }
+ *   ]
+ * }
+ */
+interface AndExpression {
+    and: Expression[];
+}
+/**
+ * Represents a logical OR operation.
+ * It evaluates an array of child expressions and resolves to `true` if
+ * *at least one* of them resolves to `true`.
+ * @example
+ * {
+ *   "or": [
+ *     { "exists": "player.key" },
+ *     { "exists": "player.gun" }
+ *   ]
+ * }
+ */
+interface OrExpression {
+    or: Expression[];
+}
+/**
+ * Represents a logical NOT operation.
+ * It evaluates a single child expression and inverts its boolean result.
+ * @example
+ * {
+ *   "not": { "exists": "player.effects.poison" }
+ * }
+ */
+interface NotExpression {
+    not: Expression;
+}
+/**
+ * Represents a probabilistic expression that resolves to `true` or `false`
+ * based on a given chance.
+ * The operand should resolve to a number between 0 and 100. step 0.01
+ * @example
+ * // 15% chance to be true
+ * { "chance": { "value": 15 } }
+ * @example
+ * // Chance is determined by the player's luck stat
+ * { "chance": { "path": "player.stats.luck" } }
+ */
+interface ChanceExpression {
+    chance: Operand;
+}
+/**
+ * Represents an expression that checks if a value is present within an array.
+ * This is useful for checking against a list of possible values, such as statuses,
+ * factions, or item types.
+ * @example
+ * // Check if player's faction is one of the "evil" ones
+ * {
+ *   "in": {
+ *     "value": { "path": "player.faction" },
+ *     "array": [ "orcs", "goblins", "undead" ]
+ *   }
+ * }
+ * @example
+ * // Check against a dynamic array from the data source
+ * {
+ *   "in": {
+ *     "value": { "path": "player.class" },
+ *     "array": { "path": "quest.valid_classes" }
+ *   }
+ * }
+ */
+interface InExpression {
+    in: {
+        /**
+         * The operand whose resolved value will be searched for in the array.
+         * should be scalar type (string, number, boolean)
+         */
+        value: Operand;
+        /**
+         * The collection to check against. This can be either:
+         * - An operand that resolves to an array.
+         * - A literal array defined directly in the expression.
+         */
+        array: Operand | (Operand | ScalarType)[];
+    };
+}
+/**
+ * A map defining all available expression types by their unique key.
+ * This interface is designed to be augmented by third-party plugins
+ * using TypeScript's declaration merging.
+ */
+interface ExpressionDefinitions {
+    literal: LiteralExpression;
+    comparison: ComparisonExpression;
+    exists: ExistsExpression;
+    and: AndExpression;
+    or: OrExpression;
+    not: NotExpression;
+    chance: ChanceExpression;
+    in: InExpression;
+}
+/** The union of all possible expression objects. */
+type Expression = ExpressionDefinitions[keyof ExpressionDefinitions];
+/** The union of all possible expression names (keys). uses in ExpressionHandler */
+type ExpressionName = keyof ExpressionDefinitions;
+
+/**
+ * Recursively resolves an Operand into its final scalar value.
+ *
+ * This function processes different types of operands:
+ * - `ValueOperand`: Returns the direct value.
+ * - `ReferenceOperand`: Looks up the value from the provided data source using its path.
+ * - `ArithmeticOperand`: Recursively resolves its left and right sides and then performs the calculation.
+ *
+ * @param op The `Operand` object to resolve. This can be a direct value, a path reference, or a nested arithmetic operation.
+ * @param source The `DataSource` used to look up values for `ReferenceOperand` types.
+ * @returns unknown.
+ * @throws {Error} If a `ReferenceOperand` points to a path that does not resolve to a scalar value.
+ * @throws {Error} If an `ArithmeticOperand` is used with non-numeric values.
+ * @throws {Error} If an unknown or unsupported operand type is provided.
+ */
+declare function resolveOperand(op: Operand, source: DataSource): unknown;
+/**
+ * Resolves an operand and asserts that the result is a `ScalarType`.
+ *
+ * This function acts as a type-safe convenience wrapper around the more generic
+ * `resolveOperand` function. It is the preferred way to resolve operands within
+ * expression handlers that are designed to work only with scalar values
+ * (string, number, or boolean), as it centralizes type checking.
+ *
+ * @param op The `Operand` object to resolve.
+ * @param source The `DataSource` used to look up values for reference operands.
+ * @returns The resolved scalar value.
+ * @throws {Error} If the resolved value from the operand is not a `ScalarType`
+ * (e.g., it's an object, array, or undefined).
+ */
+declare function resolveOperandAsScalar(op: Operand, source: DataSource): ScalarType;
+
+/**
+ * Provides the execution context for an `ExpressionHandler`, giving it the tools
+ * needed to perform its evaluation. An instance of this context is passed to
+ * every handler's `resolve` method.
+ * @interface
+ */
+interface ExpressionEvaluatorContext {
+    /**
+     * A function to recursively resolve nested or child expressions.
+     * This is used by logical handlers like `AndExpressionHandler` or `NotExpressionHandler`
+     * to evaluate their child expressions using the main evaluator logic.
+     * @param expression The nested expression to resolve.
+     * @returns A promise that resolves to the boolean result of the nested expression.
+     */
+    resolve(expression: Expression): Promise<boolean>;
+    /**
+     * A function that returns the `DataSource` for the current evaluation.
+     * This allows the handler to retrieve values needed for `ReferenceOperand`s.
+     * @returns The active `DataSource`.
+     */
+    source(): DataSource;
+}
+/**
+ * The class responsible for evaluating expression trees.
+ *
+ * It acts as an orchestrator that manages a registry of `ExpressionHandler`
+ * instances and delegates the evaluation of a specific expression to the
+ * appropriate handler.
+ *
+ * Users typically do not create this class directly but use the
+ * `createExpressionEvaluator` factory function, which provides a pre-configured
+ * instance with all core handlers.
+ *
+ * @class
+ */
+declare class ExpressionEvaluator {
+    /** @internal A map of registered expression handlers. */
+    handlers: Map<keyof ExpressionDefinitions, ExpressionHandler<Expression>>;
+    /**
+     * 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: ExpressionHandler): void;
+    /**
+     * 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.
+     */
+    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>;
+}
+
+/**
+ * An expression handler for the `chance` expression.
+ *
+ * This handler evaluates to `true` or `false` based on a probabilistic check.
+ * It resolves its operand to a numeric percentage value and compares it against
+ * a random number roll.
+ */
+declare class ChanceExpressionHandler implements ExpressionHandler<ChanceExpression> {
+    type: ExpressionName;
+    /**
+     * 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).
+     */
+    resolve(exp: ChanceExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+declare class ComparisonExpressionHandler implements ExpressionHandler<ComparisonExpression> {
+    type: ExpressionName;
+    resolve(exp: ComparisonExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+declare class ExistsExpressionHandler implements ExpressionHandler<ExistsExpression> {
+    type: ExpressionName;
+    resolve(exp: ExistsExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+/**
+ * An expression handler for the `in` expression.
+ *
+ * This handler checks if a resolved scalar value is present within a collection (array).
+ * It supports both literal arrays defined directly in the expression and arrays
+ * resolved from a data source via an operand.
+ */
+declare class InExpressionHandler implements ExpressionHandler<InExpression> {
+    type: ExpressionName;
+    /**
+     * 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.
+     */
+    resolve(exp: InExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+declare class LiteralExpressionHandler implements ExpressionHandler<LiteralExpression> {
+    type: ExpressionName;
+    resolve(exp: LiteralExpression, _context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+declare class NotExpressionHandler implements ExpressionHandler<NotExpression> {
+    type: ExpressionName;
+    resolve(exp: NotExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+declare class OrExpressionHandler implements ExpressionHandler<OrExpression> {
+    type: ExpressionName;
+    resolve(exp: OrExpression, context: ExpressionEvaluatorContext): Promise<boolean>;
+}
+
+/**
+ * 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);
+ */
+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 };