@briza/illogical 2.2.3 → 2.2.4

package/lib/illogical.cjs

@@ -1304,7 +1304,7 @@ class Present extends Comparison {
 }
 
 // Operator key
-const OPERATOR$6 = Symbol('PREFIX');
+const OPERATOR$6 = Symbol('SUFFIX');
 
 /**
  * Suffix comparison expression
@@ -2498,7 +2498,9 @@ function emitExpression(raw, state) {
     return;
   }
   if (operator === maps.orOp) {
-    const orAnd2 = detectOrAndIn2Pattern(arr, state);
+    // Skip the merge when compiling for simplify so the nested structure can
+    // be reconstructed verbatim (the merge collapses branches by ref1 value).
+    const orAnd2 = state.simplify ? null : detectOrAndIn2Pattern(arr, state);
     if (orAnd2 !== null) {
       const {
         ref1Raw,
@@ -2775,7 +2777,7 @@ function emitExpression(raw, state) {
  * Compile a raw ExpressionInput into bytecode.
  * The result should be cached and reused across evaluate() calls.
  */
-function compile(raw, opts) {
+function compile(raw, opts, simplify = false) {
   const maps = buildOperatorMaps(opts);
   const state = {
     bytecode: [],
@@ -2790,7 +2792,8 @@ function compile(raw, opts) {
     consts: [],
     constIndex: new Map(),
     overlapRefsEntries: [],
-    directionEntries: []
+    directionEntries: [],
+    simplify
   };
   emitExpression(raw, state);
 
@@ -3250,7 +3253,8 @@ function interpret(compiled, ctx) {
         }
       case OP_OR_AND_IN_CONST_2:
         {
-          // bytecode layout: ref1Idx, ref2Idx, M, (v0, setBIdx0, ref1Op0, ref2Op0), (v1, setBIdx1, ref1Op1, ref2Op1), ...
+          // bytecode layout: ref1Idx, ref2Idx, M,
+          //   (aVal0, setBIdx0, ref1Op0, ref2Op0), (aVal1, setBIdx1, ref1Op1, ref2Op1), ...
           // ref1Op/ref2Op: 0 for 'eq', 1 for 'in' (unused at runtime, kept for simplifier)
           // constSets[setBIdx] is pre-built at first interpret() call — plain Set.has lookup.
           const ref1Idx = numAt$1(bytecode[++i]);
@@ -3369,8 +3373,14 @@ function interpret(compiled, ctx) {
             break;
           }
           const values = new Array(n);
+          // Fixed destination slot for the single result value: the bottom-most
+          // operand slot. The operands occupy [stackTop - n + 1 .. stackTop].
+          // Writing here (instead of to stack[++stackTop]) keeps the result in a
+          // stable slot even when the loop below breaks early on a missing
+          // operand, so the next opcode never reads a stale operand value.
+          const resultSlot = stackTop$1 - n + 1;
           let hasNull = false;
-          const isDateArithmetic = !isNaN(toDateNumber(stack$1[stackTop$1 - n + 1])) && (op === OP_SUM || op === OP_SUBTRACT);
+          const isDateArithmetic = !isNaN(toDateNumber(stack$1[resultSlot])) && (op === OP_SUM || op === OP_SUBTRACT);
           for (let j = n - 1; j >= 0; j--) {
             const v = stack$1[stackTop$1--];
             if (v === null || v === undefined) {
@@ -3391,7 +3401,9 @@ function interpret(compiled, ctx) {
               values[j] = v;
             }
           }
-          stack$1[++stackTop$1] = hasNull ? false : isDateArithmetic && (op === OP_SUM || op === OP_SUBTRACT) && values.every(v => isString(v)) ? dateArithmeticReduce$1(values, op) : values.every(v => isNumber(v)) ? arithmeticReduce$1(values, op) : false;
+          const result = hasNull ? false : isDateArithmetic && (op === OP_SUM || op === OP_SUBTRACT) && values.every(v => isString(v)) ? dateArithmeticReduce$1(values, op) : values.every(v => isNumber(v)) ? arithmeticReduce$1(values, op) : false;
+          stack$1[resultSlot] = result;
+          stackTop$1 = resultSlot;
           break;
         }
 
@@ -5245,6 +5257,11 @@ class Engine {
     _defineProperty(this, "parser", void 0);
     _defineProperty(this, "evaluator", void 0);
     _defineProperty(this, "bytecodeCache", new WeakMap());
+    // Separate cache for the simplify compiler output. Simplify must preserve the
+    // nested structure verbatim, so it compiles with the OR_AND_IN merge disabled
+    // (see `compile`'s `simplify` flag), which yields different bytecode than the
+    // evaluate path and therefore cannot share `bytecodeCache`.
+    _defineProperty(this, "simplifyCache", new WeakMap());
     this.parser = new Parser(options);
     this.evaluator = options?.evaluator ?? 'oop';
   }
@@ -5258,6 +5275,20 @@ class Engine {
     return compiled;
   }
 
+  /**
+   * Compile for simplify: preserves the original nested structure so the
+   * simplify interpreter can reproduce the input verbatim (no OR_AND_IN merge).
+   */
+  getSimplifiedCompiled(exp) {
+    let compiled = this.simplifyCache.get(exp);
+    if (compiled === undefined) {
+      this.parser.parse(exp); // validates root operator and expression structure
+      compiled = compile(exp, this.parser.options, true);
+      this.simplifyCache.set(exp, compiled);
+    }
+    return compiled;
+  }
+
   /**
    * Evaluate the expression.
    * @param {ExpressionInput} exp Raw expression.
@@ -5312,7 +5343,7 @@ class Engine {
    */
   simplify(exp, context, strictKeys, optionalKeys) {
     if (this.evaluator === 'bytecode') {
-      return interpretSimplify(this.getCompiled(exp), context, strictKeys, optionalKeys);
+      return interpretSimplify(this.getSimplifiedCompiled(exp), context, strictKeys, optionalKeys);
     }
     const result = this.parser.parse(exp).simplify(context, strictKeys, optionalKeys);
     if (isEvaluable(result)) {

package/lib/illogical.esm.js

@@ -1300,7 +1300,7 @@ class Present extends Comparison {
 }
 
 // Operator key
-const OPERATOR$6 = Symbol('PREFIX');
+const OPERATOR$6 = Symbol('SUFFIX');
 
 /**
  * Suffix comparison expression
@@ -2494,7 +2494,9 @@ function emitExpression(raw, state) {
     return;
   }
   if (operator === maps.orOp) {
-    const orAnd2 = detectOrAndIn2Pattern(arr, state);
+    // Skip the merge when compiling for simplify so the nested structure can
+    // be reconstructed verbatim (the merge collapses branches by ref1 value).
+    const orAnd2 = state.simplify ? null : detectOrAndIn2Pattern(arr, state);
     if (orAnd2 !== null) {
       const {
         ref1Raw,
@@ -2771,7 +2773,7 @@ function emitExpression(raw, state) {
  * Compile a raw ExpressionInput into bytecode.
  * The result should be cached and reused across evaluate() calls.
  */
-function compile(raw, opts) {
+function compile(raw, opts, simplify = false) {
   const maps = buildOperatorMaps(opts);
   const state = {
     bytecode: [],
@@ -2786,7 +2788,8 @@ function compile(raw, opts) {
     consts: [],
     constIndex: new Map(),
     overlapRefsEntries: [],
-    directionEntries: []
+    directionEntries: [],
+    simplify
   };
   emitExpression(raw, state);
 
@@ -3246,7 +3249,8 @@ function interpret(compiled, ctx) {
         }
       case OP_OR_AND_IN_CONST_2:
         {
-          // bytecode layout: ref1Idx, ref2Idx, M, (v0, setBIdx0, ref1Op0, ref2Op0), (v1, setBIdx1, ref1Op1, ref2Op1), ...
+          // bytecode layout: ref1Idx, ref2Idx, M,
+          //   (aVal0, setBIdx0, ref1Op0, ref2Op0), (aVal1, setBIdx1, ref1Op1, ref2Op1), ...
           // ref1Op/ref2Op: 0 for 'eq', 1 for 'in' (unused at runtime, kept for simplifier)
           // constSets[setBIdx] is pre-built at first interpret() call — plain Set.has lookup.
           const ref1Idx = numAt$1(bytecode[++i]);
@@ -3365,8 +3369,14 @@ function interpret(compiled, ctx) {
             break;
           }
           const values = new Array(n);
+          // Fixed destination slot for the single result value: the bottom-most
+          // operand slot. The operands occupy [stackTop - n + 1 .. stackTop].
+          // Writing here (instead of to stack[++stackTop]) keeps the result in a
+          // stable slot even when the loop below breaks early on a missing
+          // operand, so the next opcode never reads a stale operand value.
+          const resultSlot = stackTop$1 - n + 1;
           let hasNull = false;
-          const isDateArithmetic = !isNaN(toDateNumber(stack$1[stackTop$1 - n + 1])) && (op === OP_SUM || op === OP_SUBTRACT);
+          const isDateArithmetic = !isNaN(toDateNumber(stack$1[resultSlot])) && (op === OP_SUM || op === OP_SUBTRACT);
           for (let j = n - 1; j >= 0; j--) {
             const v = stack$1[stackTop$1--];
             if (v === null || v === undefined) {
@@ -3387,7 +3397,9 @@ function interpret(compiled, ctx) {
               values[j] = v;
             }
           }
-          stack$1[++stackTop$1] = hasNull ? false : isDateArithmetic && (op === OP_SUM || op === OP_SUBTRACT) && values.every(v => isString(v)) ? dateArithmeticReduce$1(values, op) : values.every(v => isNumber(v)) ? arithmeticReduce$1(values, op) : false;
+          const result = hasNull ? false : isDateArithmetic && (op === OP_SUM || op === OP_SUBTRACT) && values.every(v => isString(v)) ? dateArithmeticReduce$1(values, op) : values.every(v => isNumber(v)) ? arithmeticReduce$1(values, op) : false;
+          stack$1[resultSlot] = result;
+          stackTop$1 = resultSlot;
           break;
         }
 
@@ -5241,6 +5253,11 @@ class Engine {
     _defineProperty(this, "parser", void 0);
     _defineProperty(this, "evaluator", void 0);
     _defineProperty(this, "bytecodeCache", new WeakMap());
+    // Separate cache for the simplify compiler output. Simplify must preserve the
+    // nested structure verbatim, so it compiles with the OR_AND_IN merge disabled
+    // (see `compile`'s `simplify` flag), which yields different bytecode than the
+    // evaluate path and therefore cannot share `bytecodeCache`.
+    _defineProperty(this, "simplifyCache", new WeakMap());
     this.parser = new Parser(options);
     this.evaluator = options?.evaluator ?? 'oop';
   }
@@ -5254,6 +5271,20 @@ class Engine {
     return compiled;
   }
 
+  /**
+   * Compile for simplify: preserves the original nested structure so the
+   * simplify interpreter can reproduce the input verbatim (no OR_AND_IN merge).
+   */
+  getSimplifiedCompiled(exp) {
+    let compiled = this.simplifyCache.get(exp);
+    if (compiled === undefined) {
+      this.parser.parse(exp); // validates root operator and expression structure
+      compiled = compile(exp, this.parser.options, true);
+      this.simplifyCache.set(exp, compiled);
+    }
+    return compiled;
+  }
+
   /**
    * Evaluate the expression.
    * @param {ExpressionInput} exp Raw expression.
@@ -5308,7 +5339,7 @@ class Engine {
    */
   simplify(exp, context, strictKeys, optionalKeys) {
     if (this.evaluator === 'bytecode') {
-      return interpretSimplify(this.getCompiled(exp), context, strictKeys, optionalKeys);
+      return interpretSimplify(this.getSimplifiedCompiled(exp), context, strictKeys, optionalKeys);
     }
     const result = this.parser.parse(exp).simplify(context, strictKeys, optionalKeys);
     if (isEvaluable(result)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@briza/illogical",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "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",
@@ -24,10 +24,9 @@
     "build:types": "tsc --project tsconfig.build.json --emitDeclarationOnly",
     "build:js": "rollup -c",
     "build": "rm -rf lib types && npm run build:types && npm run build:js",
-    "docs": "typedoc src && git checkout docs/.nojekyll",
-    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "test": "bash -c 'node --import tsx --test \"${@:-src/__test__/unit/**/*.test.ts}\"' --",
     "test:sample-conditions": "node --import tsx --test --test-reporter=spec \"src/__test__/unit/sample-conditions.test.ts\"",
-    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"src/**/*.test.ts\"",
+    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"src/__test__/unit/**/*.test.ts\"",
     "lint": "eslint --max-warnings 0 \"src/**/*.{ts,js}\"",
     "lint:fix": "eslint --max-warnings 0 \"src/**/*.{ts,js}\" --fix",
     "prepublishOnly": "npm run test && npm run build",
@@ -53,8 +52,11 @@
     "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",
+    "bench:full:report:test-case": "sh -c 'FILTER=$(echo \"$@\" | sed -n \"s/.*--filter \\([^ ]*\\).*/\\1/p\"); if [ -z \"$FILTER\" ]; then FILTER=\"tmp\"; fi; node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions \"$@\" --out benchmark/results-simplify-${FILTER}-oop.json && node --import tsx src/benchmark/simplify.ts --cases conditions/sample-conditions \"$@\" --options '\\''{\"evaluator\":\"bytecode\"}'\\'' --out benchmark/results-simplify-${FILTER}-bytecode.json && node --import tsx src/benchmark/report.ts benchmark/results-simplify-${FILTER}-oop.json benchmark/results-simplify-${FILTER}-bytecode.json --op simplify --out benchmark/report-simplify-${FILTER}.md && echo \"\\nReport written to benchmark/report-simplify-${FILTER}.md\" && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions \"$@\" --out benchmark/results-evaluate-${FILTER}-oop.json && node --import tsx src/benchmark/evaluate.ts --cases conditions/sample-conditions \"$@\" --options '\\''{\"evaluator\":\"bytecode\"}'\\'' --out benchmark/results-evaluate-${FILTER}-bytecode.json && node --import tsx src/benchmark/report.ts benchmark/results-evaluate-${FILTER}-oop.json benchmark/results-evaluate-${FILTER}-bytecode.json --op evaluate --out benchmark/report-evaluate-${FILTER}.md && echo \"\\nReport written to benchmark/report-evaluate-${FILTER}.md\"' -- ",
     "get-bytecode": "node --import tsx src/bytecode/get-bytecode.ts",
-    "debug-bytecode": "node --import tsx src/tools/debugger.ts"
+    "debug-bytecode": "node --import tsx src/tools/debugger.ts",
+    "test:fuzz": "node --import tsx src/tools/fuzz-runner.ts",
+    "test:fuzz:deep": "FUZZ_RUNS=100000 npm run test:fuzz"
   },
   "repository": {
     "type": "git",
@@ -92,12 +94,12 @@
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-simple-import-sort": "^12.1.1",
+    "fast-check": "^4.8.0",
     "license-checker": "^25.0.1",
     "prettier": "^3.6.2",
     "rollup": "^4.52.5",
     "tinybench": "^6.0.0",
     "tsx": "^4.19.1",
-    "typedoc": "^0.28.18",
     "typescript": "^6.0.2"
   }
 }

package/readme.md

@@ -28,6 +28,8 @@
 
 Get up and running with illogical in just a few steps.
 
+Read the [Background](#background) section to quickly understand what illogical is and why it exists. 
+
 ### Installation
 
 ```sh
@@ -69,6 +71,18 @@ engine.evaluate(['AND', ['>', '$age', 20], ['==', '$name', 'peter']]) // true
 
 ## 📚 Documentation
 
+### Background
+
+**illogical** is a JSON DSL (domain-specific language) for expressing and evaluating business rules in the insurance industry.
+
+Domain-specific languages exist to streamline work in a given domain by providing the means of performing tasks in a way that is quicker to learn and implement. This lets you optimize your custom solution and tailor it for use by distinct user groups or within unique contexts.
+
+Developers of software for insurance underwriters can enable illogical quickly and easily to make the underwriter's task of writing question sets for programmatic use more efficient by eliminating the need to learn and understand the programming language(s) in use.
+
+The way it works is that underwriters use the illogical JSON DSL to express their underwriting models, specifically their question sets and business rules. Then, the JavaScript functions in illogical parse what has been written for use within an application.
+
+Another way to think about this is that illogical is used to define machine-readable business rules for underwriting models and question sets that brokers and distribution partners can easily consume. This is much more efficient than the traditional use of spreadsheets, documents, PDFs, email exchanges, and other non-machine-readable formats that then must be translated before being used. illogical speeds up the integration process, gets your rules to market faster, and does so with significantly reduced submission errors and a lower total cost of ownership.
+
 ### Core Concepts
 
 Explore the supported expressions and their usage:
@@ -90,10 +104,7 @@ Learn how to use the engine and its methods:
 
 ### Customization
 
-Customize the engine and the documentation:
-
-- [Engine Options](./specs/engine.md)
-- [Code Documentation](https://briza-insurance.github.io/illogical/index.html)
+Customize the [engine options](./specs/engine.md).
 
 ### Development Tools
 

package/types/bytecode/compiler.d.ts

@@ -10,6 +10,63 @@ import { ArrayInput, ExpressionInput, Input } from '../parser/index.js';
 import { Options } from '../parser/options.js';
 import { CompactRef } from './refs.js';
 export type Bytecode = (number | Result)[];
+interface OperatorMaps {
+    binary: Record<string, number>;
+    arithmetic: Record<string, number>;
+    presentOp: string;
+    undefinedOp: string;
+    andOp: string;
+    orOp: string;
+    norOp: string;
+    notOp: string;
+    xorOp: string;
+    inOp: string;
+    notInOp: string;
+    overlapOp: string;
+    eqOp: string;
+}
+export interface CompilerState {
+    bytecode: Bytecode;
+    refs: CompactRef[];
+    refIndex: Map<string, number>;
+    refRawKeys: string[];
+    refKeys: string[];
+    opts: Options;
+    maps: OperatorMaps;
+    collectionCse: Map<string, number>;
+    numLocals: number;
+    consts: ArrayInput[];
+    constIndex: Map<string, number>;
+    overlapRefsEntries: Array<{
+        pos: number;
+        refIdxs: number[];
+    }>;
+    directionEntries: Array<{
+        pos: number;
+        dir: 0 | 1;
+    }>;
+    simplify: boolean;
+}
+/**
+ * Check whether an OR expression matches the pattern:
+ *   OR( AND(IN-like(ref1, set1), IN-like(ref2, set2)), ... )
+ * where IN-like is either IN(ref, staticSet) or ==(ref, scalar),
+ * and every branch uses the exact same two refs in the same order.
+ *
+ * Builds an inverted index: for each unique value in any setA, union-merges all
+ * setB values across branches where that setA value appears, and emits one
+ * (literal value, mergedSetBIdx) entry per distinct setA value.
+ *
+ * This lets the interpreter do a single O(1) Map lookup on ref1 to find all
+ * relevant setB indices, instead of a linear scan through N setA Sets.
+ * Returns null if the pattern does not match.
+ */
+export declare function detectOrAndIn2Pattern(arr: ArrayInput, state: CompilerState): {
+    ref1Raw: string;
+    ref2Raw: string;
+    entries: Array<[Result, number]>;
+    entryOperators: Array<['eq' | 'in', 'eq' | 'in']>;
+} | null;
 export interface CompiledExpression {
     bytecode: Bytecode;
     refs: CompactRef[];
@@ -26,4 +83,5 @@ export interface CompiledExpression {
  * 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;
+export declare function compile(raw: ExpressionInput, opts: Options, simplify?: boolean): CompiledExpression;
+export {};

package/types/common/evaluable.d.ts

@@ -3,7 +3,7 @@ import { Options } from '../parser/options.js';
 /**
  * Valid types for context members
  */
-type ContextValue = Record<string, unknown> | string | number | boolean | null | undefined | ContextValue[];
+export type ContextValue = Record<string, unknown> | string | number | boolean | null | undefined | ContextValue[];
 /**
  * Evaluation Context
  * Holds references used during the evaluation process.
@@ -56,4 +56,3 @@ export interface Evaluable {
     toString(): string;
 }
 export type SimplifyArgs = Parameters<Evaluable['simplify']>;
-export {};

package/types/index.d.ts

@@ -39,12 +39,18 @@ declare class Engine {
     private readonly parser;
     private readonly evaluator;
     private readonly bytecodeCache;
+    private readonly simplifyCache;
     /**
      * @constructor
      * @param {Options?} options Parser options.
      */
     constructor(options?: Partial<Options>);
     private getCompiled;
+    /**
+     * Compile for simplify: preserves the original nested structure so the
+     * simplify interpreter can reproduce the input verbatim (no OR_AND_IN merge).
+     */
+    private getSimplifiedCompiled;
     /**
      * Evaluate the expression.
      * @param {ExpressionInput} exp Raw expression.