Performance

This page describes the performance characteristics of the rule engine across its two operational phases, two execution modes, and two implementation strategies.

All figures below are measured on a single machine (M1 Pro MBP). Use them as relative guidance rather than absolute targets — hardware, V8 JIT state, and rule complexity will all shift the absolute numbers.

Overview

Engine operation divides into two phases:

• Parsing loads rules and function declarations into a workspace. This is usually a one-time startup cost.
• Execution processes contexts against the loaded rules. This is the repeated request-time cost.

Within execution there are two modes (through different requests):

• Forward chaining iteratively evaluates all applicable rules until no further changes occur.
• Backward chaining is goal-directed and evaluates only the rules needed to derive a requested output.

Within execution there are two implementation strategies:

• Dynamic compilation compiles rules and functions to native JavaScript at load time using FunctionCompiler.enabled = true.
• Expression traversal evaluates rules and functions by walking the parsed expression tree at run time.

Scalability Under Load

The measurements below show the main scaling behavior first, before the single-scenario comparisons later in this page.

These Mermaid charts compare sampled doubling steps as categories. The even spacing is a good fit for comparative checkpoints, but it still does not represent a geometrically exact numeric x-axis.

Data-Load Scaling — Candidate Count

These measurements use a backward-chaining request and vary only the candidate pool size. The charts below show per-iteration time, while the table keeps both time and heap-change reference values.

Blue line = Compiler OFF. Green line = Compiler ON.

%%{init: {'xyChart': {'height': 240}, 'themeVariables': {'xyChart': {'plotColorPalette': '#2563eb, #16a34a'}}}}%%
xychart-beta
    title "Candidate Count Scaling"
    x-axis [40, 80, 160, 320, 640, 1280, 2560, 5120, 10240]
    y-axis "ms / iteration" 0 --> 16
    line [0.192, 0.176, 0.27, 0.508, 0.978, 1.919, 3.816, 7.725, 15.194]
    line [0.07, 0.039, 0.041, 0.053, 0.089, 0.161, 0.315, 0.583, 1.122]

Time growth is close to linear in candidate count for both modes, which is what you want in a selector workload. In this latest run the compiler is dramatically faster, and the gap widens as the pool grows: it starts around 2.7× at 40 candidates and grows to roughly 13× by 10 240 candidates.

Heap change is included in the comparison table for reference, but not charted here because garbage collection timing dominates the sign and size of short-run allocation deltas.

Rule-Count Scaling — Dense Activation

These measurements use a forward-chaining request and vary only the number of loaded rules. The charts below show per-iteration time, while the table keeps both time and heap-change reference values.

Blue line = Compiler OFF. Green line = Compiler ON.

%%{init: {'xyChart': {'height': 240}, 'themeVariables': {'xyChart': {'plotColorPalette': '#2563eb, #16a34a'}}}}%%
xychart-beta
    title "Rule Count Scaling, Dense Activation"
    x-axis [40, 80, 160, 320, 640, 1280, 2560, 5120, 10240]
    y-axis "ms / iteration" 0 --> 15
    line [0.074, 0.1, 0.181, 0.348, 0.664, 1.337, 2.908, 6.801, 13.798]
    line [0.083, 0.098, 0.163, 0.327, 0.663, 1.352, 3.442, 6.853, 14.261]

Engine performance still scales roughly linearly with rule count. In this denser benchmark the two modes are effectively near parity across most of the range, with small wins alternating between them. That suggests the dominant cost when many rules remain active is not only expression evaluation, but also rule scheduling, context mutation, conflict handling, and repeated iteration through the active rule set.

Rule-Count Scaling — Selective Activation

The following benchmark models a more common production shape where only about 25% of loaded rules are selected and executed on a given request. That is where the engine's rule-selection strategy has more room to help.

Blue line = Compiler OFF. Green line = Compiler ON.

%%{init: {'xyChart': {'height': 240}, 'themeVariables': {'xyChart': {'plotColorPalette': '#2563eb, #16a34a'}}}}%%
xychart-beta
    title "Rule Count Scaling, 25% Active"
    x-axis [40, 80, 160, 320, 640, 1280, 2560, 5120, 10240]
    y-axis "ms / iteration" 0 --> 9.5
    line [0.068, 0.067, 0.103, 0.18, 0.357, 0.646, 1.44, 3.441, 8.947]
    line [0.074, 0.064, 0.105, 0.182, 0.34, 0.623, 1.326, 3.415, 7.733]

This selective-activation scenario scales better than the denser benchmark above, especially at larger rule counts. That is consistent with the expectation that rule selection and Rete-style discrimination help most when many loaded rules are irrelevant to a particular request. In this case the effect is more visible in forward-chaining requests, because selective rule activation reduces the amount of work done across the active rule set. The compiler effect is still smaller than in data-load scaling, but the compiled path regains a modest edge at larger rule counts.

Takeaway:

• Large candidate-pool workloads benefit very strongly from compilation in this run, with the advantage widening from roughly 2.7× to 13.5× as load grows.
• Large rule sets still scale acceptably with rule count. In dense activation the two modes are close to parity, while in the more selective 25%-active scenario the engine benefits more from rule selection and the compiled path regains a modest advantage at larger scales.

Phase 1: Parsing

Parsing is the one-time cost of loading rules into a workspace. The difference between compiler-on and compiler-off at this stage is small: both paths perform the same tokenising, AST construction, and type resolution. The compiler adds a one-time code-generation step per function, whose cost is quickly amortised over executions.

%%{init: {'xyChart': {'height': 200}}}%%
xychart-beta horizontal
    title "Parsing — Adding 1 000 Rules (ms)"
    x-axis ["Compiler ON", "Compiler OFF"]
    y-axis "Time (ms)" 0 --> 70
    bar [55.017, 56.28]

The compiler allocates less heap during parsing because it converts expression trees into compact native functions; the AST nodes can then be released sooner.

Takeaway: Parsing time is not meaningfully affected by the compiler flag. Optimise for parse cost by loading rules once at startup rather than per request.

Phase 2: Execution

Forward Chaining

Forward chaining processes a context through the full loaded rule set, iterating until the context reaches a stable state.

The following measurements use 1 000 contexts processed against 2 000 loaded rules:

%%{init: {'xyChart': {'height': 200}}}%%
xychart-beta horizontal
    title "Per Context (Forward)"
    x-axis ["Compiler ON", "Compiler OFF"]
    y-axis "ms / context" 0 --> 0.3
    bar [0.24, 0.279]

The compiler eliminates intermediate expression-node allocations during evaluation, which is why the heap actually shrinks slightly (prior GC pressure from parsing is released) when the compiler is on.

Takeaway: The compiler gives roughly a 14 % throughput improvement and removes ephemeral heap pressure in high-volume forward-chaining workloads.

Backward Chaining — Candidate Selection

Two implementations are compared:

• Engine (workspace functions): scoring logic is declared in the rules DSL and evaluated through the engine's backward-chaining path.
• Native TypeScript: equivalent logic written as plain TypeScript array functions, bypassing the engine entirely.

Small Pool (3 candidates, 10 000 runs)

%%{init: {'xyChart': {'height': 250}}}%%
xychart-beta horizontal
    title "Selection — 3 Candidates (Backward)"
    x-axis ["Engine (ON)", "Engine (OFF)", "Native (ON)", "Native (OFF)"]
    y-axis "ms / iteration" 0 --> 0.03
    bar [0.0268, 0.0275, 0.00039, 0.00037]

For small pools the compiler makes little practical difference because the per-run overhead is dominated by workspace bookkeeping rather than expression evaluation. The engine path is roughly 70× slower than native at this pool size.

Large Pool (10 000 candidates, 100 runs)

%%{init: {'xyChart': {'height': 250}}}%%
xychart-beta horizontal
    title "Selection — 10 000 Candidates (Backward)"
    x-axis ["Engine (ON)", "Engine (OFF)", "Native (ON)", "Native (OFF)"]
    y-axis "ms / iteration" 0 --> 25
    bar [9.399, 24.194, 0.398, 0.393]

At large pool sizes the compiler delivers a 2.6× speedup (939 ms vs 2 419 ms). This is where dynamic compilation pays back its loading cost most clearly. Native TypeScript remains ~24× faster than the compiled engine path and ~62× faster than the expression-traversal (compiler OFF) path.

Peak memory during large-pool selection:

Peak memory is similar across all four configurations (~34–37 MB). The engine path returns near its starting footprint after a GC cycle. The native path retains more post-run heap because of closures captured in the lambda functions; it also recovers to baseline after a full GC.

Implementation Strategy: Compiled vs Expression Traversal

The compiler flag selects between two mutually exclusive execution strategies for DSL functions:

• Compiler OFF — the engine walks the parsed expression tree at call time (expression traversal).
• Compiler ON — the engine calls a native JavaScript function generated once at load time. No traversal occurs.

%%{init: {'xyChart': {'height': 200}}}%%
xychart-beta horizontal
    title "Function Execution — Per Call"
    x-axis ["Expression traversal (OFF)", "Dynamic compilation (ON)"]
    y-axis "µs / call" 0 --> 7
    bar [6.218, 0.006]

The compiled path is approximately 1 000× faster per call and produces negligible heap churn. Expression traversal allocates node-level objects on each evaluation, producing several megabytes of short-lived heap pressure per 100 000 calls.

%%{init: {'xyChart': {'height': 200}}}%%
xychart-beta horizontal
    title "Function Execution — Heap Change per 100 000 Calls (MB)"
    x-axis ["Expression traversal (OFF)", "Dynamic compilation (ON)"]
    y-axis "Heap change (MB)" 0 --> 4
    bar [3.15, 0.005]

A separate baseline measurement ran the traversal path alongside compiled functions in the same process and recorded 488.6 ms for 100 000 traversal calls. The ~21 % difference versus the 621.8 ms standalone figure likely reflects V8 JIT warmup from the compiled path benefiting surrounding interpreted code.

Guidance

The choice between forward and backward chaining is primarily a business and modelling decision, not a pure performance decision. The guidance below focuses on when the compiler is likely to help, once that execution mode has already been chosen for functional reasons.

When to enable the compiler

• Function-heavy rules called thousands of times per request or more
• Large candidate pools or other workloads (>1 000 candidates or items)
• Production deployments where per-call latency or throughput matters
• Background batch scoring jobs

When to keep the compiler off

• Rule development, authoring, and testing — traversal gives full expression-level introspection, step-through rendering, and readable error context
• Rules loaded and discarded frequently (e.g. per-request workspaces) where compilation cost is not amortised
• Small, infrequently run rule sets where the difference is negligible

Replacing native logic with engine rules

The engine path adds overhead compared with equivalent native TypeScript. Use the figures below as a rough guide:

This overhead is the trade-off for declarative, auditable, type-checked rules that can be changed without redeploying application code. For the scenarios where the engine is the right tool, it is fast enough; for pure algorithmic throughput where no rule-level auditability is needed, native TypeScript will always win.