Crate datalogic_rs 

datalogic-rs

A high-performance, thread-safe Rust implementation of JSONLogic.

Overview

datalogic-rs provides a powerful rule evaluation engine that compiles JSONLogic expressions into optimized, reusable structures that can be evaluated across multiple threads with zero overhead.

Key Features

• Compilation-based optimization: Parse once, evaluate many times
• Thread-safe by design: Share compiled logic across threads with Arc
• 84 built-in operators: Complete JSONLogic compatibility plus extensions
• Arena-allocated evaluation: Results live in a bumpalo::Bump arena and can borrow directly into caller input for zero-copy paths
• Extensible: Add custom operators via the CustomOperator trait
• Structured templates: Preserve object structure for dynamic outputs

Quick Start (one-shot)

use datalogic_rs::Engine;

let engine = Engine::new();
let result = engine.eval_str(
    r#"{"==": [{"var": "status"}, "active"]}"#,
    r#"{"status": "active"}"#,
).unwrap();
assert_eq!(result, "true");

Reusing the arena across many evaluations

For high-throughput callers, open a Session handle. It owns a bumpalo::Bump, resets it between calls, and returns owned results so you don’t have to juggle arena lifetimes:

use datalogic_rs::Engine;

let engine = Engine::new();
let compiled = engine.compile(r#"{"+": [{"var": "x"}, 1]}"#).unwrap();
let mut session = engine.session();

for x in 0..3 {
    let payload = format!(r#"{{"x": {}}}"#, x);
    let result = session.eval_str(&compiled, &payload).unwrap();
    assert_eq!(result, (x + 1).to_string());
    // The session does not auto-reset; bound peak memory by
    // resetting between iterations (constant-time, reuses chunks).
    session.reset();
}

Power-user (compile once, evaluate many, zero-copy results)

When the result borrow can stay scoped to a caller-managed bumpalo::Bump, skip the deep-clone and use Engine::evaluate directly. evaluate accepts any input shape via EvalInput: &str, &OwnedDataValue, &serde_json::Value, an owned DataValue<'a>, or an existing &'a DataValue<'a>.

use bumpalo::Bump;
use datalogic_rs::Engine;

let engine = Engine::new();
let compiled = engine.compile(r#"{"==": [{"var": "status"}, "active"]}"#).unwrap();

let arena = Bump::new();
let result = engine.evaluate(&compiled, r#"{"status": "active"}"#, &arena).unwrap();
assert_eq!(result.as_bool(), Some(true));

Architecture

The library uses a two-phase approach:

1. Compilation: JSON logic is parsed into Logic with OpCode dispatch
2. Evaluation: Compiled logic is evaluated through arena dispatch — results are &'a DataValue<'a> allocated in a bumpalo::Bump for the duration of one evaluate call.

This design enables sharing compiled logic across threads, eliminates repeated parsing overhead, and lets read-through operations like var return zero-copy borrows into the caller’s input data.

Re-exports

pub use bumpalo;

pub use datavalue;

Modules

operator

Public scaffolding for user-supplied operators.

Structs

Engine

JSONLogic compile/evaluate engine.

EngineBuilder

Builder for Engine. Construct via Engine::builder.

Error

Error returned by every crate::Engine operation.

EvaluationConfig

Knobs that change how an Engine treats edge cases during evaluation — non-numeric arguments to arithmetic, division by zero, loose equality across types, truthiness rules, numeric coercion, and a recursion-depth cap.

ExecutionSteptrace

Captures state at each evaluation step.

ExpressionNodetrace

Represents a node in the expression tree for flow diagram rendering.

Logic

Compiled logic that can be evaluated multiple times across different data.

Meteredbudget

An evaluation’s result paired with what it cost.

NumericCoercionConfig

Knobs for the implicit value→number coercions arithmetic and comparison perform on non-numeric arguments.

ParsedData

A parsed JSON document that owns its backing storage.

PathStep

One node along the path from the root of a compiled rule down to the failing sub-expression. Returned root-to-leaf by crate::Logic::resolve_node_ids / crate::Error::resolve_path.

Session

Reusable evaluation handle. Construct via Engine::session.

TracedRuntrace

Result of a traced evaluation produced by TracedSession. Always includes the trace data; the value-or-error split lives on Self::result.

TracedSessiontrace

Trace-enabled view over a crate::Engine engine. Constructed via crate::Engine::trace. Every eval* returns a TracedRun<R> carrying the trace alongside the result, where R is the same shape the corresponding Session::eval* would return. The inputs differ from crate::Session, though: Self::eval and Self::eval_borrowed take compiled crate::Logic, while Self::eval_str and Self::eval_into take a rule source (crate::IntoLogic) and compile it with the optimizer disabled so every operator surfaces a step. The trace path allocates a fresh bumpalo::Bump per call (nothing is retained between runs) to keep the borrowed-result lifetime tied to the run.

Enums

DataValue

Arena-allocated JSON value tree. Mirrors serde_json::Value in shape and access surface, but every composite payload lives in a Bump.

DivisionByZeroHandling

Defines how to handle division by zero

ErrorKind

Discriminant for crate::Error. Stable variant tags are exposed via crate::Error::tag for matching across releases.

NanHandling

Defines how to handle NaN (Not a Number) scenarios in arithmetic operations

TruthyEvaluator

Defines how to evaluate truthiness of values

Traits

ArenaExt

Allocate borrowed DataValues in a Bump without typing arena.alloc(DataValue::...) at every return.

CustomOperator

Custom operator hook for the Engine.

EvalInput

Adapter trait that converts a value into a &'a DataValue<'a> borrowed from the caller-supplied arena. Sealed — the supported input shapes are listed in this file; external crates cannot add new ones.

FromDataValue

Convert a borrowed arena DataValue into a concrete result type.

IntoLogic

Convert self into an OwnedDataValue suitable for compilation.

OwnedInput

Adapter trait for crate::Engine::eval / crate::Engine::eval_str / crate::Engine::eval_into and the module-level datalogic_rs::eval* helpers, where the engine creates and owns the arena per call.

Functions

compile

Compile a rule using the default engine. Equivalent to Engine::default().compile(rule).

eval

One-shot evaluation returning datavalue::OwnedDataValue.

eval_intoserde_json

One-shot evaluation deserialised into a typed T: DeserializeOwned.

eval_str

One-shot evaluation returning a JSON String.

Type Aliases

CustomErrorSource

Trait-object alias for the source carried by ErrorKind::Custom. Reference-counted so ErrorKind stays cheap to clone, and bounded so a single crate::Error value can be sent across threads.

Result

Result type for Engine operations