Crate datalogic_rs

Expand description

§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
50+ 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:

Compilation: JSON logic is parsed into Logic with OpCode dispatch
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.
NumericCoercionConfig: Knobs for the implicit value→number coercions arithmetic and comparison perform on non-numeric arguments.
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. Mirrors crate::Session 1:1 — every eval* returns a TracedRun<R> carrying the trace alongside the result, where R is the same shape that Session::eval* would return. Owns its own bumpalo::Bump across calls; reset is per-call (the trace path always allocates a fresh arena 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::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