@briza/illogical 2.0.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@briza/illogical",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.",
   "type": "module",
   "main": "./lib/illogical.cjs",
@@ -32,10 +32,29 @@
     "lint:fix": "eslint --max-warnings 0 \"src/**/*.{ts,js}\" --fix",
     "prepublishOnly": "npm run test && npm run build",
     "check-licenses": "license-checker --summary --excludePrivatePackages --onlyAllow \"MIT;MIT OR X11;Apache-2.0;ISC;BSD-3-Clause;BSD-2-Clause;CC-BY-4.0;Public Domain;BSD;CC-BY-3.0;CC0-1.0;Python-2.0;BlueOak-1.0.0;Unlicense\"",
-    "bench:sample:oop:evaluate":    "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions    --out benchmark/results-sample-evaluate-oop.json",
-    "bench:sample:oop:simplify":    "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions    --out benchmark/results-sample-simplify-oop.json",
+    "bench": "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions    --out benchmark/results-sample-evaluate-oop.json && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions    --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-sample-evaluate-bytecode.json && node --import tsx src/benchmark/evaluate.ts --cases conditions/synthetic-conditions --out benchmark/results-synthetic-evaluate-oop.json && node --import tsx src/benchmark/evaluate.ts --cases conditions/synthetic-conditions --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-synthetic-evaluate-bytecode.json && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions    --out benchmark/results-sample-simplify-oop.json && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions    --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-sample-simplify-bytecode.json && node --import tsx src/benchmark/simplify.ts --cases conditions/synthetic-conditions --out benchmark/results-synthetic-simplify-oop.json && node --import tsx src/benchmark/simplify.ts --cases conditions/synthetic-conditions --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-synthetic-simplify-bytecode.json && node --import tsx src/benchmark/report.ts benchmark/results-sample-evaluate-oop.json    benchmark/results-sample-evaluate-bytecode.json    --op evaluate --out benchmark/report-sample-evaluate.md && node --import tsx src/benchmark/report.ts benchmark/results-synthetic-evaluate-oop.json benchmark/results-synthetic-evaluate-bytecode.json --op evaluate --out benchmark/report-synthetic-evaluate.md && node --import tsx src/benchmark/report.ts benchmark/results-sample-simplify-oop.json    benchmark/results-sample-simplify-bytecode.json    --op simplify --out benchmark/report-sample-simplify.md && node --import tsx src/benchmark/report.ts benchmark/results-synthetic-simplify-oop.json benchmark/results-synthetic-simplify-bytecode.json --op simplify --out benchmark/report-synthetic-simplify.md",
+    "bench:sample:oop:evaluate": "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions    --out benchmark/results-sample-evaluate-oop.json",
+    "bench:sample:oop:simplify": "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions    --out benchmark/results-sample-simplify-oop.json",
     "bench:synthetic:oop:evaluate": "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/synthetic-conditions --out benchmark/results-synthetic-evaluate-oop.json",
-    "bench:synthetic:oop:simplify": "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/synthetic-conditions --out benchmark/results-synthetic-simplify-oop.json"
+    "bench:synthetic:oop:simplify": "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/synthetic-conditions --out benchmark/results-synthetic-simplify-oop.json",
+    "bench:sample:bytecode:evaluate": "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions    --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-sample-evaluate-bytecode.json",
+    "bench:sample:bytecode:simplify": "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions    --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-sample-simplify-bytecode.json",
+    "bench:synthetic:bytecode:evaluate": "npm run build && node --import tsx src/benchmark/evaluate.ts --cases conditions/synthetic-conditions --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-synthetic-evaluate-bytecode.json",
+    "bench:synthetic:bytecode:simplify": "npm run build && node --import tsx src/benchmark/simplify.ts --cases conditions/synthetic-conditions --options '{\"evaluator\":\"bytecode\"}' --out benchmark/results-synthetic-simplify-bytecode.json",
+    "bench:sample:compare:evaluate": "node --import tsx src/benchmark/compare.ts benchmark/results-sample-evaluate-oop.json    benchmark/results-sample-evaluate-bytecode.json",
+    "bench:synthetic:compare:evaluate": "node --import tsx src/benchmark/compare.ts benchmark/results-synthetic-evaluate-oop.json benchmark/results-synthetic-evaluate-bytecode.json",
+    "bench:sample:compare:simplify": "node --import tsx src/benchmark/compare.ts benchmark/results-sample-simplify-oop.json    benchmark/results-sample-simplify-bytecode.json",
+    "bench:synthetic:compare:simplify": "node --import tsx src/benchmark/compare.ts benchmark/results-synthetic-simplify-oop.json benchmark/results-synthetic-simplify-bytecode.json",
+    "bench:sample:report:evaluate": "node --import tsx src/benchmark/report.ts benchmark/results-sample-evaluate-oop.json    benchmark/results-sample-evaluate-bytecode.json    --op evaluate --out benchmark/report-sample-evaluate.md",
+    "bench:synthetic:report:evaluate": "node --import tsx src/benchmark/report.ts benchmark/results-synthetic-evaluate-oop.json benchmark/results-synthetic-evaluate-bytecode.json --op evaluate --out benchmark/report-synthetic-evaluate.md",
+    "bench:sample:report:full:evaluate": "node --import tsx src/benchmark/report.ts benchmark/results-sample-evaluate-oop.json    benchmark/results-sample-evaluate-bytecode.json    --op evaluate --full --out benchmark/report-sample-evaluate-full.md",
+    "bench:synthetic:report:full:evaluate": "node --import tsx src/benchmark/report.ts benchmark/results-synthetic-evaluate-oop.json benchmark/results-synthetic-evaluate-bytecode.json --op evaluate --full --out benchmark/report-synthetic-evaluate-full.md",
+    "bench:sample:report:simplify": "node --import tsx src/benchmark/report.ts benchmark/results-sample-simplify-oop.json    benchmark/results-sample-simplify-bytecode.json    --op simplify --out benchmark/report-sample-simplify.md",
+    "bench:synthetic:report:simplify": "node --import tsx src/benchmark/report.ts benchmark/results-synthetic-simplify-oop.json benchmark/results-synthetic-simplify-bytecode.json --op simplify --out benchmark/report-synthetic-simplify.md",
+    "bench:sample:report:full:simplify": "node --import tsx src/benchmark/report.ts benchmark/results-sample-simplify-oop.json    benchmark/results-sample-simplify-bytecode.json    --op simplify --full --out benchmark/report-sample-simplify-full.md",
+    "bench:synthetic:report:full:simplify": "node --import tsx src/benchmark/report.ts benchmark/results-synthetic-simplify-oop.json benchmark/results-synthetic-simplify-bytecode.json --op simplify --full --out benchmark/report-synthetic-simplify-full.md",
+    "get-bytecode": "node --import tsx src/bytecode/get-bytecode.ts",
+    "debug-bytecode": "node --import tsx src/tools/debugger.ts"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -87,6 +87,11 @@ Customize the engine and the documentation:
 - [Engine Options](./specs/engine.md)
 - [Code Documentation](https://briza-insurance.github.io/illogical/index.html)
 
+Bytecode evaluation and debugging tools:
+
+- [Bytecode Evaluator](./specs/bytecode-evaluator.md)
+- [Debugger Tools](./specs/debugger-tools.md)
+
 ## 📖 Changelog
 
 See [changelog.md](./changelog.md).

package/types/bytecode/compiler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Bytecode compiler.
+ *
+ * Transforms a raw ExpressionInput (plain array) into a flat Bytecode array
+ * that the interpreter can execute. This runs once per unique expression;
+ * the result should be cached and reused across evaluate() calls.
+ */
+import { Result } from '../common/evaluable.js';
+import { ArrayInput, ExpressionInput, Input } from '../parser/index.js';
+import { Options } from '../parser/options.js';
+import { CompactRef } from './refs.js';
+export type Bytecode = (number | Result)[];
+export interface CompiledExpression {
+    bytecode: Bytecode;
+    refs: CompactRef[];
+    numLocals: number;
+    consts: ArrayInput[];
+    opNames: Record<number, string>;
+    refKeys: string[];
+    refRawKeys: string[];
+    overlapRefsResiduals: Array<[number, Input[]]>;
+    directionMap: Array<[number, 0 | 1]>;
+    refFirstCtxKeys: (string | undefined)[];
+}
+/**
+ * Compile a raw ExpressionInput into bytecode.
+ * The result should be cached and reused across evaluate() calls.
+ */
+export declare function compile(raw: ExpressionInput, opts: Options): CompiledExpression;

package/types/bytecode/evaluable.d.ts

@@ -0,0 +1,14 @@
+import { Context, Evaluable, EvaluableType, Result } from '../common/evaluable.js';
+import { Input } from '../parser/index.js';
+import { Options } from '../parser/options.js';
+import { CompiledExpression } from './compiler.js';
+export declare class BytecodeEvaluable implements Evaluable {
+    private readonly compiled;
+    private readonly delegate;
+    readonly type = EvaluableType.Expression;
+    constructor(compiled: CompiledExpression, delegate: Evaluable);
+    evaluate(ctx: Context): Result;
+    simplify(ctx: Context, strictKeys?: string[] | Set<string>, optionalKeys?: string[] | Set<string>): Result | Input;
+    serialize(options: Options): Input;
+    toString(): string;
+}

package/types/bytecode/get-bytecode.d.ts

@@ -0,0 +1 @@
+export {};

package/types/bytecode/interpreter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bytecode interpreter.
+ *
+ * Executes a compiled bytecode array against a context object.
+ * Zero allocations in the hot path: uses a pre-allocated stack
+ * and operates on the flat bytecode array directly.
+ */
+import { Context, Result } from '../common/evaluable.js';
+import { CompiledExpression } from './compiler.js';
+export declare function interpret(compiled: CompiledExpression, ctx: Context): Result;

package/types/bytecode/opcodes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bytecode opcodes for the illogical expression interpreter.
+ *
+ * Each opcode is a small integer. Some opcodes consume the next element(s)
+ * in the bytecode array as operand data (e.g. OP_PUSH_VALUE reads the next
+ * element as the literal value to push).
+ */
+export declare const OP_PUSH_VALUE = 1;
+export declare const OP_PUSH_REF = 2;
+export declare const OP_PUSH_REF_KEY = 6;
+export declare const OP_PUSH_REF_KEYS = 7;
+export declare const OP_PUSH_REF_TOKENS = 8;
+export declare const OP_PUSH_REF_DYNAMIC = 9;
+export declare const OP_MAKE_COLLECTION = 3;
+export declare const OP_PUSH_CONST = 4;
+export declare const OP_OVERLAP_CONST = 5;
+export declare const OP_EQ = 10;
+export declare const OP_NE = 11;
+export declare const OP_GT = 12;
+export declare const OP_GE = 13;
+export declare const OP_LT = 14;
+export declare const OP_LE = 15;
+export declare const OP_IN = 16;
+export declare const OP_NOT_IN = 17;
+export declare const OP_IN_COLLECTION = 45;
+export declare const OP_NOT_IN_COLLECTION = 46;
+export declare const OP_IN_CONST = 49;
+export declare const OP_NOT_IN_CONST = 50;
+export declare const OP_OVERLAP_SCAN_REFS_CONST = 51;
+export declare const OP_OR_AND_IN_CONST_2 = 52;
+export declare const OP_PREFIX = 18;
+export declare const OP_SUFFIX = 19;
+export declare const OP_OVERLAP = 20;
+export declare const OP_PRESENT = 21;
+export declare const OP_UNDEFINED = 22;
+export declare const OP_SUM = 30;
+export declare const OP_SUBTRACT = 31;
+export declare const OP_MULTIPLY = 32;
+export declare const OP_DIVIDE = 33;
+export declare const OP_STORE_LOCAL = 47;
+export declare const OP_LOAD_LOCAL = 48;
+export declare const OP_NOT = 40;
+export declare const OP_JUMP_IF_FALSE = 41;
+export declare const OP_JUMP_IF_TRUE = 42;
+export declare const OP_POP = 43;
+export declare const OP_XOR = 44;
+export declare const OP_AND = 53;
+export declare const OP_OR = 54;
+export declare const OP_NOR = 55;
+export declare const OP_IN_SCAN_REFS_CONST = 56;
+export declare const OP_NOT_IN_SCAN_REFS_CONST = 57;

package/types/bytecode/operateWithExpectedDecimals.d.ts

@@ -0,0 +1 @@
+export declare const operateWithExpectedDecimals: (operation: "sum" | "subtract" | "multiply") => (first: number, second: number) => number;

package/types/bytecode/refs.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reference path descriptors for the bytecode compiler and interpreter.
+ *
+ * CompactRef is the single runtime type stored in CompiledExpression.refs.
+ * The compiler picks the right opcode per ref kind so the interpreter
+ * dispatches to a dedicated handler with no secondary branching.
+ *
+ *   string          — OP_PUSH_REF_KEY    — ctx[key]
+ *   string[]        — OP_PUSH_REF_KEYS   — inline multi-key walk
+ *   CompactRefFull (tokens)  — OP_PUSH_REF_TOKENS  — token walk + optional cast
+ *   CompactRefFull (dynamic) — OP_PUSH_REF_DYNAMIC — runtime {placeholder} substitution
+ */
+import { Context, Result } from '../common/evaluable.js';
+import { DataType } from '../operand/reference.js';
+export type PathToken = {
+    kind: 'key';
+    value: string;
+} | {
+    kind: 'index';
+    value: number;
+};
+/** Full compact form for refs that don't fit the short string/string[] forms. */
+export interface CompactRefFull {
+    /** Raw key string for dynamic refs with {placeholder} substitution. */
+    k?: string;
+    /** True for dynamic refs. */
+    d?: true;
+    /** DataType cast, e.g. DataType.Number. */
+    t?: DataType;
+    /** Token list for paths containing array indexes or deep static paths. */
+    tokens?: PathToken[];
+}
+/**
+ * Runtime ref representation stored in CompiledExpression.refs:
+ *   - `string`         → single plain-key (most common)
+ *   - `string[]`       → multi-key inline path
+ *   - `CompactRefFull` → token-based or dynamic
+ */
+export type CompactRef = string | string[] | CompactRefFull;
+/**
+ * Build a CompactRef from a raw reference key string (without the $ prefix).
+ * Called once at compile time; the result is stored in CompiledExpression.refs.
+ */
+export declare function buildCompactRef(rawKey: string): CompactRef;
+/** Type-safe property access on an object narrowed from `unknown`. */
+export declare function propAt(obj: object, key: string): Result;
+/** Narrow a CompactRef to its string form (OP_PUSH_REF_KEY). Throws on mismatch. */
+export declare function asKeyRef(ref: CompactRef): string;
+/** Narrow a CompactRef to its string[] form (OP_PUSH_REF_KEYS). Throws on mismatch. */
+export declare function asKeysRef(ref: CompactRef): string[];
+/** Narrow a CompactRef to CompactRefFull (OP_PUSH_REF_TOKENS / OP_PUSH_REF_DYNAMIC). Throws on mismatch. */
+export declare function asFullRef(ref: CompactRef): CompactRefFull;
+/**
+ * Resolve a multi-key inline path (string[]) against a context.
+ * Used by OP_PUSH_REF_KEYS and OP_PUSH_REF_DYNAMIC (after substitution).
+ */
+export declare function resolveKeys(ks: string[], ctx: Context): Result;
+/**
+ * Resolve a token-based path against a context.
+ * Used by OP_PUSH_REF_TOKENS.
+ */
+export declare function resolveTokens(tokens: PathToken[], dataType: DataType | undefined, ctx: Context): Result;
+/**
+ * Resolve a dynamic ref (with {placeholder} substitution) against a context.
+ * Used by OP_PUSH_REF_DYNAMIC.
+ */
+export declare function resolveDynamic(key: string, dataType: DataType | undefined, ctx: Context): Result;
+/**
+ * Resolve any CompactRef against a context.
+ * Used in ops that embed ref indices but weren't split by kind
+ * (OP_OVERLAP_SCAN_REFS_CONST, OP_OR_AND_IN_CONST_2).
+ */
+export declare function resolveCompactRef(ref: CompactRef, ctx: Context): Result;

package/types/bytecode/simplifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Bytecode simplify interpreter.
+ *
+ * Runs the same bytecode as the evaluate interpreter but supports partial
+ * evaluation. Stack slots hold either a Result (fully resolved) or an Input
+ * fragment (residual — a ref string or a sub-expression array). When an
+ * operator receives any residual operand it reconstructs the sub-expression
+ * as an Input array instead of computing a value.
+ *
+ * Short-circuit logic still applies: AND with a false short-circuits even if
+ * other operands are unknown; OR with a true short-circuits likewise.
+ */
+import { Context } from '../common/evaluable.js';
+import { Input } from '../parser/index.js';
+import { CompiledExpression } from './compiler.js';
+export declare function interpretSimplify(compiled: CompiledExpression, ctx: Context, strictKeys?: string[] | Set<string>, optionalKeys?: string[] | Set<string>): Input;

package/types/common/type-check.d.ts

@@ -1,9 +1,12 @@
+import { Operand } from '../operand/index.js';
+import { Reference } from '../operand/reference.js';
+import { Value } from '../operand/value.js';
 import { Evaluable, Result } from './evaluable.js';
 /**
  * Is number predicate.
  * @param value Tested value.
  */
-export declare function isNumber(value: Result): value is number;
+export declare function isNumber(value: unknown): value is number;
 /**
  * Is number predicate.
  * @param value Tested value.
@@ -13,7 +16,7 @@ export declare function isInfinite(value: Result): value is typeof Infinity;
  * Is string type predicate.
  * @param value Tested value.
  */
-export declare function isString(value: Result): value is string;
+export declare function isString(value: unknown): value is string;
 /**
  * Is Object
  * @param value tested value result of the test
@@ -45,3 +48,5 @@ export declare function areAllResults(values: (Result | Evaluable)[]): values is
 export declare function areAllNumbers(results: Result[]): results is number[];
 export declare function isUndefined(value: unknown): value is undefined;
 export declare function isNull(value: unknown): value is null;
+export declare function isReference(operand: Operand): operand is Reference;
+export declare function isValue(operand: Operand): operand is Value;

package/types/common/util.d.ts

@@ -14,3 +14,9 @@ export declare const toString: (value: Result) => string | undefined;
  * @param value value to be converted to number
  */
 export declare const toDateNumber: (value: Result) => number;
+export declare const formatDateNumber: (dateNumber: number) => string;
+export type DateDuration = {
+    amount: number;
+    unit: 'd' | 'm' | 'y';
+};
+export declare const toDateDuration: (value: Result) => DateDuration | undefined;

package/types/expression/arithmetic/dateArithmeticTypeCheck.d.ts

@@ -0,0 +1,2 @@
+import { Operand } from '../../operand/index.js';
+export declare const dateArithmeticTypeCheck: (...operands: Operand[]) => void;

package/types/expression/arithmetic/index.d.ts

@@ -1,4 +1,5 @@
 import { Context, Evaluable, EvaluableType, Result, SimplifyArgs } from '../../common/evaluable.js';
+import { DateDuration } from '../../common/util.js';
 import { Operand } from '../../operand/index.js';
 import { ExpressionInput } from '../../parser/index.js';
 import { Options } from '../../parser/options.js';
@@ -27,6 +28,7 @@ export declare abstract class Arithmetic implements Evaluable {
      *   array of numbers
      */
     protected getResultValues(results: Result[]): number[] | false;
+    protected getDateCalculationResults(results: Result[]): [number, ...DateDuration[]] | false;
     /**
      * Performs the arithmetic operation on the operands evaluated values.
      * @param {Result[]} results Operand result values.

package/types/expression/arithmetic/mutateDateWithDuration.d.ts

@@ -0,0 +1,2 @@
+import { DateDuration } from '../../common/util.js';
+export declare const mutateDateWithDuration: (dateNumber: number, duration: DateDuration, operator: "sum" | "subtract") => number;

package/types/index.d.ts

@@ -29,18 +29,22 @@ import { OPERATOR as OPERATOR_XOR } from './expression/logical/xor.js';
 import { ExpressionInput, Input } from './parser/index.js';
 import { Options } from './parser/options.js';
 export { defaultOptions } from './parser/options.js';
+export type { EvaluatorMode } from './parser/options.js';
 export { isEvaluable, OPERATOR_EQ, OPERATOR_NE, OPERATOR_GT, OPERATOR_GE, OPERATOR_LT, OPERATOR_LE, OPERATOR_IN, OPERATOR_NOT_IN, OPERATOR_PREFIX, OPERATOR_SUFFIX, OPERATOR_OVERLAP, OPERATOR_UNDEFINED, OPERATOR_PRESENT, OPERATOR_AND, OPERATOR_OR, OPERATOR_NOR, OPERATOR_XOR, OPERATOR_NOT, OPERATOR_DIVIDE, OPERATOR_MULTIPLY, OPERATOR_SUBTRACT, OPERATOR_SUM, };
-export type { Context, Evaluable, ExpressionInput };
+export type { Context, Evaluable, ExpressionInput, Input };
 /**
  * Condition engine
  */
 declare class Engine {
     private readonly parser;
+    private readonly evaluator;
+    private readonly bytecodeCache;
     /**
      * @constructor
      * @param {Options?} options Parser options.
      */
     constructor(options?: Partial<Options>);
+    private getCompiled;
     /**
      * Evaluate the expression.
      * @param {ExpressionInput} exp Raw expression.

package/types/parser/options.d.ts

@@ -1,4 +1,10 @@
 export type optionValue = ((operand: string) => string | boolean) | Map<symbol, string>;
+/**
+ * Engine evaluator mode.
+ * - `'oop'` (default): evaluates expressions using the classic OOP evaluable tree.
+ * - `'bytecode'`: compiles expressions to bytecode and interprets them.
+ */
+export type EvaluatorMode = 'oop' | 'bytecode';
 export interface Options {
     /**
      * A function used to determine if the operand is a reference type,
@@ -35,7 +41,11 @@ export interface Options {
      * is the key used to represent the  given operator in the raw expression.
      */
     operatorMapping: Map<symbol, string>;
-    [k: string]: optionValue;
+    /**
+     * Evaluator mode used by the engine.
+     * Defaults to `'oop'` when not specified.
+     */
+    evaluator?: EvaluatorMode;
 }
 /**
  * Default reference predicate.
@@ -45,7 +55,7 @@ export interface Options {
  * @param {string} key
  * @return {boolean}
  */
-export declare function defaultReferencePredicate(key: string): boolean;
+export declare function defaultReferencePredicate(key: unknown): boolean;
 /**
  * Default reference transform.
  * It removes the "$" symbol at the begging of the operand name.