datalogic-rs

A fast, production-ready Rust engine for JSONLogic.

Try the JSONLogic Online Debugger to interactively test your rules

datalogic-rs is a high-performance Rust implementation of JSONLogic for evaluating logical rules expressed as JSON. It provides a fast, memory-efficient, and thread-safe way to evaluate complex business rules, feature flags, dynamic pricing logic, and more.

The same engine ships across runtimes: Rust, Node.js (native), JavaScript / TypeScript (WebAssembly), Python, Go, JVM (Java/Kotlin/Scala), .NET, PHP, and a React visual debugger. Author the rule once; evaluate it anywhere. For the cross-runtime overview and per-binding install instructions, see the repository README.

v5 is here. v5 is a breaking release that renames DataLogic → Engine, makes one-shot evaluation string-based, switches custom operators to a pre-evaluated arena API, and removes the implicit serde_json dependency from the default build. v5 is a hard cliff — there is no compatibility shim. See the Migration Guide for the conceptual overview and the repo-root MIGRATION.md for the full v4 → v5 cookbook.

Why datalogic-rs?

• Fast - OpCode-based dispatch with compile-time optimization, plus arena allocation for zero-copy reads
• Thread-Safe - Wrap Logic in Arc and share across threads (or use Engine::compile_arc to do it in one step)
• Zero unsafe - The crate enforces #![forbid(unsafe_code)]
• serde_json-free by default - The string-based API needs no serde_json dependency; opt into the serde_json feature when you need serde_json::Value interop or the typed eval_into::<T> paths
• Five-tier API ladder - module-level helpers (datalogic_rs::eval_str, …) for one-shot use, Engine for configured workloads, Session for compile-once / evaluate-many hot loops, raw evaluate(&Bump) for zero-copy result pipelines, and Engine::trace() for debugging
• Cross-runtime - same rules, same semantics across Rust, WASM, Python, Go, and the React debugger
• Extensible - Register custom operators on an EngineBuilder
• Feature-Rich - 59 built-in operators including datetime, regex, and error handling
• Fully Compliant - Passes the official JSONLogic test suite

How It Works

datalogic-rs uses a two-phase approach:

1. Compilation: Your JSON logic is parsed and compiled into a reusable Logic. This phase:

   • Assigns OpCodes to built-in operators for fast dispatch
   • Pre-evaluates constant expressions
   • Analyzes structure for templating mode

2. Evaluation: The compiled logic is evaluated against your data with:

   • Direct OpCode dispatch (no string lookups at runtime)
   • Arena-allocated &DataValue<'a> results that can borrow zero-copy from the input
   • Context stack for nested operations (map, filter, reduce)

Quick Example

#![allow(unused)]
fn main() {
// One-shot evaluation: returns a JSON string.
let result = datalogic_rs::eval_str(
    r#"{">": [{"var": "age"}, 18]}"#,
    r#"{"age": 21}"#,
).unwrap();
assert_eq!(result, "true");
}

For repeated evaluation, compile once and reuse via a session:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

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

let r1 = session.eval_str(&compiled, r#"{"age": 21}"#).unwrap();
let r2 = session.eval_str(&compiled, r#"{"age": 16}"#).unwrap();
assert_eq!(r1, "true");
assert_eq!(r2, "false");
session.reset();
}

What is JSONLogic?

JSONLogic is a standard for expressing logic rules as JSON. This makes it:

• Portable: Rules can be stored in databases, sent over APIs, or embedded in configuration
• Language-agnostic: The same rules work across different implementations
• Human-readable: Rules are easier to understand than arbitrary code
• Safe: Rules can be evaluated without arbitrary code execution

A JSONLogic rule is a JSON object where:

• The key is the operator name
• The value is an array of arguments

{"operator": [arg1, arg2, ...]}

For example:

{"and": [
  {">": [{"var": "age"}, 18]},
  {"==": [{"var": "country"}, "US"]}
]}

This rule checks if age > 18 AND country == "US".

Next Steps

• Installation - Add datalogic-rs to your project
• Quick Start - Get up and running in minutes
• Migration Guide - Move from v4 to v5
• Operators - Explore all 59 built-in operators
• API Reference - Public Rust types and the 5-tier API model

Using another language? This site focuses on the Rust crate; for Node.js (native), JavaScript / TypeScript (WASM), Python, Go, JVM, .NET, PHP, and React, jump straight to the per-binding README in the repo root.

Playground

Want the full experience? Try the Full-Page Visual Editor with examples and resizable panels.

Try JSONLogic expressions right in your browser! This playground uses the visual debugger component powered by WebAssembly.

How to Use

1. Logic: Enter your JSONLogic expression in the Logic panel
2. Data: Enter the JSON data to evaluate against in the Data panel
3. Diagram: View the visual diagram of your logic expression
4. Examples: Use the dropdown to load pre-built examples

Quick Reference

Basic Operators

Array Operations

String Operations

Example: Feature Flag

Determine if a user has access to a premium feature:

{
  "and": [
    {"==": [{"var": "user.plan"}, "premium"]},
    {">=": [{"var": "user.accountAge"}, 30]}
  ]
}

Data:

{
  "user": {
    "plan": "premium",
    "accountAge": 45
  }
}

Example: Dynamic Pricing

Calculate a discounted price based on quantity:

{
  "if": [
    {">=": [{"var": "quantity"}, 100]},
    {"*": [{"var": "price"}, 0.8]},
    {"if": [
      {">=": [{"var": "quantity"}, 50]},
      {"*": [{"var": "price"}, 0.9]},
      {"var": "price"}
    ]}
  ]
}

Data:

{
  "quantity": 75,
  "price": 100
}

Learn More

• Operators Overview - Full operator documentation
• Getting Started - Using the library
• Use Cases - Real-world examples

Installation

Adding to Your Project

Add datalogic-rs to your Cargo.toml:

[dependencies]
datalogic-rs = "5.0"

Or use cargo add:

cargo add datalogic-rs

Note: v5 does not require serde_json by default — the canonical entry points (Engine::eval_str, Engine::compile(&str), datalogic_rs::eval_str) are string-based. Add the serde_json feature only if you need serde_json::Value interop or the typed eval_into::<T> paths.

Feature Flags

v5 splits the surface into a small core plus opt-in features:

Example — opt into serde_json::Value interop plus templating:

[dependencies]
datalogic-rs = { version = "5.0", features = ["serde_json", "templating"] }
serde_json = "1.0"

Version Selection

• v5.x (current): canonical string-based API, opt-in serde_json, builder-only operator registration. v5 is a hard cliff — no compat shim — so plan a single cutover.
• v4.x: DataLogic engine, serde_json::Value-first API. Still functional but no longer the active line.
• v3.x: Arena-based allocation, predates the v4 simplification. Bug-fix only.

If you’re upgrading from v4, see the Migration Guide.

Other languages

The Rust crate is the engine; every other language uses its own binding. Click through to the binding’s README for install instructions and the language-idiomatic API:

Building the WASM binding from source:

cd bindings/wasm
./build.sh

Minimum Rust Version

datalogic-rs v5 uses Rust edition 2024 — Rust 1.85 or later is required. The crate is built with #![forbid(unsafe_code)].

Verifying Installation

Create a simple test:

fn main() {
    let result = datalogic_rs::eval_str(r#"{"+": [1, 2]}"#, r#"{}"#).unwrap();

    println!("1 + 2 = {}", result);
    assert_eq!(result, "3");
}

Run with:

cargo run

You should see: 1 + 2 = 3

Quick Start

This guide will get you evaluating JSONLogic rules in minutes.

The simplest path: module-level helpers

For one-off evaluations with no custom operators or configuration, skip the engine entirely. The crate exposes module-level helpers that share a default engine under the hood:

#![allow(unused)]
fn main() {
let result = datalogic_rs::eval_str(
    r#"{">": [{"var": "score"}, 50]}"#,
    r#"{"score": 75}"#,
).unwrap();
assert_eq!(result, "true");
}

The datalogic_rs::eval_str / eval / eval_into / compile functions all delegate to a lazily-constructed default engine. They are the right starting point for tutorials, scripts, and code that doesn’t need custom operators or non-default configuration.

When you need an Engine

Construct an Engine when you need any of: custom operators, a non-default EvaluationConfig, templating mode, a long-lived Session for hot loops, or the raw evaluate path with a caller-owned &Bump.

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

// 1. Create an engine
let engine = Engine::new();

// 2. Compile a rule (string in, Logic out)
let compiled = engine.compile(r#"{">": [{"var": "score"}, 50]}"#).unwrap();

// 3. Evaluate against data via a Session — owned String result
let mut session = engine.session();
let result = session.eval_str(&compiled, r#"{"score": 75}"#).unwrap();
assert_eq!(result, "true");
session.reset();
}

Sessions reuse the same bumpalo::Bump across calls. They never auto-reset — session.reset() between batches keeps peak memory bounded by the largest single evaluation rather than the cumulative loop.

One-shot via Engine

If you’ve already built an Engine (e.g. to register custom operators), its one-shot methods mirror the module-level helpers:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

let engine = Engine::new();
let result = engine
    .eval_str(r#"{"+": [1, 2, 3]}"#, r#"{}"#)
    .unwrap();
assert_eq!(result, "6");
}

eval_str parses the rule + data, evaluates once, and returns the result as a JSON String. eval returns an OwnedDataValue; eval_into::<T> returns a typed T: DeserializeOwned (requires feature = "serde_json").

Power-user: zero-copy borrowed results

When you want zero-copy &DataValue<'a> results and are willing to manage the arena yourself, call Engine::evaluate directly:

#![allow(unused)]
fn main() {
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));
}

Engine::evaluate accepts any input shape via EvalInput: &str, &DataValue<'a>, DataValue<'a>, &OwnedDataValue, or &serde_json::Value (under feature = "serde_json").

Working with Variables

Access data using the var operator:

#![allow(unused)]
fn main() {
// Simple variable access
let r = datalogic_rs::eval_str(r#"{"var": "name"}"#, r#"{"name": "Alice"}"#).unwrap();
assert_eq!(r, "\"Alice\"");

// Nested variable access with dot notation
let r = datalogic_rs::eval_str(
    r#"{"var": "user.address.city"}"#,
    r#"{"user": {"address": {"city": "New York"}}}"#,
).unwrap();
assert_eq!(r, "\"New York\"");

// Default values
let r = datalogic_rs::eval_str(
    r#"{"var": ["missing_key", "default_value"]}"#,
    r#"{}"#,
).unwrap();
assert_eq!(r, "\"default_value\"");
}

Conditional Logic

Use if for branching:

#![allow(unused)]
fn main() {
let rule = r#"{"if": [{">=": [{"var": "age"}, 18]}, "adult", "minor"]}"#;

let r = datalogic_rs::eval_str(rule, r#"{"age": 25}"#).unwrap();
assert_eq!(r, "\"adult\"");

let r = datalogic_rs::eval_str(rule, r#"{"age": 15}"#).unwrap();
assert_eq!(r, "\"minor\"");
}

Combining Conditions

Use and and or to combine conditions:

#![allow(unused)]
fn main() {
// AND: all conditions must be true
let rule = r#"{"and": [
    {">=": [{"var": "age"}, 18]},
    {"==": [{"var": "verified"}, true]}
]}"#;
let r = datalogic_rs::eval_str(rule, r#"{"age": 21, "verified": true}"#).unwrap();
assert_eq!(r, "true");

// OR: at least one condition must be true
let rule = r#"{"or": [
    {"==": [{"var": "role"}, "admin"]},
    {"==": [{"var": "role"}, "moderator"]}
]}"#;
let r = datalogic_rs::eval_str(rule, r#"{"role": "admin"}"#).unwrap();
assert_eq!(r, "true");
}

Array Operations

Filter, map, and reduce arrays:

#![allow(unused)]
fn main() {
// Filter: keep elements matching a condition
let r = datalogic_rs::eval_str(
    r#"{"filter": [{"var": "numbers"}, {">": [{"var": ""}, 5]}]}"#,
    r#"{"numbers": [1, 3, 5, 7, 9]}"#,
).unwrap();
assert_eq!(r, "[7,9]");

// Map: transform each element
let r = datalogic_rs::eval_str(
    r#"{"map": [{"var": "numbers"}, {"*": [{"var": ""}, 2]}]}"#,
    r#"{"numbers": [1, 2, 3]}"#,
).unwrap();
assert_eq!(r, "[2,4,6]");
}

Error Handling

The eval* methods return Result<_, datalogic_rs::Error>. The error carries a stable kind, the offending operator, and a path breadcrumb so callers can surface where the failure occurred:

#![allow(unused)]
fn main() {
use datalogic_rs::ErrorKind;

match datalogic_rs::eval_str(r#"{"+": ["text", 1]}"#, r#"{}"#) {
    Ok(value) => println!("ok: {}", value),
    Err(err) => {
        println!("kind: {}", err.tag());
        if let ErrorKind::Thrown(payload) = &err.kind {
            println!("thrown payload: {:?}", payload);
        }
    }
}
}

For runtime errors that should be caught inside the rule, enable the error-handling feature and use the try operator:

#![allow(unused)]
fn main() {
// Cargo.toml: features = ["error-handling"]
let r = datalogic_rs::eval_str(
    r#"{"try": [{"/": [10, {"var": "divisor"}]}, 0]}"#,
    r#"{"divisor": 0}"#,
).unwrap();
// `0` is returned when the divide raises.
}

Next Steps

• Basic Concepts - Understand the architecture
• Operators - Explore all available operators
• Custom Operators - Extend with your own logic
• Migration Guide - Move from v4 to v5

Basic Concepts

Understanding how datalogic-rs works will help you use it effectively.

JSONLogic Format

A JSONLogic rule is a JSON object where:

• The key is the operator name
• The value is an array of arguments (or a single argument)

{ "operator": [arg1, arg2, ...] }

Arguments can be:

• Literal values: 1, "hello", true, null
• Arrays: [1, 2, 3]
• Nested operations: { "var": "x" }

Examples

// Simple comparison
{ ">": [5, 3] }  // true

// Variable access
{ "var": "user.name" }  // Access user.name from data

// Nested operations
{ "+": [{ "var": "a" }, { "var": "b" }] }  // Add two variables

// Multiple arguments
{ "and": [true, true, false] }  // false

Compilation vs Evaluation

datalogic-rs separates rule processing into two phases.

Compilation Phase

When you call engine.compile(rule_str), the library:

1. Parses the JSON rule into an internal representation
2. Assigns OpCodes to operators for fast dispatch
3. Pre-evaluates constant sub-expressions
4. Produces a reusable Logic (no Arc wrap by default — wrap explicitly when sharing across threads)

#![allow(unused)]
fn main() {
let compiled = engine.compile(r#"{">": [{"var": "x"}, 10]}"#).unwrap();

// Wrap when you want to share across threads:
let shared = std::sync::Arc::new(compiled);
}

Evaluation Phase

When you evaluate, the engine:

1. Dispatches operations via OpCode (O(1)) for built-ins
2. Walks the context stack for variable lookups
3. Returns an arena-resident &DataValue<'a> (or an owned String / OwnedDataValue / serde_json::Value depending on the entry point)

There are four entry points, picked by what the caller has on hand and how much arena lifetime they want to manage:

#![allow(unused)]
fn main() {
use bumpalo::Bump;
use datalogic_rs::Engine;

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

// Reusable session — caller resets between batches.
let mut session = engine.session();
let _ = session.eval_str(&compiled, r#"{"x": 42}"#).unwrap();
session.reset();

// Or manage the arena yourself for zero-copy results.
let arena = Bump::new();
let r = engine.evaluate(&compiled, r#"{"x": 42}"#, &arena).unwrap();
assert_eq!(r.as_bool(), Some(true));
}

The Engine

The Engine struct is your main entry point. It is built via Engine::new or the EngineBuilder:

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig};

// Default engine
let engine = Engine::new();

// Engine with custom configuration
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .build();

// Engine with templating mode — needs feature = ["templating"]
#[cfg(feature = "templating")]
let engine = Engine::builder().with_templating(true).build();

// Engine with custom operators
struct MyOp;
impl datalogic_rs::CustomOperator for MyOp {
    fn evaluate<'a>(
        &self,
        _args: &[&'a datalogic_rs::DataValue<'a>],
        _ctx: &mut datalogic_rs::operator::EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> datalogic_rs::Result<&'a datalogic_rs::DataValue<'a>> {
        Ok(arena.alloc(datalogic_rs::DataValue::Null))
    }
}
let engine = Engine::builder()
    .add_operator("my_op", MyOp)
    .build();
}

The engine:

• Owns the registered custom operators (frozen at build())
• Holds the evaluation configuration
• Provides compile and evaluate methods

Note: v5 makes operator registration builder-only. You can no longer mutate an Engine to add operators after construction.

Context Stack

The context stack manages variable scope during evaluation. This is important for array operations like map, filter, and reduce.

#![allow(unused)]
fn main() {
// In a filter operation, "" refers to the current element
let r = datalogic_rs::eval_str(
    r#"{"filter": [[1, 2, 3, 4, 5], {">": [{"var": ""}, 3]}]}"#,
    r#"{}"#,
).unwrap();
// Result: "[4,5]"
}

During array operations:

• "" (or var with empty string) refers to the current element
• The outer data context is still accessible
• Nested operations push and pop frames automatically

Type Coercion

JSONLogic operators often perform type coercion:

Arithmetic

• Strings are parsed as numbers when possible ("5" + 3 = 8)
• Non-numeric strings raise a Thrown { type: "NaN" } error by default; configurable via EvaluationConfig::arithmetic_nan_handling

Comparison

• == performs loose equality (with type coercion)
• === performs strict equality (no coercion)

Truthiness

By default, uses JavaScript-style truthiness:

• Falsy: false, 0, "", null, []
• Truthy: everything else

This is configurable via EvaluationConfig.

Thread Safety

Logic is Send + Sync and can be shared across threads via Arc:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;
use std::sync::Arc;
use std::thread;

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

let handles: Vec<_> = (0..4).map(|i| {
    let engine = Arc::clone(&engine);
    let compiled = Arc::clone(&compiled);
    thread::spawn(move || {
        let mut session = engine.session();
        session.eval_str(&compiled, &format!(r#"{{"x": {}}}"#, i)).unwrap()
    })
}).collect();

for h in handles {
    println!("{}", h.join().unwrap());
}
}

Next Steps

• Operators Overview - Learn about all available operators
• Configuration - Customize evaluation behavior
• Custom Operators - Extend with your own logic
• Migration Guide - Move from v4 to v5

Operators Overview

datalogic-rs provides 59 built-in operators organized into logical categories — 57 in the default build plus two opt-in flagd-compatible operators (fractional, sem_ver) behind the flagd Cargo feature. This section documents each operator with syntax, examples, and notes on behavior.

Operator Categories

Operator Syntax

All operators follow the JSONLogic format:

{ "operator": [arg1, arg2, ...] }

Some operators accept a single argument without an array:

{ "var": "name" }
// Equivalent to:
{ "var": ["name"] }

Lazy Evaluation

Several operators use lazy (short-circuit) evaluation:

• and: Stops at first falsy value
• or: Stops at first truthy value
• if: Only evaluates the matching branch
• ?:: Only evaluates the matching branch
• ??: Only evaluates fallback if first value is null

This is important when operations have side effects or when you want to avoid errors:

{
  "and": [
    { "var": "user" },
    { "var": "user.profile.name" }
  ]
}

If user is null, the second condition is never evaluated, avoiding an error.

Type Coercion

Operators handle types differently:

Loose vs Strict

• == and != perform type coercion
• === and !== require exact type match

{ "==": [1, "1"] }   // true (loose)
{ "===": [1, "1"] }  // false (strict)

Numeric Coercion

Arithmetic operators attempt to convert values to numbers:

{ "+": ["5", 3] }  // 8 (string "5" becomes number 5)

Truthiness

Boolean operators use configurable truthiness rules. By default (JavaScript-style):

• Falsy: false, 0, "", null, []
• Truthy: Everything else

Custom Operators

You can add your own operators. See Custom Operators for details.

In v5 operator registration is builder-only:

#![allow(unused)]
fn main() {
let engine = Engine::builder()
    .add_operator("myop", MyOperator)
    .build();
}

Custom operators follow the same syntax in rules:

{ "myop": [arg1, arg2] }

Note: v5 removed the preserve operator. Wrap literals in templating mode (Engine::builder().with_templating(true).build(), requires feature = "templating") if you need to emit a JSON object verbatim from a rule. Literal scalars and arrays already work inline.

Variable Access Operators

These operators access data from the evaluation context.

var

Access a value from the data object using dot notation.

Syntax:

{ "var": "path" }
{ "var": ["path", default] }

Arguments:

• path - Dot-separated path to the value (string)
• default - Optional default value if path doesn’t exist

Returns: The value at the path, or the default value, or null.

Examples:

// Simple access
{ "var": "name" }
// Data: { "name": "Alice" }
// Result: "Alice"

// Nested access
{ "var": "user.address.city" }
// Data: { "user": { "address": { "city": "NYC" } } }
// Result: "NYC"

// Array index access
{ "var": "items.0" }
// Data: { "items": ["a", "b", "c"] }
// Result: "a"

// Default value
{ "var": ["missing", "default"] }
// Data: {}
// Result: "default"

// Access entire data object
{ "var": "" }
// Data: { "x": 1, "y": 2 }
// Result: { "x": 1, "y": 2 }

Try it:

Notes:

• Empty string "" returns the entire data context
• In array operations (map, filter, reduce), "" refers to the current element
• Numeric indices work for both arrays and string characters
• Returns null if path doesn’t exist and no default is provided

val

Alternative variable access with additional path navigation capabilities.

Syntax:

{ "val": "path" }
{ "val": ["path", default] }

Arguments:

• path - Path to the value, supports additional navigation syntax
• default - Optional default value

Returns: The value at the path, or the default value, or null.

Examples:

// Simple access (same as var)
{ "val": "name" }
// Data: { "name": "Bob" }
// Result: "Bob"

// Nested access
{ "val": "config.settings.enabled" }
// Data: { "config": { "settings": { "enabled": true } } }
// Result: true

Try it:

Notes:

• Similar to var but with extended path syntax support
• Useful for complex data navigation scenarios

exists

Check if a variable path exists in the data.

Syntax:

{ "exists": "path" }
{ "exists": { "var": "path" } }

Arguments:

• path - Path to check (string or var operation)

Returns: true if the path exists, false otherwise.

Examples:

// Check if key exists
{ "exists": "name" }
// Data: { "name": "Alice" }
// Result: true

// Check missing key
{ "exists": "age" }
// Data: { "name": "Alice" }
// Result: false

// Check nested path
{ "exists": "user.profile" }
// Data: { "user": { "profile": { "name": "Bob" } } }
// Result: true

// Check with var
{ "exists": { "var": "fieldName" } }
// Data: { "fieldName": "name", "name": "Alice" }
// Result: true (checks if "name" exists)

Try it:

Notes:

• Returns false for paths that don’t exist
• Does not check if the value is null/empty, only if the path exists
• Useful for conditional logic based on data structure

Comparison Operators

Operators for comparing values. All comparison operators support lazy evaluation.

== (Equals)

Loose equality comparison with type coercion.

Syntax:

{ "==": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are equal (after type coercion), false otherwise.

Examples:

// Same type
{ "==": [1, 1] }
// Result: true

// Type coercion
{ "==": [1, "1"] }
// Result: true

{ "==": [0, false] }
// Result: true

{ "==": ["", false] }
// Result: true

// Null comparison
{ "==": [null, null] }
// Result: true

// Arrays
{ "==": [[1, 2], [1, 2]] }
// Result: true

Try it:

Notes:

• Performs type coercion similar to JavaScript’s ==
• For strict comparison without coercion, use ===

=== (Strict Equals)

Strict equality comparison without type coercion.

Syntax:

{ "===": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are equal and same type, false otherwise.

Examples:

// Same type and value
{ "===": [1, 1] }
// Result: true

// Different types
{ "===": [1, "1"] }
// Result: false

{ "===": [0, false] }
// Result: false

// Null
{ "===": [null, null] }
// Result: true

Try it:

!= (Not Equals)

Loose inequality comparison with type coercion.

Syntax:

{ "!=": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are not equal (after type coercion), false otherwise.

Examples:

{ "!=": [1, 2] }
// Result: true

{ "!=": [1, "1"] }
// Result: false (type coercion makes them equal)

{ "!=": ["hello", "world"] }
// Result: true

Try it:

!== (Strict Not Equals)

Strict inequality comparison without type coercion.

Syntax:

{ "!==": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are not equal or different types, false otherwise.

Examples:

{ "!==": [1, "1"] }
// Result: true (different types)

{ "!==": [1, 1] }
// Result: false

{ "!==": [1, 2] }
// Result: true

> (Greater Than)

Check if the first value is greater than the second.

Syntax:

{ ">": [a, b] }
{ ">": [a, b, c] }

Arguments:

• a, b - Values to compare
• c - Optional third value for chained comparison

Returns: true if a > b (and b > c if provided), false otherwise.

Examples:

// Simple comparison
{ ">": [5, 3] }
// Result: true

{ ">": [3, 5] }
// Result: false

// Chained comparison (a > b > c)
{ ">": [5, 3, 1] }
// Result: true (5 > 3 AND 3 > 1)

{ ">": [5, 3, 4] }
// Result: false (3 is not > 4)

// String comparison
{ ">": ["b", "a"] }
// Result: true (lexicographic)

// With variables
{ ">": [{ "var": "age" }, 18] }
// Data: { "age": 21 }
// Result: true

Try it:

>= (Greater Than or Equal)

Check if the first value is greater than or equal to the second.

Syntax:

{ ">=": [a, b] }
{ ">=": [a, b, c] }

Arguments:

• a, b - Values to compare
• c - Optional third value for chained comparison

Returns: true if a >= b (and b >= c if provided), false otherwise.

Examples:

{ ">=": [5, 5] }
// Result: true

{ ">=": [5, 3] }
// Result: true

{ ">=": [3, 5] }
// Result: false

// Chained
{ ">=": [5, 3, 3] }
// Result: true (5 >= 3 AND 3 >= 3)

< (Less Than)

Check if the first value is less than the second.

Syntax:

{ "<": [a, b] }
{ "<": [a, b, c] }

Arguments:

• a, b - Values to compare
• c - Optional third value for chained comparison

Returns: true if a < b (and b < c if provided), false otherwise.

Examples:

{ "<": [3, 5] }
// Result: true

{ "<": [5, 3] }
// Result: false

// Chained (useful for range checks)
{ "<": [1, 5, 10] }
// Result: true (1 < 5 AND 5 < 10)

// Range check: is x between 1 and 10?
{ "<": [1, { "var": "x" }, 10] }
// Data: { "x": 5 }
// Result: true

Try it:

<= (Less Than or Equal)

Check if the first value is less than or equal to the second.

Syntax:

{ "<=": [a, b] }
{ "<=": [a, b, c] }

Arguments:

• a, b - Values to compare
• c - Optional third value for chained comparison

Returns: true if a <= b (and b <= c if provided), false otherwise.

Examples:

{ "<=": [3, 5] }
// Result: true

{ "<=": [5, 5] }
// Result: true

{ "<=": [5, 3] }
// Result: false

// Range check (inclusive)
{ "<=": [1, { "var": "x" }, 10] }
// Data: { "x": 10 }
// Result: true (1 <= 10 AND 10 <= 10)

Notes:

• Chained comparisons are useful for range checks
• { "<": [a, x, b] } is equivalent to a < x AND x < b

Logical Operators

Boolean logic operators with short-circuit evaluation.

! (Not)

Logical NOT - negates a boolean value.

Syntax:

{ "!": value }
{ "!": [value] }

Arguments:

• value - Value to negate

Returns: true if value is falsy, false if value is truthy.

Examples:

{ "!": true }
// Result: false

{ "!": false }
// Result: true

{ "!": 0 }
// Result: true (0 is falsy)

{ "!": 1 }
// Result: false (1 is truthy)

{ "!": "" }
// Result: true (empty string is falsy)

{ "!": "hello" }
// Result: false (non-empty string is truthy)

{ "!": null }
// Result: true (null is falsy)

{ "!": [] }
// Result: true (empty array is falsy)

{ "!": [1, 2] }
// Note: This negates the array [1, 2], not [value]
// Result: false (non-empty array is truthy)

Try it:

Notes:

• Uses configurable truthiness rules (default: JavaScript-style)
• Falsy values: false, 0, "", null, []
• Truthy values: everything else

!! (Double Not / Boolean Cast)

Convert a value to its boolean equivalent.

Syntax:

{ "!!": value }
{ "!!": [value] }

Arguments:

• value - Value to convert to boolean

Returns: true if value is truthy, false if value is falsy.

Examples:

{ "!!": true }
// Result: true

{ "!!": false }
// Result: false

{ "!!": 1 }
// Result: true

{ "!!": 0 }
// Result: false

{ "!!": "hello" }
// Result: true

{ "!!": "" }
// Result: false

{ "!!": [1, 2, 3] }
// Result: true

{ "!!": [] }
// Result: false

{ "!!": null }
// Result: false

Try it:

Notes:

• Equivalent to { "!": { "!": value } }
• Useful for ensuring a boolean result from any value

and

Logical AND with short-circuit evaluation.

Syntax:

{ "and": [a, b, ...] }

Arguments:

• a, b, … - Two or more values to AND together

Returns: The first falsy value encountered, or the last value if all are truthy.

Examples:

// All truthy
{ "and": [true, true] }
// Result: true

// One falsy
{ "and": [true, false] }
// Result: false

// Short-circuit: returns first falsy
{ "and": [true, 0, "never evaluated"] }
// Result: 0

// All truthy returns last value
{ "and": [1, 2, 3] }
// Result: 3

// Multiple conditions
{ "and": [
    { ">": [{ "var": "age" }, 18] },
    { "==": [{ "var": "verified" }, true] },
    { "!=": [{ "var": "banned" }, true] }
]}
// Data: { "age": 21, "verified": true, "banned": false }
// Result: true

Try it:

Notes:

• Short-circuits: stops at first falsy value
• Returns the actual value, not necessarily a boolean
• Empty and returns true (vacuous truth)

or

Logical OR with short-circuit evaluation.

Syntax:

{ "or": [a, b, ...] }

Arguments:

• a, b, … - Two or more values to OR together

Returns: The first truthy value encountered, or the last value if all are falsy.

Examples:

// One truthy
{ "or": [false, true] }
// Result: true

// All falsy
{ "or": [false, false] }
// Result: false

// Short-circuit: returns first truthy
{ "or": [0, "", "found it", "not evaluated"] }
// Result: "found it"

// All falsy returns last value
{ "or": [false, 0, ""] }
// Result: ""

// Default value pattern
{ "or": [{ "var": "nickname" }, { "var": "name" }, "Anonymous"] }
// Data: { "name": "Alice" }
// Result: "Alice" (nickname is null/missing, so returns name)

// Role check
{ "or": [
    { "==": [{ "var": "role" }, "admin"] },
    { "==": [{ "var": "role" }, "moderator"] }
]}
// Data: { "role": "admin" }
// Result: true

Try it:

Notes:

• Short-circuits: stops at first truthy value
• Returns the actual value, not necessarily a boolean
• Useful for default value patterns
• Empty or returns false

Truthiness Reference

The default JavaScript-style truthiness:

This can be customized via EvaluationConfig. See Configuration.

Arithmetic Operators

Mathematical operations with type coercion support.

+ (Add)

Add numbers together, or concatenate strings.

Syntax:

{ "+": [a, b, ...] }
{ "+": value }

Arguments:

• a, b, … - Values to add (variadic)
• Single value is cast to number

Returns: Sum of all arguments, or concatenated string.

Examples:

// Basic addition
{ "+": [1, 2] }
// Result: 3

// Multiple values
{ "+": [1, 2, 3, 4] }
// Result: 10

// Type coercion
{ "+": ["5", 3] }
// Result: 8 (string "5" converted to number)

// Unary plus (convert to number)
{ "+": "42" }
// Result: 42

{ "+": "-3.14" }
// Result: -3.14

// With variables
{ "+": [{ "var": "price" }, { "var": "tax" }] }
// Data: { "price": 100, "tax": 8.5 }
// Result: 108.5

Try it:

Notes:

• Strings are converted to numbers when possible
• Non-numeric strings may result in NaN or error (configurable)
• Single argument converts value to number

- (Subtract)

Subtract numbers.

Syntax:

{ "-": [a, b] }
{ "-": value }

Arguments:

• a - Value to subtract from
• b - Value to subtract
• Single value negates it

Returns: Difference, or negated value.

Examples:

// Subtraction
{ "-": [10, 3] }
// Result: 7

// Unary minus (negate)
{ "-": 5 }
// Result: -5

{ "-": -3 }
// Result: 3

// With coercion
{ "-": ["10", "3"] }
// Result: 7

// Calculate discount
{ "-": [{ "var": "price" }, { "var": "discount" }] }
// Data: { "price": 100, "discount": 15 }
// Result: 85

Try it:

* (Multiply)

Multiply numbers.

Syntax:

{ "*": [a, b, ...] }

Arguments:

• a, b, … - Values to multiply (variadic)

Returns: Product of all arguments.

Examples:

// Basic multiplication
{ "*": [3, 4] }
// Result: 12

// Multiple values
{ "*": [2, 3, 4] }
// Result: 24

// With coercion
{ "*": ["5", 2] }
// Result: 10

// Calculate total
{ "*": [{ "var": "quantity" }, { "var": "price" }] }
// Data: { "quantity": 3, "price": 25 }
// Result: 75

// Apply percentage
{ "*": [{ "var": "amount" }, 0.1] }
// Data: { "amount": 200 }
// Result: 20

Try it:

/ (Divide)

Divide numbers.

Syntax:

{ "/": [a, b] }

Arguments:

• a - Dividend
• b - Divisor

Returns: Quotient.

Examples:

// Basic division
{ "/": [10, 2] }
// Result: 5

// Decimal result
{ "/": [7, 2] }
// Result: 3.5

// Division by zero (configurable behavior)
{ "/": [10, 0] }
// Result: Infinity (default) or error

// With coercion
{ "/": ["100", "4"] }
// Result: 25

// Calculate average
{ "/": [{ "+": [10, 20, 30] }, 3] }
// Result: 20

Try it:

Notes:

• Division by zero behavior is configurable via EvaluationConfig
• Default returns Infinity or -Infinity

% (Modulo)

Calculate remainder of division.

Syntax:

{ "%": [a, b] }

Arguments:

• a - Dividend
• b - Divisor

Returns: Remainder after division.

Examples:

// Basic modulo
{ "%": [10, 3] }
// Result: 1

{ "%": [10, 5] }
// Result: 0

// Negative numbers
{ "%": [-10, 3] }
// Result: -1

// Check if even
{ "==": [{ "%": [{ "var": "n" }, 2] }, 0] }
// Data: { "n": 4 }
// Result: true

Try it:

max

Find the maximum value.

Syntax:

{ "max": [a, b, ...] }
{ "max": array }

Arguments:

• a, b, … - Values to compare, or
• array - Single array of values

Returns: The largest value.

Examples:

// Multiple arguments
{ "max": [1, 5, 3] }
// Result: 5

// Single array
{ "max": [[1, 5, 3]] }
// Result: 5

// With variables
{ "max": [{ "var": "scores" }] }
// Data: { "scores": [85, 92, 78] }
// Result: 92

// Empty array
{ "max": [[]] }
// Result: null

Try it:

min

Find the minimum value.

Syntax:

{ "min": [a, b, ...] }
{ "min": array }

Arguments:

• a, b, … - Values to compare, or
• array - Single array of values

Returns: The smallest value.

Examples:

// Multiple arguments
{ "min": [5, 1, 3] }
// Result: 1

// Single array
{ "min": [[5, 1, 3]] }
// Result: 1

// With variables
{ "min": [{ "var": "prices" }] }
// Data: { "prices": [29.99, 19.99, 39.99] }
// Result: 19.99

// Empty array
{ "min": [[]] }
// Result: null

Try it:

abs

Get the absolute value.

Syntax:

{ "abs": value }

Arguments:

• value - Number to get absolute value of

Returns: Absolute (positive) value.

Examples:

{ "abs": -5 }
// Result: 5

{ "abs": 5 }
// Result: 5

{ "abs": -3.14 }
// Result: 3.14

{ "abs": 0 }
// Result: 0

// Distance between two points
{ "abs": { "-": [{ "var": "a" }, { "var": "b" }] } }
// Data: { "a": 3, "b": 10 }
// Result: 7

Try it:

ceil

Round up to the nearest integer.

Syntax:

{ "ceil": value }

Arguments:

• value - Number to round up

Returns: Smallest integer greater than or equal to value.

Examples:

{ "ceil": 4.1 }
// Result: 5

{ "ceil": 4.9 }
// Result: 5

{ "ceil": 4.0 }
// Result: 4

{ "ceil": -4.1 }
// Result: -4

// Round up to whole units
{ "ceil": { "/": [{ "var": "items" }, 10] } }
// Data: { "items": 25 }
// Result: 3 (need 3 boxes of 10)

Try it:

floor

Round down to the nearest integer.

Syntax:

{ "floor": value }

Arguments:

• value - Number to round down

Returns: Largest integer less than or equal to value.

Examples:

{ "floor": 4.9 }
// Result: 4

{ "floor": 4.1 }
// Result: 4

{ "floor": 4.0 }
// Result: 4

{ "floor": -4.1 }
// Result: -5

// Truncate decimal
{ "floor": { "var": "amount" } }
// Data: { "amount": 99.99 }
// Result: 99

Try it:

Control Flow Operators

Conditional branching and value selection operators.

if

Conditional branching with if/then/else chains.

Syntax:

{ "if": [condition, then_value] }
{ "if": [condition, then_value, else_value] }
{ "if": [cond1, value1, cond2, value2, ..., else_value] }

Arguments:

• condition - Condition to evaluate
• then_value - Value if condition is truthy
• else_value - Value if condition is falsy (optional)
• Additional condition/value pairs for else-if chains

Returns: The value corresponding to the first truthy condition, or the else value.

Examples:

// Simple if/then
{ "if": [true, "yes"] }
// Result: "yes"

{ "if": [false, "yes"] }
// Result: null

// If/then/else
{ "if": [true, "yes", "no"] }
// Result: "yes"

{ "if": [false, "yes", "no"] }
// Result: "no"

// If/else-if/else chain
{ "if": [
    { ">=": [{ "var": "score" }, 90] }, "A",
    { ">=": [{ "var": "score" }, 80] }, "B",
    { ">=": [{ "var": "score" }, 70] }, "C",
    { ">=": [{ "var": "score" }, 60] }, "D",
    "F"
]}
// Data: { "score": 85 }
// Result: "B"

// Nested if
{ "if": [
    { "var": "premium" },
    { "if": [
        { ">": [{ "var": "amount" }, 100] },
        "free_shipping",
        "standard_shipping"
    ]},
    "no_shipping"
]}
// Data: { "premium": true, "amount": 150 }
// Result: "free_shipping"

Try it:

Notes:

• Only evaluates the matching branch (lazy evaluation)
• Empty condition list returns null
• Odd number of arguments uses last as else value

?: (Ternary)

Ternary conditional operator (shorthand if/then/else).

Syntax:

{ "?:": [condition, then_value, else_value] }

Arguments:

• condition - Condition to evaluate
• then_value - Value if condition is truthy
• else_value - Value if condition is falsy

Returns: then_value if condition is truthy, else_value otherwise.

Examples:

// Basic ternary
{ "?:": [true, "yes", "no"] }
// Result: "yes"

{ "?:": [false, "yes", "no"] }
// Result: "no"

// With comparison
{ "?:": [
    { ">": [{ "var": "age" }, 18] },
    "adult",
    "minor"
]}
// Data: { "age": 21 }
// Result: "adult"

// Nested ternary
{ "?:": [
    { "var": "vip" },
    0,
    { "?:": [
        { ">": [{ "var": "total" }, 50] },
        5,
        10
    ]}
]}
// Data: { "vip": false, "total": 75 }
// Result: 5 (shipping cost)

Try it:

Notes:

• Equivalent to { "if": [condition, then_value, else_value] }
• More concise for simple conditions
• Only evaluates the matching branch

?? (Null Coalesce)

Return the first non-null value.

Syntax:

{ "??": [a, b] }
{ "??": [a, b, c, ...] }

Arguments:

• a, b, … - Values to check (variadic)

Returns: The first non-null value, or null if all are null.

Examples:

// First is not null
{ "??": ["hello", "default"] }
// Result: "hello"

// First is null
{ "??": [null, "default"] }
// Result: "default"

// Multiple values
{ "??": [null, null, "found"] }
// Result: "found"

// All null
{ "??": [null, null] }
// Result: null

// With variables (default value pattern)
{ "??": [{ "var": "nickname" }, { "var": "name" }, "Anonymous"] }
// Data: { "name": "Alice" }
// Result: "Alice"

// Note: 0, "", and false are NOT null
{ "??": [0, "default"] }
// Result: 0

{ "??": ["", "default"] }
// Result: ""

{ "??": [false, "default"] }
// Result: false

Try it:

Notes:

• Only checks for null, not other falsy values
• Use or if you want to skip all falsy values
• Short-circuits: stops at first non-null value

Comparison: if vs ?: vs ?? vs or

Examples:

// Value is 0 (falsy but not null)
// Data: { "count": 0 }

{ "if": [{ "var": "count" }, { "var": "count" }, 10] }
// Result: 10 (0 is falsy)

{ "?:": [{ "var": "count" }, { "var": "count" }, 10] }
// Result: 10 (0 is falsy)

{ "??": [{ "var": "count" }, 10] }
// Result: 0 (0 is not null)

{ "or": [{ "var": "count" }, 10] }
// Result: 10 (0 is falsy)

Choose the operator based on whether you want to treat 0, "", and false as valid values.

String Operators

String manipulation and searching operations.

cat

Concatenate strings together.

Syntax:

{ "cat": [a, b, ...] }

Arguments:

• a, b, … - Values to concatenate (variadic)

Returns: Concatenated string.

Examples:

// Simple concatenation
{ "cat": ["Hello", " ", "World"] }
// Result: "Hello World"

// With variables
{ "cat": ["Hello, ", { "var": "name" }, "!"] }
// Data: { "name": "Alice" }
// Result: "Hello, Alice!"

// Non-strings are converted
{ "cat": ["Value: ", 42] }
// Result: "Value: 42"

{ "cat": ["Is active: ", true] }
// Result: "Is active: true"

// Building paths
{ "cat": ["/users/", { "var": "userId" }, "/profile"] }
// Data: { "userId": 123 }
// Result: "/users/123/profile"

Try it:

substr

Extract a substring.

Syntax:

{ "substr": [string, start] }
{ "substr": [string, start, length] }

Arguments:

• string - Source string
• start - Starting index (0-based, negative counts from end)
• length - Number of characters (optional, negative counts from end)

Returns: Extracted substring.

Examples:

// From start index
{ "substr": ["Hello World", 0, 5] }
// Result: "Hello"

// From middle
{ "substr": ["Hello World", 6] }
// Result: "World"

// Negative start (from end)
{ "substr": ["Hello World", -5] }
// Result: "World"

// Negative length (exclude from end)
{ "substr": ["Hello World", 0, -6] }
// Result: "Hello"

// Get file extension
{ "substr": ["document.pdf", -3] }
// Result: "pdf"

// With variables
{ "substr": [{ "var": "text" }, 0, 10] }
// Data: { "text": "This is a long string" }
// Result: "This is a "

Try it:

in

Check if a value is contained in a string or array.

Syntax:

{ "in": [needle, haystack] }

Arguments:

• needle - Value to search for
• haystack - String or array to search in

Returns: true if found, false otherwise.

Examples:

// String contains substring
{ "in": ["World", "Hello World"] }
// Result: true

{ "in": ["xyz", "Hello World"] }
// Result: false

// Array contains element
{ "in": [2, [1, 2, 3]] }
// Result: true

{ "in": [5, [1, 2, 3]] }
// Result: false

// Check membership
{ "in": [{ "var": "role" }, ["admin", "moderator"]] }
// Data: { "role": "admin" }
// Result: true

// Check substring
{ "in": ["@", { "var": "email" }] }
// Data: { "email": "user@example.com" }
// Result: true

Try it:

length

Get the length of a string or array.

Syntax:

{ "length": value }

Arguments:

• value - String or array

Returns: Length (number of characters or elements).

Examples:

// String length
{ "length": "Hello" }
// Result: 5

// Array length
{ "length": [1, 2, 3, 4, 5] }
// Result: 5

// Empty values
{ "length": "" }
// Result: 0

{ "length": [] }
// Result: 0

// With variables
{ "length": { "var": "items" } }
// Data: { "items": ["a", "b", "c"] }
// Result: 3

// Check minimum length
{ ">=": [{ "length": { "var": "password" } }, 8] }
// Data: { "password": "secret123" }
// Result: true

Try it:

starts_with

Check if a string starts with a prefix.

Syntax:

{ "starts_with": [string, prefix] }

Arguments:

• string - String to check
• prefix - Prefix to look for

Returns: true if string starts with prefix, false otherwise.

Examples:

{ "starts_with": ["Hello World", "Hello"] }
// Result: true

{ "starts_with": ["Hello World", "World"] }
// Result: false

// Check URL scheme
{ "starts_with": [{ "var": "url" }, "https://"] }
// Data: { "url": "https://example.com" }
// Result: true

// Case sensitive
{ "starts_with": ["Hello", "hello"] }
// Result: false

Try it:

ends_with

Check if a string ends with a suffix.

Syntax:

{ "ends_with": [string, suffix] }

Arguments:

• string - String to check
• suffix - Suffix to look for

Returns: true if string ends with suffix, false otherwise.

Examples:

{ "ends_with": ["Hello World", "World"] }
// Result: true

{ "ends_with": ["Hello World", "Hello"] }
// Result: false

// Check file extension
{ "ends_with": [{ "var": "filename" }, ".pdf"] }
// Data: { "filename": "report.pdf" }
// Result: true

// Case sensitive
{ "ends_with": ["test.PDF", ".pdf"] }
// Result: false

Try it:

upper

Convert string to uppercase.

Syntax:

{ "upper": string }

Arguments:

• string - String to convert

Returns: Uppercase string.

Examples:

{ "upper": "hello" }
// Result: "HELLO"

{ "upper": "Hello World" }
// Result: "HELLO WORLD"

// With variable
{ "upper": { "var": "name" } }
// Data: { "name": "alice" }
// Result: "ALICE"

Try it:

lower

Convert string to lowercase.

Syntax:

{ "lower": string }

Arguments:

• string - String to convert

Returns: Lowercase string.

Examples:

{ "lower": "HELLO" }
// Result: "hello"

{ "lower": "Hello World" }
// Result: "hello world"

// Case-insensitive comparison
{ "==": [
    { "lower": { "var": "input" } },
    "yes"
]}
// Data: { "input": "YES" }
// Result: true

Try it:

trim

Remove leading and trailing whitespace.

Syntax:

{ "trim": string }

Arguments:

• string - String to trim

Returns: String with whitespace removed from both ends.

Examples:

{ "trim": "  hello  " }
// Result: "hello"

{ "trim": "\n\ttext\n\t" }
// Result: "text"

// Clean user input
{ "trim": { "var": "userInput" } }
// Data: { "userInput": "  search query  " }
// Result: "search query"

Try it:

split

Split a string into an array.

Syntax:

{ "split": [string, delimiter] }

Arguments:

• string - String to split
• delimiter - Delimiter to split on

Returns: Array of substrings.

Examples:

// Split by space
{ "split": ["Hello World", " "] }
// Result: ["Hello", "World"]

// Split by comma
{ "split": ["a,b,c", ","] }
// Result: ["a", "b", "c"]

// Split by empty string (characters)
{ "split": ["abc", ""] }
// Result: ["a", "b", "c"]

// Parse CSV-like data
{ "split": [{ "var": "tags" }, ","] }
// Data: { "tags": "rust,json,logic" }
// Result: ["rust", "json", "logic"]

// Get first part
{ "var": "0" }
// Applied to: { "split": ["user@example.com", "@"] }
// Result: "user"

Try it:

Array Operators

Operations for working with arrays, including iteration and transformation.

merge

Merge multiple arrays into one.

Syntax:

{ "merge": [array1, array2, ...] }

Arguments:

• array1, array2, … - Arrays to merge

Returns: Single flattened array.

Examples:

// Merge two arrays
{ "merge": [[1, 2], [3, 4]] }
// Result: [1, 2, 3, 4]

// Merge multiple
{ "merge": [[1], [2], [3]] }
// Result: [1, 2, 3]

// Non-arrays are wrapped
{ "merge": [[1, 2], 3, [4, 5]] }
// Result: [1, 2, 3, 4, 5]

// With variables
{ "merge": [{ "var": "arr1" }, { "var": "arr2" }] }
// Data: { "arr1": [1, 2], "arr2": [3, 4] }
// Result: [1, 2, 3, 4]

Try it:

filter

Filter array elements based on a condition.

Syntax:

{ "filter": [array, condition] }

Arguments:

• array - Array to filter
• condition - Condition applied to each element (use {"var": ""} for current element)

Returns: Array of elements where condition is truthy.

Examples:

// Filter numbers greater than 2
{ "filter": [
    [1, 2, 3, 4, 5],
    { ">": [{ "var": "" }, 2] }
]}
// Result: [3, 4, 5]

// Filter even numbers
{ "filter": [
    [1, 2, 3, 4, 5, 6],
    { "==": [{ "%": [{ "var": "" }, 2] }, 0] }
]}
// Result: [2, 4, 6]

// Filter objects by property
{ "filter": [
    { "var": "users" },
    { "==": [{ "var": "active" }, true] }
]}
// Data: {
//   "users": [
//     { "name": "Alice", "active": true },
//     { "name": "Bob", "active": false },
//     { "name": "Carol", "active": true }
//   ]
// }
// Result: [{ "name": "Alice", "active": true }, { "name": "Carol", "active": true }]

// Filter with multiple conditions
{ "filter": [
    { "var": "products" },
    { "and": [
        { ">": [{ "var": "price" }, 10] },
        { "var": "inStock" }
    ]}
]}

Try it:

Notes:

• Inside the condition, {"var": ""} refers to the current element
• The original array is not modified

map

Transform each element of an array.

Syntax:

{ "map": [array, transformation] }

Arguments:

• array - Array to transform
• transformation - Operation applied to each element

Returns: Array of transformed elements.

Examples:

// Double each number
{ "map": [
    [1, 2, 3],
    { "*": [{ "var": "" }, 2] }
]}
// Result: [2, 4, 6]

// Extract property from objects
{ "map": [
    { "var": "users" },
    { "var": "name" }
]}
// Data: {
//   "users": [
//     { "name": "Alice", "age": 30 },
//     { "name": "Bob", "age": 25 }
//   ]
// }
// Result: ["Alice", "Bob"]

// Create new objects
{ "map": [
    { "var": "items" },
    { "cat": ["Item: ", { "var": "name" }] }
]}
// Data: { "items": [{ "name": "A" }, { "name": "B" }] }
// Result: ["Item: A", "Item: B"]

// Square numbers
{ "map": [
    [1, 2, 3, 4],
    { "*": [{ "var": "" }, { "var": "" }] }
]}
// Result: [1, 4, 9, 16]

Try it:

reduce

Reduce an array to a single value.

Syntax:

{ "reduce": [array, reducer, initial] }

Arguments:

• array - Array to reduce
• reducer - Operation combining accumulator and current element
• initial - Initial value for accumulator

Returns: Final accumulated value.

Context Variables:

• {"var": "current"} - Current element
• {"var": "accumulator"} - Current accumulated value

Examples:

// Sum all numbers
{ "reduce": [
    [1, 2, 3, 4, 5],
    { "+": [{ "var": "accumulator" }, { "var": "current" }] },
    0
]}
// Result: 15

// Product of all numbers
{ "reduce": [
    [1, 2, 3, 4],
    { "*": [{ "var": "accumulator" }, { "var": "current" }] },
    1
]}
// Result: 24

// Concatenate strings
{ "reduce": [
    ["a", "b", "c"],
    { "cat": [{ "var": "accumulator" }, { "var": "current" }] },
    ""
]}
// Result: "abc"

// Find maximum
{ "reduce": [
    [3, 1, 4, 1, 5, 9],
    { "if": [
        { ">": [{ "var": "current" }, { "var": "accumulator" }] },
        { "var": "current" },
        { "var": "accumulator" }
    ]},
    0
]}
// Result: 9

// Count elements matching condition
{ "reduce": [
    [1, 2, 3, 4, 5, 6],
    { "+": [
        { "var": "accumulator" },
        { "if": [{ ">": [{ "var": "current" }, 3] }, 1, 0] }
    ]},
    0
]}
// Result: 3 (count of numbers > 3)

Try it:

all

Check if all elements satisfy a condition.

Syntax:

{ "all": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if all elements satisfy condition, false otherwise.

Examples:

// All positive
{ "all": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 0] }
]}
// Result: true

// All greater than 5
{ "all": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 5] }
]}
// Result: false

// All users active
{ "all": [
    { "var": "users" },
    { "var": "active" }
]}
// Data: { "users": [{ "active": true }, { "active": true }] }
// Result: true

// Empty array returns true (vacuous truth)
{ "all": [[], { ">": [{ "var": "" }, 0] }] }
// Result: true

Try it:

some

Check if any element satisfies a condition.

Syntax:

{ "some": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if at least one element satisfies condition, false otherwise.

Examples:

// Any negative
{ "some": [
    [1, -2, 3],
    { "<": [{ "var": "" }, 0] }
]}
// Result: true

// Any greater than 10
{ "some": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 10] }
]}
// Result: false

// Any admin user
{ "some": [
    { "var": "users" },
    { "==": [{ "var": "role" }, "admin"] }
]}
// Data: {
//   "users": [
//     { "role": "user" },
//     { "role": "admin" }
//   ]
// }
// Result: true

// Empty array returns false
{ "some": [[], { ">": [{ "var": "" }, 0] }] }
// Result: false

Try it:

none

Check if no elements satisfy a condition.

Syntax:

{ "none": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if no elements satisfy condition, false otherwise.

Examples:

// None negative
{ "none": [
    [1, 2, 3],
    { "<": [{ "var": "" }, 0] }
]}
// Result: true

// None greater than 0
{ "none": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 0] }
]}
// Result: false

// No banned users
{ "none": [
    { "var": "users" },
    { "var": "banned" }
]}
// Data: { "users": [{ "banned": false }, { "banned": false }] }
// Result: true

// Empty array returns true
{ "none": [[], { ">": [{ "var": "" }, 0] }] }
// Result: true

Try it:

sort

Sort an array.

Syntax:

{ "sort": array }
{ "sort": [array] }
{ "sort": [array, comparator] }

Arguments:

• array - Array to sort
• comparator - Optional comparison logic

Returns: Sorted array.

Examples:

// Sort numbers
{ "sort": [[3, 1, 4, 1, 5, 9]] }
// Result: [1, 1, 3, 4, 5, 9]

// Sort strings
{ "sort": [["banana", "apple", "cherry"]] }
// Result: ["apple", "banana", "cherry"]

// Sort with custom comparator
{ "sort": [
    { "var": "items" },
    { "-": [{ "var": "a.price" }, { "var": "b.price" }] }
]}
// Data: {
//   "items": [
//     { "name": "B", "price": 20 },
//     { "name": "A", "price": 10 }
//   ]
// }
// Result: [{ "name": "A", "price": 10 }, { "name": "B", "price": 20 }]

Try it:

slice

Extract a portion of an array.

Syntax:

{ "slice": [array, start] }
{ "slice": [array, start, end] }

Arguments:

• array - Source array
• start - Starting index (negative counts from end)
• end - Ending index, exclusive (optional, negative counts from end)

Returns: Array slice.

Examples:

// From index 2 to end
{ "slice": [[1, 2, 3, 4, 5], 2] }
// Result: [3, 4, 5]

// From index 1 to 3
{ "slice": [[1, 2, 3, 4, 5], 1, 3] }
// Result: [2, 3]

// Last 2 elements
{ "slice": [[1, 2, 3, 4, 5], -2] }
// Result: [4, 5]

// First 3 elements
{ "slice": [[1, 2, 3, 4, 5], 0, 3] }
// Result: [1, 2, 3]

// Pagination
{ "slice": [
    { "var": "items" },
    { "*": [{ "var": "page" }, 10] },
    { "+": [{ "*": [{ "var": "page" }, 10] }, 10] }
]}
// Data: { "items": [...], "page": 0 }
// Result: first 10 items

Try it:

DateTime Operators

Operations for working with dates, times, and durations.

now

Get the current UTC datetime.

Syntax:

{ "now": [] }

Arguments: None

Returns: Current UTC datetime as ISO 8601 string.

Examples:

{ "now": [] }
// Result: "2024-01-15T14:30:00Z" (current time)

// Check if date is in the future
{ ">": [{ "var": "expiresAt" }, { "now": [] }] }
// Data: { "expiresAt": "2025-12-31T00:00:00Z" }
// Result: true or false depending on current time

// Check if event is happening now
{ "and": [
    { "<=": [{ "var": "startTime" }, { "now": [] }] },
    { ">=": [{ "var": "endTime" }, { "now": [] }] }
]}

Try it:

Notes:

• Returns ISO 8601 formatted string (e.g., “2024-01-15T14:30:00Z”)
• Always returns UTC time
• Useful for time-based conditions and comparisons

datetime

Parse or validate a datetime value.

Syntax:

{ "datetime": value }

Arguments:

• value - ISO 8601 datetime string

Returns: The validated datetime string (preserving timezone information).

Examples:

// Parse ISO string
{ "datetime": "2024-01-01T00:00:00Z" }
// Result: "2024-01-01T00:00:00Z"

// With timezone offset
{ "datetime": "2024-01-01T10:00:00+05:30" }
// Result: "2024-01-01T10:00:00+05:30"

// Compare datetimes
{ ">": [
    { "datetime": "2024-06-15T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" }
]}
// Result: true

// Add duration to datetime
{ "+": [
    { "datetime": "2024-01-01T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

Try it:

timestamp

Create or parse a duration value. Durations represent time periods (not points in time).

Syntax:

{ "timestamp": duration_string }

Arguments:

• duration_string - Duration in format like “1d:2h:3m:4s” or partial like “1d”, “2h”, “30m”, “45s”

Returns: Normalized duration string in format “Xd:Xh:Xm:Xs”.

Duration Format:

• d - Days
• h - Hours
• m - Minutes
• s - Seconds

Examples:

// Full duration format
{ "timestamp": "1d:2h:3m:4s" }
// Result: "1d:2h:3m:4s"

// Days only
{ "timestamp": "2d" }
// Result: "2d:0h:0m:0s"

// Hours only
{ "timestamp": "5h" }
// Result: "0d:5h:0m:0s"

// Minutes only
{ "timestamp": "30m" }
// Result: "0d:0h:30m:0s"

// Compare durations
{ ">": [{ "timestamp": "2d" }, { "timestamp": "36h" }] }
// Result: true (2 days > 36 hours)

// Duration equality
{ "==": [{ "timestamp": "1d" }, { "timestamp": "24h" }] }
// Result: true

Try it:

Duration Arithmetic

Durations can be used in arithmetic operations:

// Multiply duration
{ "*": [{ "timestamp": "1d" }, 2] }
// Result: "2d:0h:0m:0s"

// Divide duration
{ "/": [{ "timestamp": "2d" }, 2] }
// Result: "1d:0h:0m:0s"

// Add durations
{ "+": [{ "timestamp": "1d" }, { "timestamp": "12h" }] }
// Result: "1d:12h:0m:0s"

// Subtract durations
{ "-": [{ "timestamp": "2d" }, { "timestamp": "12h" }] }
// Result: "1d:12h:0m:0s"

// Add duration to datetime
{ "+": [
    { "datetime": "2024-01-01T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

// Subtract duration from datetime
{ "-": [
    { "datetime": "2024-01-15T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

// Difference between two datetimes (returns duration)
{ "-": [
    { "datetime": "2024-01-08T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" }
]}
// Result: "7d:0h:0m:0s"

parse_date

Parse a date string with a custom format into an ISO datetime.

Syntax:

{ "parse_date": [string, format] }

Arguments:

• string - Date string to parse
• format - Format string using simplified tokens

Returns: Parsed datetime as ISO 8601 string.

Format Tokens:

Examples:

// Parse US date format
{ "parse_date": ["12/25/2024", "MM/dd/yyyy"] }
// Result: "2024-12-25T00:00:00Z"

// Parse European format
{ "parse_date": ["25-12-2024", "dd-MM-yyyy"] }
// Result: "2024-12-25T00:00:00Z"

// Parse date only
{ "parse_date": ["2024-01-15", "yyyy-MM-dd"] }
// Result: "2024-01-15T00:00:00Z"

// With variable
{ "parse_date": [{ "var": "dateStr" }, "yyyy-MM-dd"] }
// Data: { "dateStr": "2024-06-15" }
// Result: "2024-06-15T00:00:00Z"

Try it:

format_date

Format a datetime as a string with a custom format.

Syntax:

{ "format_date": [datetime, format] }

Arguments:

• datetime - Datetime value to format
• format - Format string using simplified tokens (same as parse_date)

Returns: Formatted date string.

Special Format:

• z - Returns timezone offset (e.g., “+0500”)

Examples:

// Format as date only
{ "format_date": [{ "datetime": "2024-01-15T14:30:00Z" }, "yyyy-MM-dd"] }
// Result: "2024-01-15"

// Format as US date
{ "format_date": [{ "datetime": "2024-12-25T00:00:00Z" }, "MM/dd/yyyy"] }
// Result: "12/25/2024"

// Get timezone offset
{ "format_date": [{ "datetime": "2024-01-01T10:00:00+05:00" }, "z"] }
// Result: "+0500"

// Format current time
{ "format_date": [{ "now": [] }, "yyyy-MM-dd"] }
// Result: "2024-01-15" (current date)

// With variable
{ "format_date": [{ "var": "date" }, "dd/MM/yyyy"] }
// Data: { "date": "2024-12-25T00:00:00Z" }
// Result: "25/12/2024"

Try it:

date_diff

Calculate the difference between two dates in a specified unit.

Syntax:

{ "date_diff": [date1, date2, unit] }

Arguments:

• date1 - First datetime
• date2 - Second datetime
• unit - Unit of measurement: “days”, “hours”, “minutes”, “seconds”

Returns: Difference as an integer in the specified unit.

Examples:

// Days between dates
{ "date_diff": [
    { "datetime": "2024-12-31T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "days"
]}
// Result: 365

// Hours difference
{ "date_diff": [
    { "datetime": "2024-01-01T12:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "hours"
]}
// Result: 12

// With variables
{ "date_diff": [
    { "var": "end" },
    { "var": "start" },
    "days"
]}
// Data: {
//   "start": "2024-01-01T00:00:00Z",
//   "end": "2024-01-15T00:00:00Z"
// }
// Result: 14

// Check if within 24 hours
{ "<": [
    { "date_diff": [{ "now": [] }, { "var": "timestamp" }, "hours"] },
    24
]}
// Data: { "timestamp": "2024-01-15T10:00:00Z" }
// Result: true or false

// Days since creation
{ "date_diff": [
    { "now": [] },
    { "var": "createdAt" },
    "days"
]}

Try it:

DateTime Patterns

Check if date is in the past

{ "<": [{ "var": "date" }, { "now": [] }] }

Check if date is in the future

{ ">": [{ "var": "date" }, { "now": [] }] }

Check if within time window

{ "and": [
    { ">=": [{ "now": [] }, { "var": "startTime" }] },
    { "<=": [{ "now": [] }, { "var": "endTime" }] }
]}

Add days to a date

{ "+": [
    { "var": "date" },
    { "timestamp": "7d" }
]}

Calculate days until expiration

{ "date_diff": [
    { "var": "expiresAt" },
    { "now": [] },
    "days"
]}

Check if expired

{ "<": [{ "var": "expiresAt" }, { "now": [] }] }

Missing Value Operators

Operators for checking if data fields are missing or undefined.

missing

Check for missing fields in the data.

Syntax:

{ "missing": [key1, key2, ...] }
{ "missing": key }

Arguments:

• key1, key2, … - Field names to check

Returns: Array of missing field names.

Examples:

// Check single field
{ "missing": "name" }
// Data: { "age": 25 }
// Result: ["name"]

// Check multiple fields
{ "missing": ["name", "email", "phone"] }
// Data: { "name": "Alice", "phone": "555-1234" }
// Result: ["email"]

// All fields present
{ "missing": ["name", "age"] }
// Data: { "name": "Alice", "age": 25 }
// Result: []

// All fields missing
{ "missing": ["name", "age"] }
// Data: {}
// Result: ["name", "age"]

// Nested fields
{ "missing": ["user.name", "user.email"] }
// Data: { "user": { "name": "Alice" } }
// Result: ["user.email"]

Common Patterns

Require all fields:

{ "!": { "missing": ["name", "email", "password"] } }
// Returns true only if all fields are present

Check if any field is missing:

{ "!!": { "missing": ["name", "email"] } }
// Returns true if ANY field is missing

Conditional validation:

{ "if": [
    { "missing": ["required_field"] },
    { "throw": "Missing required field" },
    "ok"
]}

Try it:

missing_some

Check if at least N fields are missing from a set.

Syntax:

{ "missing_some": [minimum, [key1, key2, ...]] }

Arguments:

• minimum - Minimum number of fields that should be present
• [key1, key2, ...] - Array of field names to check

Returns: Array of missing field names if fewer than minimum are present, empty array otherwise.

Examples:

// Need at least 1 of these contact methods
{ "missing_some": [1, ["email", "phone", "address"]] }
// Data: { "email": "a@b.com" }
// Result: [] (1 present, requirement met)

// Data: {}
// Result: ["email", "phone", "address"] (0 present, need at least 1)

// Need at least 2 of these
{ "missing_some": [2, ["name", "email", "phone"]] }
// Data: { "name": "Alice" }
// Result: ["email", "phone"] (only 1 present, need 2)

// Data: { "name": "Alice", "email": "a@b.com" }
// Result: [] (2 present, requirement met)

// Data: { "name": "Alice", "email": "a@b.com", "phone": "555" }
// Result: [] (3 present, exceeds requirement)

Common Patterns

Require at least one contact method:

{ "!": { "missing_some": [1, ["email", "phone", "fax"]] } }
// Returns true if at least one contact method is provided

Flexible field requirements:

{ "if": [
    { "missing_some": [2, ["street", "city", "zip", "country"]] },
    "Please provide at least 2 address fields",
    "Address accepted"
]}

Require majority of fields:

{ "!": { "missing_some": [3, ["field1", "field2", "field3", "field4", "field5"]] } }
// Returns true if at least 3 of 5 fields are present

Try it:

Comparison: missing vs missing_some

Integration with Validation

Form validation example:

{ "if": [
    { "missing": ["username", "password"] },
    { "throw": { "code": "VALIDATION_ERROR", "missing": { "missing": ["username", "password"] } } },
    { "if": [
        { "missing_some": [1, ["email", "phone"]] },
        { "throw": { "code": "CONTACT_REQUIRED", "message": "Provide email or phone" } },
        "valid"
    ]}
]}

Conditional field requirements:

// If business account, require company name
{ "if": [
    { "==": [{ "var": "accountType" }, "business"] },
    { "!": { "missing": ["companyName", "taxId"] } },
    true
]}

Error Handling Operators

Operators for throwing and catching errors, providing exception-like error handling in JSONLogic.

try

Catch errors and provide fallback values.

Syntax:

{ "try": [expression, fallback] }
{ "try": [expression, catch_expression] }

Arguments:

• expression - Expression that might throw an error
• fallback - Value or expression to use if an error occurs

Returns: Result of expression if successful, or fallback value/expression result if an error occurs.

Context in Catch: When an error is caught, the catch expression can access error details via var:

• { "var": "message" } - Error message
• { "var": "code" } - Error code (if thrown with one)
• { "var": "" } - Entire error object

Examples:

// Simple fallback value
{ "try": [
    { "/": [10, 0] },
    0
]}
// Result: 0 (division by zero caught)

// Expression that succeeds
{ "try": [
    { "+": [1, 2] },
    0
]}
// Result: 3 (no error, normal result)

// Catch with error access
{ "try": [
    { "throw": { "code": "NOT_FOUND", "message": "User not found" } },
    { "cat": ["Error: ", { "var": "message" }] }
]}
// Result: "Error: User not found"

// Access error code
{ "try": [
    { "throw": { "code": 404 } },
    { "var": "code" }
]}
// Result: 404

// Nested try for multiple error sources
{ "try": [
    { "try": [
        { "var": "data.nested.value" },
        { "throw": "nested access failed" }
    ]},
    "default"
]}

Common Patterns

Safe division:

{ "try": [
    { "/": [{ "var": "numerator" }, { "var": "denominator" }] },
    0
]}

Safe property access:

{ "try": [
    { "var": "user.profile.settings.theme" },
    "default-theme"
]}

Error logging pattern:

{ "try": [
    { "risky_operation": [] },
    { "cat": ["Operation failed: ", { "var": "message" }] }
]}

Try it:

throw

Throw an error with optional details.

Syntax:

{ "throw": message }
{ "throw": { "code": code, "message": message, ...} }

Arguments:

• message - Error message string, or
• Error object with code, message, and additional properties

Returns: Never returns normally; throws an error that must be caught by try.

Examples:

// Simple string error
{ "throw": "Something went wrong" }
// Throws error with message "Something went wrong"

// Error with code
{ "throw": { "code": "INVALID_INPUT", "message": "Age must be positive" } }
// Throws error with code and message

// Error with additional data
{ "throw": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email",
    "value": { "var": "email" }
}}
// Throws detailed error with context

// Conditional throw
{ "if": [
    { "<": [{ "var": "age" }, 0] },
    { "throw": { "code": "INVALID_AGE", "message": "Age cannot be negative" } },
    { "var": "age" }
]}
// Data: { "age": -5 }
// Throws error

// Data: { "age": 25 }
// Result: 25

Common Patterns

Validation with throw:

{ "if": [
    { "missing": ["name", "email"] },
    { "throw": {
        "code": "MISSING_FIELDS",
        "message": "Required fields missing",
        "fields": { "missing": ["name", "email"] }
    }},
    "valid"
]}

Business rule enforcement:

{ "if": [
    { ">": [{ "var": "amount" }, { "var": "balance" }] },
    { "throw": {
        "code": "INSUFFICIENT_FUNDS",
        "message": "Amount exceeds balance",
        "requested": { "var": "amount" },
        "available": { "var": "balance" }
    }},
    { "-": [{ "var": "balance" }, { "var": "amount" }] }
]}

Type validation:

{ "if": [
    { "!==": [{ "type": { "var": "value" } }, "number"] },
    { "throw": { "code": "TYPE_ERROR", "message": "Expected number" } },
    { "*": [{ "var": "value" }, 2] }
]}

Try it:

Error Handling Patterns

Graceful Degradation

{ "try": [
    { "var": "user.preferences.language" },
    { "try": [
        { "var": "defaults.language" },
        "en"
    ]}
]}
// Try user preference, then defaults, then hardcoded "en"

Validation Pipeline

{ "try": [
    { "if": [
        { "!": { "var": "input" } },
        { "throw": { "code": "EMPTY", "message": "Input required" } },
        { "if": [
            { "<": [{ "length": { "var": "input" } }, 3] },
            { "throw": { "code": "TOO_SHORT", "message": "Minimum 3 characters" } },
            { "var": "input" }
        ]}
    ]},
    { "cat": ["Validation error: ", { "var": "message" }] }
]}

Error Recovery with Retry Logic

{ "try": [
    { "primary_operation": [] },
    { "try": [
        { "fallback_operation": [] },
        "all operations failed"
    ]}
]}

Collecting All Errors

While JSONLogic doesn’t natively support collecting multiple errors, you can structure validations to report all issues:

{
    "errors": { "filter": [
        [
            { "if": [{ "missing": ["name"] }, "name is required", null] },
            { "if": [{ "missing": ["email"] }, "email is required", null] },
            { "if": [
                { "and": [
                    { "!": { "missing": ["email"] } },
                    { "!": { "in": ["@", { "var": "email" }] } }
                ]},
                "invalid email format",
                null
            ]}
        ],
        { "!==": [{ "var": "" }, null] }
    ]}
}

This returns an array of error messages for all validation failures.

flagd-Compat Operators

Two operators specified by the OpenFeature flagd in-process provider for feature-flag targeting. Implemented to match the canonical Go evaluator byte-for-byte, so a flag definition that works under any flagd provider will produce identical variants here.

Cargo feature: flagd. Off by default — opt in via:

datalogic-rs = { version = "5", features = ["flagd"] }

Both operators return null on malformed input (wrong arg count, unparseable version, missing targeting context, etc.) rather than raising. flagd’s evaluator observes the null and falls back to the flag’s default variant; non-flagd callers can compose with ?? or if for the same effect.

fractional

Deterministic percentage bucketing for A/B tests and gradual rollouts. Buckets are sticky per bucketing key — the same input always lands in the same variant across runs.

Reference: flagd Fractional spec

Algorithm. MurmurHash3 x86-32 of the bucketing key, then bucket = (hash * total_weight) >> 32 and walk cumulative integer weight bands. Identical to the Go evaluator’s core/pkg/evaluator/fractional.go. The hash is vendored inline (~30 LOC) for portability across every target.

Two argument shapes:

1. Explicit bucketing key

The first argument evaluates to a string; the remaining args are [variant, weight] pairs.

{
  "fractional": [
    { "cat": [{ "var": "$flagd.flagKey" }, { "var": "email" }] },
    ["red",   50],
    ["blue",  20],
    ["green", 30]
  ]
}

The canonical pattern concatenates $flagd.flagKey + email so the same email gets different variants on different flags — users aren’t always in the same cohort across your whole product.

2. Implicit bucketing key

Omit the first argument (or pass anything that doesn’t evaluate to a string). The bucketing key is built from the root context as flagKey + targetingKey (the order the flagd Go evaluator uses):

{
  "fractional": [
    ["new-ui", 50],
    ["old-ui", 50]
  ]
}

The evaluation data needs to carry both pieces. flagd in-process providers stamp them onto the context as:

{
  "targetingKey": "alice@example.com",
  "$flagd": { "flagKey": "header-color" }
}

Missing or empty targetingKey in implicit form returns null — there’s no key to hash and flagd’s contract is to fall back to the default variant.

Weights

Weights are relative, not percentages: [50, 50] and [1, 1] produce identical splits because the operator divides by the total. This lets you grow a rollout from [1, 99] → [50, 50] → [99, 1] without renormalizing.

Omitted weights default to 1, so ["red"], ["blue"] is equivalent to ["red", 1], ["blue", 1]. Negative weights clamp to 0.

Composing with if

Real-world usage typically gates fractional behind a precondition rather than running it unconditionally:

{
  "if": [
    { "in": ["@example.com", { "var": "email" }] },
    {
      "fractional": [
        { "cat": [{ "var": "$flagd.flagKey" }, { "var": "email" }] },
        ["new-ui", 50],
        ["old-ui", 50]
      ]
    },
    "old-ui"
  ]
}

sem_ver

Semantic-version comparison with the four normalizations the flagd spec calls for.

Reference: flagd SemVer spec

Syntax:

{ "sem_ver": [version1, operator, version2] }

Operators:

Comparison follows SemVer 2.0 precedence, including pre-release ordering: 1.0.0-alpha < 1.0.0-beta < 1.0.0.

Input normalizations

The operator applies four normalizations to both version arguments before parsing — matching what the flagd evaluator and most other flagd providers do:

1. Strip leading v / V — "v1.2.3", "V1.2.3", and "1.2.3" are all equivalent.
2. Pad partial versions — "1" becomes "1.0.0", "1.2" becomes "1.2.0".
3. Coerce numeric input — 1 (a JSON number) is treated as the string "1", then padded.
4. Drop build metadata — "1.2.3+build.7" is treated as "1.2.3". (SemVer 2.0 specifies build metadata is ignored when determining precedence.)

Examples

// Simple comparison
{ "sem_ver": [{ "var": "app_version" }, ">=", "1.2.0"] }

// Caret: same major
{ "sem_ver": [{ "var": "app_version" }, "^", "1.0.0"] }
// matches 1.0.0, 1.5.3, 1.99.99 — but not 2.0.0

// Tilde: same major + minor
{ "sem_ver": [{ "var": "app_version" }, "~", "1.2.0"] }
// matches 1.2.0, 1.2.5, 1.2.99 — but not 1.3.0

// v-prefixed input is handled transparently
{ "sem_ver": ["v1.2.3", "=", "1.2.3"] }            // true
{ "sem_ver": ["1.2", "<", "1.2.1"] }                // true (1.2 padded to 1.2.0)
{ "sem_ver": [1, "=", "v1.0.0"] }                   // true (int 1 coerced)

Gated rollout pattern

The common shape for shipping a feature only to clients on a recent version:

{
  "if": [
    { "sem_ver": [{ "var": "app_version" }, ">=", "2.0.0"] },
    { "fractional": [
        { "cat": [{ "var": "$flagd.flagKey" }, { "var": "user_id" }] },
        ["new-checkout", 10],
        ["old-checkout", 90]
    ]},
    "old-checkout"
  ]
}

Conformance

The conformance test suites live under crates/datalogic-rs/tests/suites/flagd/ and mirror the upstream Go test fixtures:

• fractional_test.go
• semver_test.go

Every release runs the full suite, so any flagd-spec drift gets caught before publish.

Installation

The @goplasmatic/datalogic-wasm package provides WebAssembly bindings for the datalogic-rs engine, bringing high-performance JSONLogic evaluation to JavaScript and TypeScript.

Package Installation

# npm
npm install @goplasmatic/datalogic-wasm

# yarn
yarn add @goplasmatic/datalogic-wasm

# pnpm
pnpm add @goplasmatic/datalogic-wasm

Build Targets

The package includes three build targets optimized for different environments:

Automatic Target Selection

The package’s exports field automatically selects the appropriate target:

// Browser/Bundler - uses web or bundler target
import init, { evaluate } from '@goplasmatic/datalogic-wasm';

// Node.js - uses nodejs target
const { evaluate } = require('@goplasmatic/datalogic-wasm');

Explicit Target Import

If you need a specific target:

// Web target (ES modules with init)
import init, { evaluate } from '@goplasmatic/datalogic-wasm/web';

// Bundler target
import init, { evaluate } from '@goplasmatic/datalogic-wasm/bundler';

// Node.js target
import { evaluate } from '@goplasmatic/datalogic-wasm/nodejs';

WASM Initialization

For browser and bundler environments, you must initialize the WASM module before using any functions:

import init, { evaluate } from '@goplasmatic/datalogic-wasm';

// Initialize once at application startup
await init();

// Now you can use evaluate, CompiledRule, etc.
const result = evaluate('{"==": [1, 1]}', '{}', false);

Note: Node.js does not require initialization - you can use functions immediately after import.

TypeScript Support

The package includes TypeScript declarations. No additional @types package is needed.

import init, { evaluate, CompiledRule, evaluate_with_trace } from '@goplasmatic/datalogic-wasm';

// Full type inference for all exports
const result: string = evaluate('{"==": [1, 1]}', '{}', false);

Bundle Size

The WASM binary is approximately 50KB gzipped, making it suitable for web applications where performance is critical.

CDN Usage

For quick prototyping or simple pages, you can load directly from a CDN:

<script type="module">
  import init, { evaluate } from 'https://unpkg.com/@goplasmatic/datalogic-wasm@latest/web/datalogic_wasm.js';

  async function run() {
    await init();
    console.log(evaluate('{"==": [1, 1]}', '{}', false)); // "true"
  }

  run();
</script>

Next Steps

• Quick Start - Basic usage examples
• API Reference - Complete API documentation
• Framework Integration - React, Vue, and bundler setup

Quick Start

This guide covers the essential patterns for using JSONLogic in JavaScript/TypeScript.

Basic Evaluation

The simplest way to evaluate JSONLogic:

import init, { evaluate } from '@goplasmatic/datalogic-wasm';

// Initialize WASM (required for browser/bundler)
await init();

// Evaluate a simple expression
const result = evaluate('{"==": [1, 1]}', '{}', false);
console.log(result); // "true"

Working with Data

Pass data as a JSON string for variable resolution:

// Access nested data
const logic = '{"var": "user.age"}';
const data = '{"user": {"age": 25}}';
const result = evaluate(logic, data, false);
console.log(result); // "25"

// Multiple variables
const priceLogic = '{"*": [{"var": "price"}, {"var": "quantity"}]}';
const orderData = '{"price": 10.99, "quantity": 3}';
console.log(evaluate(priceLogic, orderData, false)); // "32.97"

Compiled Rules

For repeated evaluation of the same logic, use CompiledRule for better performance:

import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

await init();

// Compile once
const rule = new CompiledRule('{">=": [{"var": "age"}, 18]}', false);

// Evaluate many times with different data
console.log(rule.evaluate('{"age": 21}')); // "true"
console.log(rule.evaluate('{"age": 16}')); // "false"
console.log(rule.evaluate('{"age": 18}')); // "true"

Parsing Results

Results are returned as JSON strings. Parse them for use in your application:

const result = evaluate('{"+": [1, 2, 3]}', '{}', false);
const value = JSON.parse(result); // 6 (number)

// For complex results
const arrayResult = evaluate('{"map": [[1,2,3], {"+": [{"var": ""}, 10]}]}', '{}', false);
const array = JSON.parse(arrayResult); // [11, 12, 13]

Conditional Logic

Use if for branching:

const gradeLogic = JSON.stringify({
  "if": [
    { ">=": [{ "var": "score" }, 90] }, "A",
    { ">=": [{ "var": "score" }, 80] }, "B",
    { ">=": [{ "var": "score" }, 70] }, "C",
    { ">=": [{ "var": "score" }, 60] }, "D",
    "F"
  ]
});

const rule = new CompiledRule(gradeLogic, false);
console.log(JSON.parse(rule.evaluate('{"score": 85}'))); // "B"
console.log(JSON.parse(rule.evaluate('{"score": 42}'))); // "F"

Array Operations

Process arrays with map, filter, and reduce:

// Filter items
const filterLogic = JSON.stringify({
  "filter": [
    { "var": "items" },
    { ">": [{ "var": ".price" }, 20] }
  ]
});

const data = JSON.stringify({
  items: [
    { name: "Book", price: 15 },
    { name: "Phone", price: 299 },
    { name: "Pen", price: 5 },
    { name: "Headphones", price: 50 }
  ]
});

const result = JSON.parse(evaluate(filterLogic, data, false));
// [{ name: "Phone", price: 299 }, { name: "Headphones", price: 50 }]

Templating Mode

Enable templating for JSON templating:

const template = JSON.stringify({
  "user": {
    "fullName": { "cat": [{ "var": "firstName" }, " ", { "var": "lastName" }] },
    "isAdult": { ">=": [{ "var": "age" }, 18] }
  },
  "timestamp": { "now": [] }
});

const data = JSON.stringify({
  firstName: "Alice",
  lastName: "Smith",
  age: 25
});

// Third parameter = true enables templating mode
const result = JSON.parse(evaluate(template, data, true));
// {
//   "user": { "fullName": "Alice Smith", "isAdult": true },
//   "timestamp": "2024-01-15T10:30:00Z"
// }

Error Handling

Wrap evaluations in try-catch:

try {
  const result = evaluate('{"invalid": "json', '{}', false);
} catch (error) {
  console.error('Evaluation failed:', error);
}

Debugging

Use evaluate_with_trace for step-by-step debugging:

import init, { evaluate_with_trace } from '@goplasmatic/datalogic-wasm';

await init();

const trace = evaluate_with_trace(
  '{"and": [{"var": "a"}, {"var": "b"}]}',
  '{"a": true, "b": false}',
  false
);

const traceData = JSON.parse(trace);
console.log('Result:', traceData.result);
console.log('Steps:', traceData.steps);

Next Steps

• API Reference - Complete function documentation
• Framework Integration - React, Vue, and bundler setup

API Reference

Complete API documentation for the @goplasmatic/datalogic-wasm WebAssembly package.

Functions

init()

Initialize the WebAssembly module. Required before using any other functions in browser/bundler environments.

function init(input?: InitInput): Promise<InitOutput>;

Parameters:

• input (optional) - Custom WASM source (URL, Response, or BufferSource)

Returns: Promise that resolves when initialization is complete

Example:

import init from '@goplasmatic/datalogic-wasm';

// Standard initialization
await init();

// Custom WASM location
await init('/custom/path/datalogic_wasm_bg.wasm');

Note: Node.js does not require initialization.

evaluate()

Evaluate a JSONLogic expression against data.

function evaluate(logic: string, data: string, templating: boolean): string;

Parameters:

• logic - JSON string containing the JSONLogic expression
• data - JSON string containing the data context
• templating - Enable templating mode (multi-key objects compile to output-shaping templates with embedded JSONLogic)

Returns: JSON string containing the result

Throws: String error message if evaluation fails

Examples:

// Simple comparison
evaluate('{"==": [1, 1]}', '{}', false); // "true"

// Variable access
evaluate('{"var": "name"}', '{"name": "Alice"}', false); // "\"Alice\""

// Arithmetic
evaluate('{"+": [1, 2, 3]}', '{}', false); // "6"

// Array operations
evaluate('{"map": [[1,2,3], {"+": [{"var": ""}, 1]}]}', '{}', false); // "[2,3,4]"

// Templating mode
evaluate(
  '{"result": {"var": "x"}, "computed": {"+": [1, 2]}}',
  '{"x": 42}',
  true
); // '{"result":42,"computed":3}'

evaluateWithTrace()

Evaluate with detailed execution trace for debugging.

function evaluateWithTrace(logic: string, data: string, templating: boolean): string;

Parameters: Same as evaluate()

Returns: JSON string containing a TracedResult:

interface TracedResult {
  result: any;              // Evaluation result
  expression_tree: {        // Tree structure of the expression
    id: number;
    expression: string;
    children?: ExpressionNode[];
  };
  steps: Step[];            // Execution steps
}

interface Step {
  node_id: number;
  operator: string;
  input_values: any[];
  output_value: any;
  context: any;
}

The TracedResult JSON layout is the JavaScript-side wire shape and is stable across the v4 → v5 cutover. On the Rust side it is produced from a datalogic_rs::TracedRun<String> (see the Rust API reference).

Example:

const trace = evaluateWithTrace(
  '{"and": [true, {"var": "x"}]}',
  '{"x": false}',
  false
);

const data = JSON.parse(trace);
console.log(data.result);      // false
console.log(data.steps.length); // 3 (and, true literal, var lookup)

Classes

CompiledRule

Pre-compiled rule for efficient repeated evaluation.

Constructor

new CompiledRule(logic: string, templating: boolean)

Parameters:

• logic - JSON string containing the JSONLogic expression
• templating - Enable templating mode

Throws: If the logic is invalid JSON or contains compilation errors

Example:

const rule = new CompiledRule('{">=": [{"var": "age"}, 18]}', false);

Methods

evaluate(data: string): string

Evaluate the compiled rule against data.

evaluate(data: string): string;

Parameters:

• data - JSON string containing the data context

Returns: JSON string containing the result

Example:

const rule = new CompiledRule('{"+": [{"var": "a"}, {"var": "b"}]}', false);

rule.evaluate('{"a": 1, "b": 2}');  // "3"
rule.evaluate('{"a": 10, "b": 20}'); // "30"

Tracing a compiled rule: the WASM CompiledRule exposes evaluate only. For execution traces, call the standalone evaluateWithTrace(logic, data, templating) function — it recompiles per call but returns the full TracedResult shape.

Type Definitions

Input/Output Types

All functions accept and return JSON strings. Parse results for use:

// Input: Always JSON strings
const logic: string = JSON.stringify({ "==": [1, 1] });
const data: string = JSON.stringify({ x: 42 });

// Output: Always JSON strings
const result: string = evaluate(logic, data, false);
const parsed: boolean = JSON.parse(result); // true

Templating Mode

When templating is true:

• Unknown object keys become output fields
• Only recognized operators are evaluated
• Useful for JSON templating

// Without templating - "result" treated as unknown operator
evaluate('{"result": {"var": "x"}}', '{"x": 1}', false);
// Error or unexpected behavior

// With templating - "result" becomes output field
evaluate('{"result": {"var": "x"}}', '{"x": 1}', true);
// '{"result":1}'

Error Handling

All functions throw string errors on failure:

try {
  evaluate('{"invalid json', '{}', false);
} catch (error) {
  // error is a string describing the problem
  console.error('Failed:', error);
}

Common error types:

• JSON parse errors (invalid syntax)
• Unknown operator errors (when templating is off)
• Type errors (wrong argument types)
• Variable access errors (missing required data)

Performance Tips

1. Use CompiledRule for repeated evaluation:

   // Slow: recompiles each time
   for (const user of users) {
     evaluate(logic, JSON.stringify(user), false);
   }
   
   // Fast: compile once
   const rule = new CompiledRule(logic, false);
   for (const user of users) {
     rule.evaluate(JSON.stringify(user));
   }
   

2. Initialize once at startup:

   // Application entry point
   await init();
   // Now use evaluate/CompiledRule anywhere
   

3. Reuse CompiledRule instances:

   // Store compiled rules
   const rules = {
     isAdult: new CompiledRule('{">=": [{"var": "age"}, 18]}', false),
     isPremium: new CompiledRule('{"==": [{"var": "tier"}, "premium"]}', false),
   };
   

Framework Integration

This guide covers integration with popular JavaScript frameworks and build tools.

React

Basic Setup

import { useEffect, useState } from 'react';
import init, { evaluate, CompiledRule } from '@goplasmatic/datalogic-wasm';

function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    init().then(() => setReady(true));
  }, []);

  if (!ready) return <div>Loading...</div>;

  return <RuleEvaluator />;
}

function RuleEvaluator() {
  const result = evaluate('{"==": [1, 1]}', '{}', false);
  return <div>Result: {result}</div>;
}

Custom Hook

Create a reusable hook for JSONLogic evaluation:

import { useEffect, useState, useMemo } from 'react';
import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

// Initialize once at module level
let initPromise: Promise<void> | null = null;
function ensureInit() {
  if (!initPromise) {
    initPromise = init();
  }
  return initPromise;
}

export function useJsonLogic(logic: object, data: unknown) {
  const [ready, setReady] = useState(false);
  const [result, setResult] = useState<unknown>(null);
  const [error, setError] = useState<string | null>(null);

  const rule = useMemo(() => {
    if (!ready) return null;
    try {
      return new CompiledRule(JSON.stringify(logic), false);
    } catch (e) {
      setError(String(e));
      return null;
    }
  }, [logic, ready]);

  useEffect(() => {
    ensureInit().then(() => setReady(true));
  }, []);

  useEffect(() => {
    if (!rule) return;
    try {
      const res = rule.evaluate(JSON.stringify(data));
      setResult(JSON.parse(res));
      setError(null);
    } catch (e) {
      setError(String(e));
    }
  }, [rule, data]);

  return { result, error, ready };
}

Usage:

function FeatureFlag({ feature, user }) {
  const rule = { "and": [
    { "in": [feature, { "var": "enabledFeatures" }] },
    { ">=": [{ "var": "accountAge" }, 30] }
  ]};

  const { result, error, ready } = useJsonLogic(rule, user);

  if (!ready) return null;
  if (error) return <div>Error: {error}</div>;
  return result ? <NewFeature /> : <LegacyFeature />;
}

With React Query

import { useQuery } from '@tanstack/react-query';
import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

export function useCompiledRule(logic: object) {
  return useQuery({
    queryKey: ['compiled-rule', JSON.stringify(logic)],
    queryFn: async () => {
      await init();
      return new CompiledRule(JSON.stringify(logic), false);
    },
    staleTime: Infinity,
  });
}

Vue

Composition API

<script setup lang="ts">
import { ref, onMounted, computed } from 'vue';
import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

const ready = ref(false);
const data = ref({ age: 25 });

onMounted(async () => {
  await init();
  ready.value = true;
});

const rule = computed(() => {
  if (!ready.value) return null;
  return new CompiledRule('{">=": [{"var": "age"}, 18]}', false);
});

const isAdult = computed(() => {
  if (!rule.value) return null;
  return JSON.parse(rule.value.evaluate(JSON.stringify(data.value)));
});
</script>

<template>
  <div v-if="ready">
    Is Adult: {{ isAdult }}
  </div>
  <div v-else>Loading...</div>
</template>

Composable

// useJsonLogic.ts
import { ref, onMounted, watchEffect, Ref } from 'vue';
import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

let initialized = false;
let initPromise: Promise<void> | null = null;

export function useJsonLogic(logic: Ref<object>, data: Ref<unknown>) {
  const result = ref<unknown>(null);
  const error = ref<string | null>(null);
  const ready = ref(false);

  onMounted(async () => {
    if (!initialized) {
      if (!initPromise) initPromise = init();
      await initPromise;
      initialized = true;
    }
    ready.value = true;
  });

  watchEffect(() => {
    if (!ready.value) return;
    try {
      const rule = new CompiledRule(JSON.stringify(logic.value), false);
      result.value = JSON.parse(rule.evaluate(JSON.stringify(data.value)));
      error.value = null;
    } catch (e) {
      error.value = String(e);
    }
  });

  return { result, error, ready };
}

Node.js

Express Middleware

const express = require('express');
const { evaluate, CompiledRule } = require('@goplasmatic/datalogic-wasm');

const app = express();
app.use(express.json());

// Compile rules at startup
const rules = {
  canAccess: new CompiledRule(JSON.stringify({
    "and": [
      { "==": [{ "var": "role" }, "admin"] },
      { "var": "active" }
    ]
  }), false)
};

// Middleware
function authorize(ruleName) {
  return (req, res, next) => {
    const rule = rules[ruleName];
    if (!rule) return res.status(500).json({ error: 'Unknown rule' });

    const result = JSON.parse(rule.evaluate(JSON.stringify(req.user)));
    if (result) {
      next();
    } else {
      res.status(403).json({ error: 'Forbidden' });
    }
  };
}

app.get('/admin', authorize('canAccess'), (req, res) => {
  res.json({ message: 'Welcome, admin!' });
});

Rule Evaluation API

const { evaluate } = require('@goplasmatic/datalogic-wasm');

app.post('/api/evaluate', (req, res) => {
  const { logic, data, preserveStructure = false } = req.body;

  try {
    const result = evaluate(
      JSON.stringify(logic),
      JSON.stringify(data),
      preserveStructure
    );
    res.json({ result: JSON.parse(result) });
  } catch (error) {
    res.status(400).json({ error: String(error) });
  }
});

Bundler Configuration

Vite

WASM works out of the box with Vite:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  // No special configuration needed
});

Webpack 5

Enable async WASM:

// webpack.config.js
module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
};

Next.js

// next.config.js
module.exports = {
  webpack: (config) => {
    config.experiments = {
      ...config.experiments,
      asyncWebAssembly: true,
    };
    return config;
  },
};

For App Router, create a client component:

'use client';

import { useEffect, useState } from 'react';
import init, { evaluate } from '@goplasmatic/datalogic-wasm';

export function JsonLogicEvaluator({ logic, data }) {
  const [result, setResult] = useState(null);

  useEffect(() => {
    init().then(() => {
      const res = evaluate(JSON.stringify(logic), JSON.stringify(data), false);
      setResult(JSON.parse(res));
    });
  }, [logic, data]);

  return <div>{JSON.stringify(result)}</div>;
}

Browser (No Build Tools)

For simple pages without bundlers:

<!DOCTYPE html>
<html>
<head>
  <title>JSONLogic Demo</title>
</head>
<body>
  <div id="result"></div>

  <script type="module">
    import init, { evaluate } from 'https://unpkg.com/@goplasmatic/datalogic-wasm@latest/web/datalogic_wasm.js';

    async function run() {
      await init();

      const logic = JSON.stringify({ ">=": [{ "var": "age" }, 18] });
      const data = JSON.stringify({ age: 21 });
      const result = JSON.parse(evaluate(logic, data, false));

      document.getElementById('result').textContent =
        result ? 'Adult' : 'Minor';
    }

    run();
  </script>
</body>
</html>

Worker Threads

Web Worker

// worker.js
import init, { CompiledRule } from '@goplasmatic/datalogic-wasm';

let rule = null;

self.onmessage = async (e) => {
  if (e.data.type === 'init') {
    await init();
    rule = new CompiledRule(e.data.logic, false);
    self.postMessage({ type: 'ready' });
  } else if (e.data.type === 'evaluate') {
    const result = rule.evaluate(JSON.stringify(e.data.data));
    self.postMessage({ type: 'result', result: JSON.parse(result) });
  }
};

Node.js Worker Thread

const { Worker, isMainThread, parentPort } = require('worker_threads');
const { CompiledRule } = require('@goplasmatic/datalogic-wasm');

if (isMainThread) {
  const worker = new Worker(__filename);
  worker.postMessage({ logic: '{"==": [1, 1]}', data: {} });
  worker.on('message', (result) => console.log(result));
} else {
  parentPort.on('message', ({ logic, data }) => {
    const rule = new CompiledRule(JSON.stringify(logic), false);
    const result = JSON.parse(rule.evaluate(JSON.stringify(data)));
    parentPort.postMessage(result);
  });
}

Installation

The @goplasmatic/datalogic-ui package provides a React component for visualizing and debugging JSONLogic expressions as interactive flow diagrams.

Package Installation

# npm
npm install @goplasmatic/datalogic-ui @xyflow/react

# yarn
yarn add @goplasmatic/datalogic-ui @xyflow/react

# pnpm
pnpm add @goplasmatic/datalogic-ui @xyflow/react

Peer Dependencies

The package requires:

Note: The @goplasmatic/datalogic-wasm WASM package is bundled internally for evaluation.

CSS Setup

Import the required styles in your application entry point or component:

// React Flow base styles (required)
import '@xyflow/react/dist/style.css';

// DataLogicEditor styles (required)
import '@goplasmatic/datalogic-ui/styles.css';

Style Import Order

Import order matters. Always import React Flow styles before DataLogicEditor styles:

// Correct order
import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

// Then import components
import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

Minimal Example

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

function App() {
  return (
    <div style={{ width: '100%', height: '500px' }}>
      <DataLogicEditor
        value={{ "==": [{ "var": "x" }, 1] }}
      />
    </div>
  );
}

Container Requirements

The editor requires a container with defined dimensions:

// Option 1: Explicit dimensions
<div style={{ width: '100%', height: '500px' }}>
  <DataLogicEditor value={expression} />
</div>

// Option 2: CSS class
<div className="editor-container">
  <DataLogicEditor value={expression} />
</div>

// CSS
.editor-container {
  width: 100%;
  height: 100vh;
}

TypeScript Setup

Types are included in the package. Import types as needed:

import type {
  DataLogicEditorProps,
  DataLogicEditorMode,
  JsonLogicValue,
} from '@goplasmatic/datalogic-ui';

Bundler Notes

Vite

Works out of the box. No additional configuration needed.

Webpack

Ensure CSS loaders are configured:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};

Next.js

For App Router, use client components:

'use client';

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

export function LogicVisualizer({ expression }) {
  return <DataLogicEditor value={expression} />;
}

Next Steps

• Quick Start - Basic usage examples
• Modes - Visualize, debug, and edit modes
• Props & API - Complete props reference

Quick Start

This guide covers essential patterns for using the DataLogicEditor component.

Basic Visualization

Render a JSONLogic expression as a flow diagram:

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

function App() {
  const expression = {
    "and": [
      { ">": [{ "var": "age" }, 18] },
      { "==": [{ "var": "status" }, "active"] }
    ]
  };

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <DataLogicEditor value={expression} />
    </div>
  );
}

Debug Mode

Add evaluation results by providing data context:

function DebugExample() {
  const expression = {
    "if": [
      { ">=": [{ "var": "score" }, 90] }, "A",
      { ">=": [{ "var": "score" }, 80] }, "B",
      "C"
    ]
  };

  const userData = {
    score: 85
  };

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <DataLogicEditor
        value={expression}
        data={userData}
        mode="debug"
      />
    </div>
  );
}

In debug mode, each node displays its evaluated result, making it easy to trace how the final value was computed.

Dynamic Data

Update evaluation results by changing the data:

import { useState } from 'react';

function DynamicDebugger() {
  const [score, setScore] = useState(75);

  const expression = {
    "if": [
      { ">=": [{ "var": "score" }, 90] }, "A",
      { ">=": [{ "var": "score" }, 80] }, "B",
      { ">=": [{ "var": "score" }, 70] }, "C",
      "F"
    ]
  };

  return (
    <div>
      <div>
        <label>
          Score:
          <input
            type="range"
            min="0"
            max="100"
            value={score}
            onChange={(e) => setScore(Number(e.target.value))}
          />
          {score}
        </label>
      </div>

      <div style={{ width: '100%', height: '400px' }}>
        <DataLogicEditor
          value={expression}
          data={{ score }}
          mode="debug"
        />
      </div>
    </div>
  );
}

Complex Expressions

The editor handles complex nested expressions:

function ComplexExample() {
  const expression = {
    "and": [
      { "or": [
        { "==": [{ "var": "user.role" }, "admin"] },
        { "==": [{ "var": "user.role" }, "moderator"] }
      ]},
      { ">=": [{ "var": "user.accountAge" }, 30] },
      { "!": [{ "var": "user.banned" }] }
    ]
  };

  const data = {
    user: {
      role: "moderator",
      accountAge: 45,
      banned: false
    }
  };

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <DataLogicEditor
        value={expression}
        data={data}
        mode="debug"
      />
    </div>
  );
}

Array Operations

Visualize array operations like map, filter, and reduce:

function ArrayExample() {
  const expression = {
    "filter": [
      { "var": "items" },
      { ">": [{ "var": ".price" }, 20] }
    ]
  };

  const data = {
    items: [
      { name: "Book", price: 15 },
      { name: "Phone", price: 299 },
      { name: "Pen", price: 5 }
    ]
  };

  return (
    <div style={{ width: '100%', height: '400px' }}>
      <DataLogicEditor
        value={expression}
        data={data}
        mode="debug"
      />
    </div>
  );
}

Theme Support

The editor supports light and dark themes:

// Explicit theme
<DataLogicEditor
  value={expression}
  theme="dark"
/>

// System preference (default)
<DataLogicEditor value={expression} />

// Or set data-theme on a parent element
<div data-theme="dark">
  <DataLogicEditor value={expression} />
</div>

Handling Null/Empty Expressions

The editor gracefully handles null or undefined expressions:

function ConditionalEditor({ expression }) {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <DataLogicEditor
        value={expression}  // Can be null
      />
    </div>
  );
}

Styling Container

Add custom styling to the container:

<DataLogicEditor
  value={expression}
  className="my-custom-editor"
/>

// CSS
.my-custom-editor {
  border: 1px solid #ccc;
  border-radius: 8px;
}

Next Steps

• Modes - Detailed mode documentation
• Props & API - Complete props reference
• Customization - Theming and styling

Editor Modes

The DataLogicEditor supports three modes, each providing different levels of functionality.

Mode Overview

Visualize Mode (Default)

The default mode renders a static flow diagram of the JSONLogic expression.

<DataLogicEditor
  value={expression}
  mode="visualize"  // Optional, this is the default
/>

Use cases:

• Documentation and explanation
• Code review and understanding
• Static representation in reports

Features:

• Interactive pan and zoom
• Node highlighting on hover
• Tree-based automatic layout
• Color-coded operator categories

Debug Mode

Debug mode adds evaluation results to each node, showing how the expression evaluates against provided data.

<DataLogicEditor
  value={expression}
  data={contextData}
  mode="debug"
/>

Use cases:

• Understanding evaluation flow
• Debugging unexpected results
• Testing expressions with different inputs
• Learning JSONLogic

Features:

• All visualization features, plus:
• Evaluation results displayed on each node
• Step-by-step execution visibility
• Context values shown for variable nodes
• Highlighted execution path

Debug Mode Requirements

Debug mode requires the data prop. Without it, the component falls back to visualize mode:

// This will work in debug mode
<DataLogicEditor
  value={expression}
  data={{ x: 1 }}
  mode="debug"
/>

// This falls back to visualize mode (no data)
<DataLogicEditor
  value={expression}
  mode="debug"
/>

Tracing Execution

In debug mode, the component uses evaluate_with_trace internally to capture:

• The result of each sub-expression
• The order of evaluation
• Context values at each step
• Final computed result

Edit Mode (Coming Soon)

Edit mode will provide a full visual builder for creating and modifying JSONLogic expressions.

// Planned API
<DataLogicEditor
  value={expression}
  onChange={setExpression}
  data={contextData}  // Optional, for live preview
  mode="edit"
/>

Planned features:

• Drag-and-drop node creation
• Visual connection editing
• Operator palette
• Live evaluation preview
• Undo/redo support
• Expression validation

Note: Using mode="edit" currently renders the component in read-only mode. If data is provided, it shows debug evaluation. A console warning indicates this limitation.

Mode Comparison

Visual Differences

Performance Considerations

• Visualize mode is fastest - no evaluation overhead
• Debug mode runs evaluation on every data change
• Edit mode will include validation and preview costs

For large expressions or frequent data updates, consider debouncing:

import { useMemo } from 'react';
import { useDebouncedValue } from './hooks';

function DebugWithDebounce({ expression, data }) {
  const debouncedData = useDebouncedValue(data, 200);

  return (
    <DataLogicEditor
      value={expression}
      data={debouncedData}
      mode="debug"
    />
  );
}

Switching Modes

You can dynamically switch between modes:

function ModeToggle() {
  const [mode, setMode] = useState<'visualize' | 'debug'>('visualize');

  return (
    <div>
      <button onClick={() => setMode('visualize')}>Visualize</button>
      <button onClick={() => setMode('debug')}>Debug</button>

      <DataLogicEditor
        value={expression}
        data={mode === 'debug' ? data : undefined}
        mode={mode}
      />
    </div>
  );
}

Next Steps

• Props & API - Complete props reference
• Customization - Theming and styling

Props & API Reference

Complete reference for the DataLogicEditor component and related exports.

DataLogicEditor Props

Required Props

value

The JSONLogic expression to render.

value: JsonLogicValue | null

Accepts any valid JSONLogic expression or null for an empty state.

// Simple expression
<DataLogicEditor value={{ "==": [1, 1] }} />

// Complex expression
<DataLogicEditor value={{
  "and": [
    { ">=": [{ "var": "age" }, 18] },
    { "var": "active" }
  ]
}} />

// Null for empty state
<DataLogicEditor value={null} />

Optional Props

mode

The editor mode.

mode?: 'visualize' | 'debug' | 'edit'

Default: 'visualize'

<DataLogicEditor value={expr} mode="debug" />

data

Data context for evaluation (required for debug mode).

data?: unknown

<DataLogicEditor
  value={{ "var": "user.name" }}
  data={{ user: { name: "Alice" } }}
  mode="debug"
/>

onChange

Callback when expression changes (for future edit mode).

onChange?: (expression: JsonLogicValue | null) => void

// Future usage
<DataLogicEditor
  value={expression}
  onChange={setExpression}
  mode="edit"
/>

theme

Theme override.

theme?: 'light' | 'dark'

Default: System preference

<DataLogicEditor value={expr} theme="dark" />

className

Additional CSS class for the container.

className?: string

<DataLogicEditor value={expr} className="my-editor" />

Type Definitions

JsonLogicValue

The type for JSONLogic expressions:

type JsonLogicValue =
  | string
  | number
  | boolean
  | null
  | JsonLogicValue[]
  | { [operator: string]: JsonLogicValue };

DataLogicEditorMode

type DataLogicEditorMode = 'visualize' | 'debug' | 'edit';

DataLogicEditorProps

interface DataLogicEditorProps {
  value: JsonLogicValue | null;
  onChange?: (expression: JsonLogicValue | null) => void;
  data?: unknown;
  mode?: DataLogicEditorMode;
  theme?: 'light' | 'dark';
  className?: string;
}

LogicNode

Internal node type (for advanced customization):

interface LogicNode {
  id: string;
  type: string;
  position: { x: number; y: number };
  data: {
    label: string;
    category: OperatorCategory;
    value?: unknown;
    result?: unknown;
  };
}

LogicEdge

Internal edge type:

interface LogicEdge {
  id: string;
  source: string;
  target: string;
  sourceHandle?: string;
  targetHandle?: string;
}

OperatorCategory

type OperatorCategory =
  | 'logical'
  | 'comparison'
  | 'arithmetic'
  | 'string'
  | 'array'
  | 'control'
  | 'variable'
  | 'literal'
  | 'datetime'
  | 'misc';

Exports

Component

import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

Types

import type {
  DataLogicEditorProps,
  DataLogicEditorMode,
  JsonLogicValue,
  LogicNode,
  LogicEdge,
  OperatorCategory,
} from '@goplasmatic/datalogic-ui';

Constants

import { OPERATORS, CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

OPERATORS: Map of operator names to their metadata (category, label, etc.)

CATEGORY_COLORS: Color definitions for each operator category

Utilities

import { jsonLogicToNodes, applyTreeLayout } from '@goplasmatic/datalogic-ui';

jsonLogicToNodes: Convert JSONLogic expression to React Flow nodes/edges

const { nodes, edges } = jsonLogicToNodes(expression, traceData?);

applyTreeLayout: Apply dagre tree layout to nodes

const layoutedNodes = applyTreeLayout(nodes, edges, direction?);

Utility Functions

jsonLogicToNodes

Convert a JSONLogic expression to React Flow nodes and edges.

function jsonLogicToNodes(
  expression: JsonLogicValue,
  trace?: TraceData
): { nodes: LogicNode[]; edges: LogicEdge[] }

Parameters:

• expression - JSONLogic expression to convert
• trace - Optional trace data for debug mode

Returns: Object with nodes and edges arrays

Example:

import { jsonLogicToNodes } from '@goplasmatic/datalogic-ui';

const expr = { "==": [{ "var": "x" }, 1] };
const { nodes, edges } = jsonLogicToNodes(expr);

console.log(nodes);
// [
//   { id: '0', type: 'operator', data: { label: '==', category: 'comparison' }, ... },
//   { id: '1', type: 'variable', data: { label: 'x', category: 'variable' }, ... },
//   { id: '2', type: 'literal', data: { label: '1', category: 'literal' }, ... }
// ]

applyTreeLayout

Apply dagre-based tree layout to nodes.

function applyTreeLayout(
  nodes: LogicNode[],
  edges: LogicEdge[],
  direction?: 'TB' | 'LR'
): LogicNode[]

Parameters:

• nodes - Array of nodes
• edges - Array of edges
• direction - Layout direction (default: 'TB' for top-to-bottom)

Returns: Nodes with updated positions

Advanced Usage

Custom Node Rendering

For advanced customization, you can use the utilities to render with your own React Flow setup:

import { ReactFlow } from '@xyflow/react';
import { jsonLogicToNodes, applyTreeLayout } from '@goplasmatic/datalogic-ui';

function CustomEditor({ expression }) {
  const { nodes: rawNodes, edges } = jsonLogicToNodes(expression);
  const nodes = applyTreeLayout(rawNodes, edges);

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      nodeTypes={customNodeTypes}
      // Custom configuration...
    />
  );
}

Accessing Category Colors

import { CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

// Use in custom styling
const logicalColor = CATEGORY_COLORS.logical;  // e.g., '#4CAF50'

Next Steps

• Customization - Theming and styling options

Customization

This guide covers theming, styling, and advanced customization of the DataLogicEditor.

Theming

System Theme (Default)

By default, the editor detects system theme preference:

<DataLogicEditor value={expression} />

Explicit Theme

Override with the theme prop:

// Always dark
<DataLogicEditor value={expression} theme="dark" />

// Always light
<DataLogicEditor value={expression} theme="light" />

Parent-Based Theme

The component respects data-theme on parent elements:

<div data-theme="dark">
  <DataLogicEditor value={expression} />
</div>

Dynamic Theme Switching

function ThemedEditor() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <div>
      <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>
        Toggle Theme
      </button>
      <DataLogicEditor value={expression} theme={theme} />
    </div>
  );
}

CSS Customization

Container Styling

Use the className prop for container styling:

<DataLogicEditor value={expression} className="custom-editor" />

.custom-editor {
  border: 2px solid #3b82f6;
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

CSS Variables

Override CSS variables for global styling:

:root {
  /* Node colors by category */
  --datalogic-logical-bg: #4caf50;
  --datalogic-comparison-bg: #2196f3;
  --datalogic-arithmetic-bg: #ff9800;
  --datalogic-string-bg: #9c27b0;
  --datalogic-array-bg: #00bcd4;
  --datalogic-variable-bg: #607d8b;
  --datalogic-literal-bg: #795548;

  /* General theming */
  --datalogic-bg: #ffffff;
  --datalogic-text: #1a1a1a;
  --datalogic-border: #e5e7eb;
  --datalogic-node-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

[data-theme="dark"] {
  --datalogic-bg: #1a1a1a;
  --datalogic-text: #ffffff;
  --datalogic-border: #374151;
  --datalogic-node-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
}

Node Styling

Target specific node types:

/* All nodes */
.react-flow__node {
  font-family: 'Inter', sans-serif;
}

/* Operator nodes */
.react-flow__node-operator {
  border-width: 2px;
}

/* Variable nodes */
.react-flow__node-variable {
  font-style: italic;
}

/* Literal nodes */
.react-flow__node-literal {
  font-weight: bold;
}

Edge Styling

Customize connection lines:

.react-flow__edge-path {
  stroke: #6b7280;
  stroke-width: 2px;
}

.react-flow__edge.selected .react-flow__edge-path {
  stroke: #3b82f6;
}

Layout Customization

Container Dimensions

The editor requires explicit dimensions:

// Fixed height
<div style={{ height: '500px' }}>
  <DataLogicEditor value={expression} />
</div>

// Viewport height
<div style={{ height: '100vh' }}>
  <DataLogicEditor value={expression} />
</div>

// Flexbox
<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
  <header>...</header>
  <div style={{ flex: 1 }}>
    <DataLogicEditor value={expression} />
  </div>
</div>

Using Utilities

Custom Flow Rendering

For complete control, use the utility functions with your own React Flow instance:

import { ReactFlow, Background, Controls } from '@xyflow/react';
import { jsonLogicToNodes, applyTreeLayout, CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

function CustomEditor({ expression }) {
  const { nodes: rawNodes, edges } = jsonLogicToNodes(expression);
  const nodes = applyTreeLayout(rawNodes, edges);

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      fitView
      nodesDraggable={false}
      nodesConnectable={false}
    >
      <Background />
      <Controls />
    </ReactFlow>
  );
}

Custom Node Types

Create custom node components:

import { Handle, Position } from '@xyflow/react';
import { CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

function CustomOperatorNode({ data }) {
  const color = CATEGORY_COLORS[data.category];

  return (
    <div
      style={{
        background: color,
        padding: '12px 20px',
        borderRadius: '8px',
        color: 'white',
      }}
    >
      <Handle type="target" position={Position.Top} />
      <div>{data.label}</div>
      {data.result !== undefined && (
        <div style={{ fontSize: '0.75em', opacity: 0.8 }}>
          = {JSON.stringify(data.result)}
        </div>
      )}
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

const customNodeTypes = {
  operator: CustomOperatorNode,
  // ... other custom types
};

Category Colors

Access and customize category colors:

import { CATEGORY_COLORS } from '@goplasmatic/datalogic-ui';

// Default colors
console.log(CATEGORY_COLORS);
// {
//   logical: '#4CAF50',
//   comparison: '#2196F3',
//   arithmetic: '#FF9800',
//   string: '#9C27B0',
//   array: '#00BCD4',
//   control: '#F44336',
//   variable: '#607D8B',
//   literal: '#795548',
//   datetime: '#3F51B5',
//   misc: '#9E9E9E'
// }

// Use in custom components
function Legend() {
  return (
    <div>
      {Object.entries(CATEGORY_COLORS).map(([category, color]) => (
        <div key={category} style={{ display: 'flex', alignItems: 'center' }}>
          <span style={{ background: color, width: 16, height: 16 }} />
          <span>{category}</span>
        </div>
      ))}
    </div>
  );
}

Responsive Design

Make the editor responsive:

function ResponsiveEditor({ expression }) {
  return (
    <div className="editor-wrapper">
      <DataLogicEditor value={expression} />
    </div>
  );
}

.editor-wrapper {
  width: 100%;
  height: 300px;
}

@media (min-width: 768px) {
  .editor-wrapper {
    height: 500px;
  }
}

@media (min-width: 1024px) {
  .editor-wrapper {
    height: 700px;
  }
}

Performance Tips

Memoization

Memoize expression objects to prevent unnecessary re-renders:

import { useMemo } from 'react';

function OptimizedEditor({ config }) {
  const expression = useMemo(() => ({
    "and": [
      { ">=": [{ "var": "age" }, config.minAge] },
      { "var": "active" }
    ]
  }), [config.minAge]);

  return <DataLogicEditor value={expression} />;
}

Debounced Data Updates

For frequently changing data in debug mode:

import { useDeferredValue } from 'react';

function DebugWithDeferred({ expression, data }) {
  const deferredData = useDeferredValue(data);

  return (
    <DataLogicEditor
      value={expression}
      data={deferredData}
      mode="debug"
    />
  );
}

Custom Operators

Extend datalogic-rs with your own operators to implement domain-specific logic.

v5 changes: Custom operators receive pre-evaluated &DataValue<'a> arguments and return arena-allocated values. The old “args are unevaluated; call evaluator.evaluate()” model is gone, and so is the Evaluator trait. The trait is named CustomOperator, and registration is builder-only.

The CustomOperator Trait

#![allow(unused)]
fn main() {
use bumpalo::Bump;
use datalogic_rs::operator::EvalContext;
use datalogic_rs::{CustomOperator, DataValue, Result};

pub trait CustomOperator: Send + Sync {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        ctx: &mut EvalContext<'_, 'a>,
        arena: &'a Bump,
    ) -> Result<&'a DataValue<'a>>;
}
}

The return value must live in the arena (or be a preallocated singleton like DataValue::Null). Never return a stack reference.

Basic Custom Operator

#![allow(unused)]
fn main() {
use bumpalo::Bump;
use datalogic_rs::operator::EvalContext;
use datalogic_rs::{CustomOperator, DataValue, Engine, Error, Result};

struct DoubleOperator;

impl CustomOperator for DoubleOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a Bump,
    ) -> Result<&'a DataValue<'a>> {
        let n = args
            .first()
            .and_then(|v| v.as_f64())
            .ok_or_else(|| Error::invalid_arguments("expected number"))?;
        Ok(arena.alloc(DataValue::from_f64(n * 2.0)))
    }
}
}

Registering Custom Operators

Operator registration is builder-only. Once build() is called the engine’s operator set is frozen:

#![allow(unused)]
fn main() {
let engine = Engine::builder()
    .add_operator("double", DoubleOperator)
    .build();

let result = engine.eval_str(r#"{"double": 21}"#, r#"{}"#).unwrap();
assert_eq!(result, "42");
}

add_operator accepts both typed operators (T: CustomOperator + 'static) and pre-boxed trait objects (Box<dyn CustomOperator>) — the box itself implements CustomOperator by delegating to its contents, so the same entry point covers both shapes.

The builder is consumed by .build(); the operator set is then frozen. There is no remove_operator in v5 — rebuild the builder if you need a different set.

Reading Argument Types

DataValue<'a> is the arena-resident value tree, re-exported from the datavalue crate. Common accessors:

#![allow(unused)]
fn main() {
match args[0] {
    DataValue::Null => { /* ... */ }
    DataValue::Bool(b) => { /* ... */ }
    DataValue::Number(_) => {
        let n: Option<f64> = args[0].as_f64();
        let i: Option<i64> = args[0].as_i64();
    }
    DataValue::String(s) => { /* &str */ }
    DataValue::Array(items) => { /* &[DataValue<'a>] */ }
    DataValue::Object(pairs) => { /* &[(&str, DataValue<'a>)] */ }
    _ => {}
}
}

Example: Average Operator

#![allow(unused)]
fn main() {
use bumpalo::Bump;
use datalogic_rs::operator::EvalContext;
use datalogic_rs::{CustomOperator, DataValue, Engine, Result};

struct AverageOperator;

impl CustomOperator for AverageOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a Bump,
    ) -> Result<&'a DataValue<'a>> {
        let mut numbers: Vec<f64> = Vec::new();
        for av in args {
            match av {
                DataValue::Array(items) => {
                    for it in items.iter() {
                        if let Some(n) = it.as_f64() {
                            numbers.push(n);
                        }
                    }
                }
                other => {
                    if let Some(n) = other.as_f64() {
                        numbers.push(n);
                    }
                }
            }
        }

        if numbers.is_empty() {
            return Ok(arena.alloc(DataValue::Null));
        }

        let avg = numbers.iter().sum::<f64>() / numbers.len() as f64;
        Ok(arena.alloc(DataValue::from_f64(avg)))
    }
}

let engine = Engine::builder().add_operator("avg", AverageOperator).build();

let result = engine.eval_str(
    r#"{"avg": {"var": "scores"}}"#,
    r#"{"scores": [80, 90, 85, 95]}"#,
).unwrap();
assert_eq!(result, "87.5");
}

Example: Range Check Operator

#![allow(unused)]
fn main() {
struct InRangeOperator;

impl CustomOperator for InRangeOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        if args.len() != 3 {
            return Err(Error::invalid_arguments(
                "in_range requires 3 arguments: value, min, max",
            ));
        }
        let v = args[0].as_f64()
            .ok_or_else(|| Error::invalid_arguments("value must be a number"))?;
        let lo = args[1].as_f64()
            .ok_or_else(|| Error::invalid_arguments("min must be a number"))?;
        let hi = args[2].as_f64()
            .ok_or_else(|| Error::invalid_arguments("max must be a number"))?;
        Ok(arena.alloc(DataValue::Bool(v >= lo && v <= hi)))
    }
}

let engine = Engine::builder()
    .add_operator("in_range", InRangeOperator)
    .build();
}

Example: String Formatting Operator

#![allow(unused)]
fn main() {
struct FormatOperator;

impl CustomOperator for FormatOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        let template = args
            .first()
            .and_then(|v| v.as_str())
            .ok_or_else(|| Error::invalid_arguments("expected string template"))?;

        let mut out = template.to_string();
        for av in args.iter().skip(1) {
            if let Some(pos) = out.find("{}") {
                let replacement = match av {
                    DataValue::String(s) => (*s).to_string(),
                    DataValue::Bool(b) => b.to_string(),
                    DataValue::Null => "null".to_string(),
                    DataValue::Number(_) => av.as_f64()
                        .map(|n| n.to_string())
                        .unwrap_or_default(),
                    _ => "<value>".to_string(),
                };
                out.replace_range(pos..pos + 2, &replacement);
            }
        }

        // Allocate the rendered string in the arena and wrap it.
        let s = arena.alloc_str(&out);
        Ok(arena.alloc(DataValue::String(s)))
    }
}

let engine = Engine::builder()
    .add_operator("format", FormatOperator)
    .build();

let r = engine.eval_str(
    r#"{"format": ["Hello, {}! You have {} messages.", {"var": "name"}, {"var": "count"}]}"#,
    r#"{"name": "Alice", "count": 5}"#,
).unwrap();
// "Hello, Alice! You have 5 messages."
}

Thread Safety Requirements

CustomOperator is Send + Sync. For shared mutable state, use the usual synchronisation primitives:

#![allow(unused)]
fn main() {
use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};

struct CounterOperator { counter: Arc<AtomicUsize> }

impl CustomOperator for CounterOperator {
    fn evaluate<'a>(
        &self,
        _args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        let count = self.counter.fetch_add(1, Ordering::SeqCst) as i64;
        Ok(arena.alloc(DataValue::from_i64(count)))
    }
}
}

Error Handling

Return appropriate errors for invalid inputs:

#![allow(unused)]
fn main() {
impl CustomOperator for MyOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        if args.is_empty() {
            return Err(Error::invalid_arguments(
                "myop requires at least one argument",
            ));
        }

        let num = args[0].as_f64().ok_or_else(|| {
            Error::type_error(format!("expected number, got {}", value_type_name(args[0])))
        })?;

        if num < 0.0 {
            return Err(Error::custom_message("value must be non-negative"));
        }

        Ok(arena.alloc(DataValue::from_f64(num.sqrt())))
    }
}

fn value_type_name(v: &DataValue<'_>) -> &'static str {
    match v {
        DataValue::Null => "null",
        DataValue::Bool(_) => "boolean",
        DataValue::Number(_) => "number",
        DataValue::String(_) => "string",
        DataValue::Array(_) => "array",
        DataValue::Object(_) => "object",
        _ => "other",
    }
}
}

The Error type is structured: tag() returns a stable variant tag, and the operator / path fields are populated automatically by the engine when a custom operator returns an error.

To wrap a foreign error type into Error, use Error::wrap:

#![allow(unused)]
fn main() {
"not_a_number".parse::<i32>().map_err(Error::wrap)?;
// `error.source()` returns the original `ParseIntError`.
}

Best Practices

1. Validate argument count and types early.
2. Allocate results in the arena (arena.alloc(...) / arena.alloc_str(...)).
3. Return meaningful errors — Error::invalid_arguments, Error::type_error, Error::custom_message, Error::wrap.
4. Keep operators focused — one responsibility per operator.
5. Use Arc for shared configuration to maintain Send + Sync.
6. Test with literals, variables, and nested expressions — the engine evaluates each before calling you.

Configuration

Customize evaluation behavior with EvaluationConfig and the EngineBuilder.

Creating a Configured Engine

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig, NanHandling};

// Default configuration
let engine = Engine::new();

// Custom configuration
let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue,
    ..Default::default()
};
let engine = Engine::builder().with_config(config).build();
}

v5 dropped the inherent Engine::with_config / with_preserve_structure / with_config_and_structure constructors — use the builder. There is no compatibility shim. See the Migration Guide for the v4 → v5 mapping.

Configuration Options

EvaluationConfig is a plain struct — set fields directly with struct update syntax:

#![allow(unused)]
fn main() {
use datalogic_rs::{EvaluationConfig, NanHandling, DivisionByZeroHandling};

let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue,
    division_by_zero: DivisionByZeroHandling::ReturnNull,
    loose_equality_errors: false,
    ..Default::default()
};
}

NaN Handling

Control how non-numeric values are handled in arithmetic operations.

#![allow(unused)]
fn main() {
use datalogic_rs::{EvaluationConfig, NanHandling};

// ThrowError (default), IgnoreValue, CoerceToZero, ReturnNull
let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue,
    ..Default::default()
};
}

Behavior comparison for {"+": [1, "text", 2]}:

Division by Zero

#![allow(unused)]
fn main() {
use datalogic_rs::{EvaluationConfig, DivisionByZeroHandling};

// ReturnSaturated (default), ThrowError, ReturnNull, ReturnInfinity
let config = EvaluationConfig {
    division_by_zero: DivisionByZeroHandling::ThrowError,
    ..Default::default()
};
}

Behavior comparison for {"/": [10, 0]}:

Truthiness Evaluation

#![allow(unused)]
fn main() {
use std::sync::Arc;
use datalogic_rs::{EvaluationConfig, TruthyEvaluator};
use datalogic_rs::datavalue::OwnedDataValue;

// JavaScript (default), Python, StrictBoolean, Custom
let config = EvaluationConfig {
    truthy_evaluator: TruthyEvaluator::Python,
    ..Default::default()
};

// Custom truthy: receives an OwnedDataValue (no serde_json required)
let custom = Arc::new(|value: &OwnedDataValue| -> bool {
    value.as_f64().map_or(false, |n| n > 0.0)
});
let config = EvaluationConfig {
    truthy_evaluator: TruthyEvaluator::Custom(custom),
    ..Default::default()
};
}

v5 change: TruthyEvaluator::Custom now takes Arc<dyn Fn(&OwnedDataValue) -> bool + Send + Sync> (the canonical owned value type). v4 used &serde_json::Value.

Truthiness comparison:

Loose Equality Errors

Control whether loose equality (==) raises errors for incompatible types.

#![allow(unused)]
fn main() {
let config = EvaluationConfig {
    loose_equality_errors: true,   // default
    ..Default::default()
};
}

Numeric Coercion

#![allow(unused)]
fn main() {
use datalogic_rs::{EvaluationConfig, NumericCoercionConfig};

let config = EvaluationConfig {
    numeric_coercion: NumericCoercionConfig {
        empty_string_to_zero: false,
        null_to_zero: false,
        bool_to_number: false,
        reject_non_numeric: true,
        undefined_to_zero: false,
    },
    ..Default::default()
};
}

Configuration Presets

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig};

// Lenient arithmetic — IgnoreValue + ReturnNull divide-by-zero
let engine = Engine::builder()
    .with_config(EvaluationConfig::safe_arithmetic())
    .build();

// Strict — errors for any type mismatch and no numeric coercion
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .build();
}

Combining with Templating Mode

Use both configuration and templating mode (requires feature = "templating"):

#![allow(unused)]
fn main() {
let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::CoerceToZero,
    ..Default::default()
};

let engine = Engine::builder()
    .with_config(config)
    .with_templating(true)
    .build();
}

Configuration Examples

Lenient Data Processing

#![allow(unused)]
fn main() {
let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue,
    division_by_zero: DivisionByZeroHandling::ReturnNull,
    ..Default::default()
};

let engine = Engine::builder().with_config(config).build();

let r = engine.eval_str(
    r#"{"+": [1, "not a number", null, 2]}"#,
    r#"{}"#,
).unwrap();
// "3" (ignores non-numeric values)
}

Strict Validation

#![allow(unused)]
fn main() {
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .build();

let result = engine.eval_str(r#"{"+": [1, "2"]}"#, r#"{}"#);
// Err(...) — strict mode does not coerce "2" to a number
}

Custom Business Logic Truthiness

#![allow(unused)]
fn main() {
use std::sync::Arc;
use datalogic_rs::datavalue::OwnedDataValue;

let custom_truthy = Arc::new(|value: &OwnedDataValue| -> bool {
    match value {
        OwnedDataValue::Bool(b) => *b,
        OwnedDataValue::Number(_) => value.as_f64().map_or(false, |n| n > 0.0),
        OwnedDataValue::String(s) => !s.is_empty(),
        _ => false,
    }
});

let config = EvaluationConfig {
    truthy_evaluator: TruthyEvaluator::Custom(custom_truthy),
    ..Default::default()
};

let engine = Engine::builder().with_config(config).build();
// {"if": [0,  "yes", "no"]}  ⇒ "no"
// {"if": [-5, "yes", "no"]}  ⇒ "no"
// {"if": [1,  "yes", "no"]}  ⇒ "yes"
}

Structured Objects (Templating)

Use JSONLogic as a templating engine with templating mode.

Requires feature = "templating". The mode is off by default.

Enabling Structure Preservation

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

// Enable templating mode
let engine = Engine::builder().with_templating(true).build();

// Combine with custom configuration
let engine = Engine::builder()
    .with_config(my_config)
    .with_templating(true)
    .build();
}

How It Works

In normal mode, unknown keys in a JSON object are treated as errors (or as custom operators when one is registered). With structure preservation enabled, unknown keys become literal output fields.

Normal mode:

{ "user": { "var": "name" } }
// Error: "user" is not a known operator

Structure preservation mode:

{ "user": { "var": "name" } }
// Result: { "user": "Alice" }

Basic Templating

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

let engine = Engine::builder().with_templating(true).build();

let template = r#"{
    "greeting": {"cat": ["Hello, ", {"var": "name"}, "!"]},
    "isAdmin": {"==": [{"var": "role"}, "admin"]}
}"#;
let data = r#"{"name": "Alice", "role": "admin"}"#;

let result = engine.eval_str(template, data).unwrap();
// {"greeting":"Hello, Alice!","isAdmin":true}
}

Nested Structures

Structure preservation works at any depth:

#![allow(unused)]
fn main() {
let template = r#"{
    "user": {
        "profile": {
            "displayName": {"var": "firstName"},
            "email": {"var": "userEmail"},
            "verified": true
        },
        "settings": {
            "theme": {"??": [{"var": "preferredTheme"}, "light"]},
            "notifications": {"var": "notificationsEnabled"}
        }
    },
    "metadata": {
        "version": "1.0"
    }
}"#;

let data = r#"{
    "firstName": "Bob",
    "userEmail": "bob@example.com",
    "notificationsEnabled": true
}"#;

let result = engine.eval_str(template, data).unwrap();
}

Arrays in Templates

Arrays are processed element by element:

#![allow(unused)]
fn main() {
let template = r#"{
    "items": [
        {"name": "Item 1", "price": {"var": "price1"}},
        {"name": "Item 2", "price": {"var": "price2"}}
    ],
    "total": {"+": [{"var": "price1"}, {"var": "price2"}]}
}"#;

let data = r#"{"price1": 10, "price2": 20}"#;

let result = engine.eval_str(template, data).unwrap();
}

Dynamic Arrays with Map

Generate arrays dynamically using map:

#![allow(unused)]
fn main() {
let template = r#"{
    "users": {
        "map": [
            {"var": "userList"},
            {
                "id": {"var": ".id"},
                "name": {"var": ".name"},
                "isActive": {"var": ".active"}
            }
        ]
    }
}"#;

let data = r#"{
    "userList": [
        {"id": 1, "name": "Alice", "active": true},
        {"id": 2, "name": "Bob", "active": false}
    ]
}"#;

let result = engine.eval_str(template, data).unwrap();
}

The preserve Operator Was Removed

In v4 there was an explicit preserve operator that wrapped a value to prevent further evaluation. v5 removed it. Wrap-as-output is exactly what templating mode already does for objects, and literal scalars / arrays already pass through inline. If you need to emit a JSON object verbatim from a rule, enable with_templating(true) and write the object directly.

Use Cases

API Response Transformation

#![allow(unused)]
fn main() {
let template = r#"{
    "success": true,
    "data": {
        "user": {
            "id": {"var": "userId"},
            "profile": {
                "name": {"cat": [{"var": "firstName"}, " ", {"var": "lastName"}]},
                "avatar": {"cat": ["https://cdn.example.com/", {"var": "avatarId"}, ".jpg"]}
            }
        }
    }
}"#;
}

Document Generation

#![allow(unused)]
fn main() {
let template = r#"{
    "invoice": {
        "number": {"cat": ["INV-", {"var": "invoiceId"}]},
        "customer": {
            "name": {"var": "customerName"},
            "address": {"var": "customerAddress"}
        },
        "items": {"var": "lineItems"},
        "total": {
            "reduce": [
                {"var": "lineItems"},
                {"+": [{"var": "accumulator"}, {"var": "current.amount"}]},
                0
            ]
        }
    }
}"#;
}

Configuration Templating

#![allow(unused)]
fn main() {
let template = r#"{
    "database": {
        "host": {"??": [{"var": "DB_HOST"}, "localhost"]},
        "port": {"??": [{"var": "DB_PORT"}, 5432]},
        "name": {"var": "DB_NAME"},
        "ssl": {"==": [{"var": "ENV"}, "production"]}
    },
    "cache": {
        "enabled": {"var": "CACHE_ENABLED"},
        "ttl": {"if": [
            {"==": [{"var": "ENV"}, "development"]},
            60,
            3600
        ]}
    }
}"#;
}

Dynamic Forms

#![allow(unused)]
fn main() {
let template = r#"{
    "form": {
        "title": {"var": "formTitle"},
        "fields": {
            "map": [
                {"var": "fieldDefinitions"},
                {
                    "name": {"var": ".name"},
                    "type": {"var": ".type"},
                    "required": {"var": ".required"},
                    "label": {"cat": [{"var": ".name"}, {"if": [{"var": ".required"}, " *", ""]}]}
                }
            ]
        }
    }
}"#;
}

Mixing Operators and Structure

You can mix operators and structure freely:

#![allow(unused)]
fn main() {
let template = r#"{
    "type": "response",
    "version": "2.0",

    "status": {"if": [
        {"var": "success"},
        "ok",
        "error"
    ]},

    "data": {"if": [
        {"var": "success"},
        {
            "result": {"var": "data"},
            "count": {"length": {"var": "data"}}
        },
        {
            "error": {"var": "errorMessage"},
            "code": {"var": "errorCode"}
        }
    ]}
}"#;
}

Thread Safety

datalogic-rs is designed for thread-safe, concurrent evaluation.

Thread-Safe Design

Logic is Send + Sync

Logic (the v5 name for CompiledLogic) is Send + Sync. v5 does not auto-wrap it in Arc — wrap it yourself when you want cheap cross-thread sharing, or use Engine::compile_arc to do it in one step:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;
use std::sync::Arc;

let engine = Engine::new();

// Manual:
let compiled = Arc::new(
    engine.compile(r#"{">": [{"var": "x"}, 10]}"#).unwrap(),
);

// Or in one step (equivalent to `Arc::new(engine.compile(rule)?)`):
let compiled = engine.compile_arc(r#"{">": [{"var": "x"}, 10]}"#).unwrap();

// Cloning the Arc is cheap — just bumps the refcount.
let compiled_clone = Arc::clone(&compiled);
}

Engine itself is also Send + Sync once built, so wrap it in Arc the same way when sharing across threads.

Sharing Across Threads

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;
use std::sync::Arc;
use std::thread;

let engine = Arc::new(Engine::new());
let compiled = engine.compile_arc(r#"{"*": [{"var": "x"}, 2]}"#).unwrap();

let handles: Vec<_> = (0..4).map(|i| {
    let engine = Arc::clone(&engine);
    let compiled = Arc::clone(&compiled);

    thread::spawn(move || {
        let mut session = engine.session();
        session
            .eval_str(&compiled, &format!(r#"{{"x": {}}}"#, i))
            .unwrap()
    })
}).collect();

for handle in handles {
    println!("{}", handle.join().unwrap());
}
}

Async Runtime Integration

With Tokio

Evaluation is CPU-bound — use spawn_blocking to keep async runtimes responsive:

use datalogic_rs::{Engine, Logic};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let engine = Arc::new(Engine::new());
    let compiled = engine.compile_arc(r#"{"+": [{"var": "a"}, {"var": "b"}]}"#).unwrap();

    let tasks: Vec<_> = (0..10).map(|i| {
        let engine = Arc::clone(&engine);
        let compiled = Arc::clone(&compiled);

        tokio::task::spawn_blocking(move || {
            let mut session = engine.session();
            let payload = format!(r#"{{"a": {}, "b": {}}}"#, i, i * 2);
            session.eval_str(&compiled, &payload)
        })
    }).collect();

    for task in tasks {
        let result = task.await.unwrap().unwrap();
        println!("{}", result);
    }
}

Thread Pool Pattern

For high-throughput scenarios, use a thread pool — each worker keeps its own Session so the arena is reused across calls without contention:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;
use rayon::prelude::*;
use std::sync::Arc;

let engine = Arc::new(Engine::new());
let compiled = engine
    .compile_arc(r#"{"filter": [{"var": "items"}, {">": [{"var": ".value"}, 50]}]}"#)
    .unwrap();

let datasets: Vec<String> = (0..1000)
    .map(|i| format!(r#"{{"items": [{{"value": {}}}, {{"value": {}}}]}}"#, i % 100, (i + 1) % 100))
    .collect();

let results: Vec<_> = datasets
    .par_iter()
    .map_init(
        || engine.session(),
        |session, data| {
            let r = session.eval_str(&compiled, data);
            session.reset();
            r
        },
    )
    .collect();
}

Tip: Session does not auto-reset. Call session.reset() between batches (as above) to keep peak memory tracking the largest single evaluation rather than the lifetime sum.

Shared Engine vs Per-Thread Engine

Shared Engine (Recommended)

Build the engine once with all custom operators, then share via Arc:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use datalogic_rs::Engine;

let engine = Arc::new(
    Engine::builder()
        .add_operator("custom", MyOperator)
        .build(),
);

for _ in 0..4 {
    let engine = Arc::clone(&engine);
    std::thread::spawn(move || {
        let mut session = engine.session();
        // Use shared engine.
    });
}
}

Per-Thread Engine

Use when you genuinely need thread-local engine state:

#![allow(unused)]
fn main() {
thread_local! {
    static ENGINE: datalogic_rs::Engine = datalogic_rs::Engine::new();
}

ENGINE.with(|engine| {
    let compiled = engine.compile(r#"{"==": [1, 1]}"#).unwrap();
    let mut session = engine.session();
    session.eval_str(&compiled, r#"{}"#)
});
}

Custom Operator Thread Safety

CustomOperator is Send + Sync. For shared mutable state, use the usual synchronisation primitives:

#![allow(unused)]
fn main() {
use std::sync::{Arc, atomic::{AtomicUsize, Ordering}};
use datalogic_rs::{CustomOperator, DataValue, Engine, Result};
use datalogic_rs::operator::EvalContext;

struct CounterOperator {
    counter: Arc<AtomicUsize>,
}

impl CustomOperator for CounterOperator {
    fn evaluate<'a>(
        &self,
        _args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        let count = self.counter.fetch_add(1, Ordering::SeqCst) as i64;
        Ok(arena.alloc(DataValue::from_i64(count)))
    }
}

let counter = Arc::new(AtomicUsize::new(0));
let engine = Engine::builder()
    .add_operator("count", CounterOperator { counter: Arc::clone(&counter) })
    .build();
}

Performance Considerations

Compile Once, Evaluate Many

#![allow(unused)]
fn main() {
// Good
let compiled = engine.compile(rule).unwrap();
let mut session = engine.session();
for data in datasets {
    session.eval_str(&compiled, data)?;
    session.reset();
}

// Bad — recompiles every iteration
for data in datasets {
    let compiled = engine.compile(rule).unwrap();
    engine.eval_str(rule, data)?;
}
}

Reuse the Arena

Session reuses one bumpalo::Bump across calls; the caller calls session.reset() between batches so peak memory tracks the largest single evaluation rather than the sum. For zero-copy &DataValue<'a> results, manage the bumpalo::Bump yourself and call Engine::evaluate directly.

Short-Circuit Evaluation

and, or, if, ?:, and ?? short-circuit. Order conditions so that the cheapest / most-likely-to-decide ones come first.

Error Handling in Threads

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, Error};
use std::sync::Arc;
use std::thread;

let engine = Arc::new(Engine::new());
let compiled = engine.compile_arc(r#"{"+": [1, 1]}"#).unwrap();

let handles: Vec<_> = (0..4).map(|_| {
    let engine = Arc::clone(&engine);
    let compiled = Arc::clone(&compiled);
    thread::spawn(move || -> Result<String, Error> {
        let mut session = engine.session();
        session.eval_str(&compiled, r#"{}"#)
    })
}).collect();

for h in handles {
    match h.join().expect("thread panicked") {
        Ok(value) => println!("{}", value),
        Err(e) => eprintln!("error: {} (operator: {:?}, path: {:?})", e, e.operator, e.path),
    }
}
}

API Reference

Core types and methods in datalogic-rs v5.

Public surface at a glance

v5 exposes five evaluation tiers, in order of caller control. Pick by use case, not by curiosity — most callers want Tier 0 for ad-hoc work or Tier 2 for repeated evaluation.

The same tier model is exposed in every binding — see each binding’s README for the language-idiomatic entry points.

Module-level helpers

For the simplest cases, skip the engine entirely:

#![allow(unused)]
fn main() {
let result = datalogic_rs::eval_str(
    r#"{"==": [{"var": "x"}, 1]}"#,
    r#"{"x": 1}"#,
).unwrap();
assert_eq!(result, "true");
}

#![allow(unused)]
fn main() {
pub fn compile<R: IntoLogic>(rule: R) -> Result<Logic>;
pub fn eval<R, D>(rule: R, data: D) -> Result<OwnedDataValue>;
pub fn eval_str<R, D>(rule: R, data: D) -> Result<String>;

#[cfg(feature = "serde_json")]
pub fn eval_into<T, R, D>(rule: R, data: D) -> Result<T>;
}

These delegate to a shared default engine (lazy OnceLock<Engine>). Escalate to a real Engine when you need custom operators, a non-default config, templating, or a long-lived Session.

Engine

The configured engine. Compiles rules and evaluates them.

Creating an Engine

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig};

// Default engine.
let engine = Engine::new();

// Builder — set config, enable templating, register custom operators.
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .with_templating(true)           // requires feature = "templating"
    .add_operator("my_op", MyOperator)
    .with_constant_folding(true)     // default; pass false to keep every operator visible in the compiled tree
    .build();
}

v5 makes operator registration builder-only. The Engine produced by build() has a frozen operator set.

Methods

compile

Compile a JSONLogic rule into reusable Logic.

#![allow(unused)]
fn main() {
pub fn compile<R: IntoLogic>(&self, rule: R) -> Result<Logic>;
pub fn compile_arc<R: IntoLogic>(&self, rule: R) -> Result<Arc<Logic>>;
}

R: IntoLogic accepts &str (JSON-parsed), &String, &OwnedDataValue / OwnedDataValue, and &serde_json::Value (gated on feature = "serde_json"). Use compile_arc for the dominant cross-thread sharing pattern (equivalent to Arc::new(engine.compile(rule)?)).

eval / eval_str / eval_into (one-shot)

Engine-owned arena per call. The differences are only in the result type:

#![allow(unused)]
fn main() {
pub fn eval<R, D>(&self, rule: R, data: D) -> Result<OwnedDataValue>;
pub fn eval_str<R, D>(&self, rule: R, data: D) -> Result<String>;

#[cfg(feature = "serde_json")]
pub fn eval_into<T, R, D>(&self, rule: R, data: D) -> Result<T>;
}

R: IntoLogic and D: OwnedInput — data accepts &str, String, &OwnedDataValue / OwnedDataValue, and &serde_json::Value (gated on serde_json). For eval_into, T: DeserializeOwned; the typical choices are serde_json::Value (JSON-shaped boundary) or your own domain struct.

#![allow(unused)]
fn main() {
let result = engine.eval_str(
    r#"{"+": [{"var": "x"}, 1]}"#,
    r#"{"x": 41}"#,
)?;
assert_eq!(result, "42");

let value: serde_json::Value = engine.eval_into(
    r#"{"+": [{"var": "x"}, 1]}"#,
    r#"{"x": 41}"#,
)?;
}

evaluate (raw tier)

Hot-path evaluation against arena-resident data. The caller owns the bumpalo::Bump; the result borrows from it.

#![allow(unused)]
fn main() {
pub fn evaluate<'a, D: EvalInput<'a>>(
    &self,
    compiled: &'a Logic,
    data: D,
    arena: &'a bumpalo::Bump,
) -> Result<&'a DataValue<'a>>;
}

D accepts any of: &'a DataValue<'a>, DataValue<'a>, &'a str, &OwnedDataValue, or &serde_json::Value (under feature = "serde_json").

#![allow(unused)]
fn main() {
use bumpalo::Bump;
use datalogic_rs::Engine;

let engine = Engine::new();
let compiled = engine.compile(r#"{"==": [{"var": "x"}, 1]}"#).unwrap();
let arena = Bump::new();
let result = engine.evaluate(&compiled, r#"{"x": 1}"#, &arena).unwrap();
assert_eq!(result.as_bool(), Some(true));
}

session

Open a Session that owns a reusable arena.

#![allow(unused)]
fn main() {
pub fn session(&self) -> Session<'_>;
}

trace (feature = “trace”)

Open a TracedSession that records execution steps. Mirrors session() 1:1 — every eval* returns a TracedRun<R> carrying the result, steps, and compile-time expression tree.

#![allow(unused)]
fn main() {
#[cfg(feature = "trace")]
pub fn trace(&self) -> TracedSession<'_>;
}

Introspection helpers

#![allow(unused)]
fn main() {
pub fn config(&self) -> &EvaluationConfig
pub fn has_custom_operator(&self, name: &str) -> bool
pub fn custom_operator_names(&self) -> impl Iterator<Item = &str>
}

EngineBuilder

Fluent constructor for Engine. Returned by Engine::builder().

#![allow(unused)]
fn main() {
EngineBuilder::new()
    .with_config(EvaluationConfig::default())
    .with_templating(true)                  // feature = "templating"
    .with_constant_folding(true)            // default; disable to keep every operator visible
    .add_operator("name", MyOp)             // typed operator
    .add_operator("dyn", boxed_op)          // also accepts Box<dyn CustomOperator>
    .build();
}

with_constant_folding(false) is useful for tooling that walks the compiled tree and would be surprised by {"+": [1, 2]} collapsing to a literal 3. The trace surface always disables folding internally regardless of this setting.

Logic

The compiled, reusable rule tree. Output of Engine::compile.

• Send + Sync — wrap in Arc to share across threads (or use Engine::compile_arc to do it in one step).
• Immutable after construction.
• resolve_node_ids(&self, ids: &[u32]) -> Vec<PathStep> — translate the breadcrumb of a structured Error into the source path of the failing node.

Session

Reusable evaluation handle that owns a bumpalo::Bump. The session never auto-resets — the caller decides when to release arena memory back to the start-of-chunk position. Construct via Engine::session().

#![allow(unused)]
fn main() {
let mut session = engine.session();
let result_str: String = session.eval_str(&compiled, data_json)?;
let result_owned: datalogic_rs::datavalue::OwnedDataValue =
    session.eval(&compiled, data)?;

#[cfg(feature = "serde_json")]
let value: serde_json::Value = session.eval_into(&compiled, &serde_data)?;

// Zero-copy borrowed result; lives until the next &mut self call.
let view: &datalogic_rs::DataValue<'_> = session.eval_borrowed(&compiled, data)?;

session.reset();                       // bound peak memory between batches
session.reset_with_capacity(64 * 1024);
let bytes = session.allocated_bytes();
}

Session::eval / eval_str / eval_into accept any EvalInput<'_>. eval_borrowed returns a &'a DataValue<'a> that borrows from the session’s arena — Rust’s borrow checker enforces that the next &mut self call invalidates it.

EvalInput

Sealed input adapter trait used by Engine::evaluate, Session::eval_borrowed, and the OwnedInput cousin used by the owned entry points.

The trait is sealed — external crates cannot add new shapes.

DataValue / OwnedDataValue

DataValue<'a> is the arena-resident value tree:

#![allow(unused)]
fn main() {
enum DataValue<'a> {
    Null,
    Bool(bool),
    Number(NumberRepr),
    String(&'a str),
    Array(&'a [DataValue<'a>]),
    Object(&'a [(&'a str, DataValue<'a>)]),
    DateTime(...),  // feature = "datetime"
    Duration(...),  // feature = "datetime"
    InputRef(...),  // borrow-through into caller input
}
}

Both DataValue and OwnedDataValue are re-exported from the datavalue crate. Use arena.alloc(...) to return values from custom operators; use OwnedDataValue when you need a heap-allocated owned tree (e.g. as the return of Engine::eval / Session::eval).

EvaluationConfig

Configuration for evaluation behavior. All fields are public — set them with struct update syntax:

#![allow(unused)]
fn main() {
EvaluationConfig {
    arithmetic_nan_handling: NanHandling::ThrowError,
    division_by_zero: DivisionByZeroHandling::ReturnSaturated,
    loose_equality_errors: true,
    truthy_evaluator: TruthyEvaluator::JavaScript,
    numeric_coercion: NumericCoercionConfig::default(),
}
}

Presets:

#![allow(unused)]
fn main() {
EvaluationConfig::default();
EvaluationConfig::safe_arithmetic();
EvaluationConfig::strict();
}

NanHandling

#![allow(unused)]
fn main() {
pub enum NanHandling {
    ThrowError,    // default
    IgnoreValue,
    CoerceToZero,
    ReturnNull,
}
}

DivisionByZeroHandling

#![allow(unused)]
fn main() {
pub enum DivisionByZeroHandling {
    ReturnSaturated,    // default — f64::MAX / MIN
    ThrowError,
    ReturnNull,
    ReturnInfinity,
}
}

TruthyEvaluator

#![allow(unused)]
fn main() {
pub enum TruthyEvaluator {
    JavaScript,    // default
    Python,
    StrictBoolean,
    Custom(Arc<dyn Fn(&OwnedDataValue) -> bool + Send + Sync>),
}
}

The Custom callback receives an &OwnedDataValue (not &serde_json::Value).

CustomOperator Trait

#![allow(unused)]
fn main() {
pub trait CustomOperator: Send + Sync {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        ctx: &mut operator::EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>>;
}
}

EvalContext

operator::EvalContext<'_, 'a> is an opaque view into the engine’s evaluation context, passed to CustomOperator::evaluate. Most custom operators don’t need to inspect it; the read-only accessors root_input() (the input passed to Engine::evaluate) and depth() (number of iteration frames currently pushed) cover the rare cases where behaviour depends on the surrounding context. The internal stack layout is hidden so it can evolve without breaking the trait contract.

Error

Structured error type:

#![allow(unused)]
fn main() {
pub struct Error {
    pub kind: ErrorKind,
    pub operator: Option<String>,
    pub path: Vec<u32>,
}

pub enum ErrorKind {
    InvalidOperator(String),
    InvalidArguments(String),
    VariableNotFound(String),
    InvalidContextLevel(isize),
    TypeError(String),
    ArithmeticError(String),
    Custom(CustomErrorSource),
    ParseError(String),
    Thrown(OwnedDataValue),
    FormatError(String),
    IndexOutOfBounds { index: isize, length: usize },
    ConfigurationError(String),
}
}

Error serialises (with serde) to:

{
  "type": "<KindTag>",
  "message": "<Display>",
  "operator": "<name>",        // present only when known
  "node_ids": [42, 13, 7],     // present only when non-empty
  // kind-specific extras (variable, level, thrown, index/length, ...)
}

Use error.tag() for stable string matching, error.thrown_value() for the Thrown payload, and error.resolve_path(&compiled) to translate the node_ids breadcrumb into source PathSteps.

To wrap a foreign std::error::Error into a Custom error:

#![allow(unused)]
fn main() {
"abc".parse::<i32>().map_err(datalogic_rs::Error::wrap)?;
}

Error::source() walks the inner chain unchanged.

Error Constructors

#![allow(unused)]
fn main() {
Error::invalid_operator(name)
Error::invalid_arguments(msg)
Error::variable_not_found(name)
Error::type_error(msg)
Error::arithmetic_error(msg)
Error::custom_message(msg)    // string-only
Error::wrap(err)              // any Error + Send + Sync + 'static
Error::parse_error(msg)
Error::thrown(value)
Error::format_error(msg)
Error::index_out_of_bounds(index, length)
Error::configuration_error(msg)
}

PathStep

Resolved entry returned by Logic::resolve_node_ids and Error::resolve_path. Names the operator and child index of a node along the failing-evaluation path.

Result Type

#![allow(unused)]
fn main() {
pub type Result<T> = std::result::Result<T, Error>;
}

Trace API (feature = “trace”)

TracedSession

Open via engine.trace(). Mirrors Session 1:1 — every eval* returns a TracedRun<R>.

#![allow(unused)]
fn main() {
#[cfg(feature = "trace")]
{
    let engine = datalogic_rs::Engine::new();
    let run = engine.trace().eval_str(r#"{"+": [1, 2]}"#, r#"{}"#);
    println!("{}", run.result.unwrap());
    println!("{} steps", run.steps.len());
}
}

The pre-compiled paths inherit whatever shape Engine::compile produced (constant folding can hide some operators). For full coverage on a single rule, prefer engine.trace().eval_str(rule, data) — the one-shot path compiles internally with folding disabled.

TracedRun<R> (feature = “trace”)

#![allow(unused)]
fn main() {
pub struct TracedRun<R> {
    pub result: Result<R, Error>,        // success and failure share one field
    pub steps: Vec<ExecutionStep>,
    pub expression_tree: ExpressionNode,
}
}

R is the same shape that Session::eval* would return: OwnedDataValue for eval, String for eval_str, T for eval_into::<T>, &'a DataValue<'a> for eval_borrowed.

#![allow(unused)]
fn main() {
pub struct ExecutionStep { /* per-node entry / result / error */ }
pub struct ExpressionNode { /* compile-time tree shape with stable ids */ }
}

Full Example

use datalogic_rs::{Engine, EvaluationConfig, NanHandling};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::builder()
        .with_config(EvaluationConfig {
            arithmetic_nan_handling: NanHandling::IgnoreValue,
            ..Default::default()
        })
        .build();

    let compiled = engine.compile_arc(
        r#"{"if": [{">=": [{"var": "score"}, 60]}, "pass", "fail"]}"#,
    )?;

    let mut session = engine.session();
    for score in [85, 45, 60] {
        let r = session.eval_str(&compiled, &format!(r#"{{"score": {}}}"#, score))?;
        println!("{} -> {}", score, r);
        session.reset();
    }

    Ok(())
}

Use Cases & Examples

Real-world examples of using datalogic-rs for common scenarios.

Feature Flags

Control feature availability based on user attributes.

Basic Feature Flag

#![allow(unused)]
fn main() {
// Feature available to premium users in US
let rule = r#"{
    "and": [
        {"==": [{"var": "user.plan"}, "premium"]},
        {"==": [{"var": "user.country"}, "US"]}
    ]
}"#;

let user_data = r#"{
    "user": {"plan": "premium", "country": "US"}
}"#;

let enabled = datalogic_rs::eval_str(rule, user_data).unwrap();
assert_eq!(enabled, "true");
}

The examples below show JSONLogic rules and data as JSON. Wire them through datalogic_rs::eval_str (zero-config one-shot), Engine::eval_str (one-shot through a configured engine), or compile once and reuse with Engine::session().

Percentage Rollout

#![allow(unused)]
fn main() {
// Enable for 20% of users (based on user ID hash)
let rule = json!({
    "<": [
        { "%": [{ "var": "user.id" }, 100] },
        20
    ]
});
}

Beta Access

#![allow(unused)]
fn main() {
// Enable for beta testers OR employees OR users who signed up before a date
let rule = json!({
    "or": [
        { "==": [{ "var": "user.role" }, "beta_tester"] },
        { "ends_with": [{ "var": "user.email" }, "@company.com"] },
        { "<": [{ "var": "user.signup_date" }, "2024-01-01"] }
    ]
});
}

Dynamic Pricing

Calculate prices based on rules.

Discount by Quantity

#![allow(unused)]
fn main() {
let rule = json!({
    "if": [
        { ">=": [{ "var": "quantity" }, 100] },
        { "*": [{ "var": "base_price" }, 0.8] },  // 20% off
        { "if": [
            { ">=": [{ "var": "quantity" }, 50] },
            { "*": [{ "var": "base_price" }, 0.9] },  // 10% off
            { "var": "base_price" }
        ]}
    ]
});

// Data: { "quantity": 75, "base_price": 100 }
// Result: 90 (10% discount)
}

Tiered Pricing

#![allow(unused)]
fn main() {
let rule = json!({
    "+": [
        // First 10 units at $10
        { "*": [{ "min": [{ "var": "quantity" }, 10] }, 10] },
        // Next 40 units at $8
        { "*": [
            { "max": [{ "-": [{ "min": [{ "var": "quantity" }, 50] }, 10] }, 0] },
            8
        ]},
        // Remaining units at $6
        { "*": [
            { "max": [{ "-": [{ "var": "quantity" }, 50] }, 0] },
            6
        ]}
    ]
});
}

Member Pricing

#![allow(unused)]
fn main() {
let rule = json!({
    "if": [
        { "var": "user.is_member" },
        { "*": [
            { "var": "product.price" },
            { "-": [1, { "/": [{ "var": "user.member_discount" }, 100] }] }
        ]},
        { "var": "product.price" }
    ]
});

let data = json!({
    "user": { "is_member": true, "member_discount": 15 },
    "product": { "price": 200 }
});
// Result: 170 (15% member discount)
}

Form Validation

Validate user input with complex rules.

Required Fields

#![allow(unused)]
fn main() {
let rule = json!({
    "if": [
        { "missing": ["name", "email", "password"] },
        {
            "valid": false,
            "errors": { "missing": ["name", "email", "password"] }
        },
        { "valid": true }
    ]
});
}

Field Constraints

#![allow(unused)]
fn main() {
let engine = Engine::builder().with_templating(true).build();

let rule = json!({
    "valid": { "and": [
        // Email format
        { "in": ["@", { "var": "email" }] },
        // Password length
        { ">=": [{ "length": { "var": "password" } }, 8] },
        // Age range
        { "and": [
            { ">=": [{ "var": "age" }, 18] },
            { "<=": [{ "var": "age" }, 120] }
        ]}
    ]},
    "errors": { "filter": [
        [
            { "if": [
                { "!": { "in": ["@", { "var": "email" }] } },
                "Invalid email format",
                null
            ]},
            { "if": [
                { "<": [{ "length": { "var": "password" } }, 8] },
                "Password must be at least 8 characters",
                null
            ]},
            { "if": [
                { "or": [
                    { "<": [{ "var": "age" }, 18] },
                    { ">": [{ "var": "age" }, 120] }
                ]},
                "Age must be between 18 and 120",
                null
            ]}
        ],
        { "!==": [{ "var": "" }, null] }
    ]}
});
}

Conditional Validation

#![allow(unused)]
fn main() {
// If business account, require company name
let rule = json!({
    "if": [
        { "and": [
            { "==": [{ "var": "account_type" }, "business"] },
            { "missing": ["company_name"] }
        ]},
        { "error": "Company name required for business accounts" },
        { "valid": true }
    ]
});
}

Access Control

Determine user permissions.

Role-Based Access

#![allow(unused)]
fn main() {
let rule = json!({
    "or": [
        { "==": [{ "var": "user.role" }, "admin"] },
        { "and": [
            { "==": [{ "var": "user.role" }, "editor"] },
            { "==": [{ "var": "resource.owner_id" }, { "var": "user.id" }] }
        ]}
    ]
});
}

Permission Checking

#![allow(unused)]
fn main() {
let rule = json!({
    "in": [
        { "var": "required_permission" },
        { "var": "user.permissions" }
    ]
});

let data = json!({
    "user": {
        "permissions": ["read", "write", "delete"]
    },
    "required_permission": "write"
});
// Result: true
}

Time-Based Access

#![allow(unused)]
fn main() {
let rule = json!({
    "and": [
        // Has permission
        { "in": ["access_data", { "var": "user.permissions" }] },
        // Within allowed hours (9 AM - 6 PM)
        { "and": [
            { ">=": [{ "var": "current_hour" }, 9] },
            { "<": [{ "var": "current_hour" }, 18] }
        ]},
        // On a weekday
        { "in": [{ "var": "current_day" }, [1, 2, 3, 4, 5]] }
    ]
});
}

Fraud Detection

Score and flag potentially fraudulent transactions.

Risk Scoring

#![allow(unused)]
fn main() {
let rule = json!({
    "+": [
        // High amount
        { "if": [{ ">": [{ "var": "amount" }, 1000] }, 30, 0] },
        // New account
        { "if": [{ "<": [{ "var": "account_age_days" }, 7] }, 25, 0] },
        // Different country
        { "if": [
            { "!=": [{ "var": "billing_country" }, { "var": "shipping_country" }] },
            20,
            0
        ]},
        // Multiple attempts
        { "if": [{ ">": [{ "var": "attempts_last_hour" }, 3] }, 25, 0] },
        // Unusual time
        { "if": [
            { "or": [
                { "<": [{ "var": "hour" }, 6] },
                { ">": [{ "var": "hour" }, 23] }
            ]},
            15,
            0
        ]}
    ]
});

// Score > 50 = flag for review
let data = json!({
    "amount": 1500,
    "account_age_days": 3,
    "billing_country": "US",
    "shipping_country": "CA",
    "attempts_last_hour": 1,
    "hour": 14
});
// Result: 75 (high amount + new account + different country)
}

Velocity Checks

#![allow(unused)]
fn main() {
let rule = json!({
    "or": [
        // Too many transactions in short time
        { ">": [{ "var": "transactions_last_hour" }, 10] },
        // Too much total amount
        { ">": [{ "var": "total_amount_last_hour" }, 5000] },
        // Same card used from multiple IPs
        { ">": [{ "var": "unique_ips_last_day" }, 3] }
    ]
});
}

Data Transformation

Transform and reshape data.

API Response Mapping

#![allow(unused)]
fn main() {
let engine = Engine::builder().with_templating(true).build();

let template = json!({
    "users": {
        "map": [
            { "var": "raw_users" },
            {
                "id": { "var": "user_id" },
                "fullName": { "cat": [{ "var": "first_name" }, " ", { "var": "last_name" }] },
                "email": { "lower": { "var": "email" } },
                "isActive": { "==": [{ "var": "status" }, "active"] }
            }
        ]
    },
    "total": { "length": { "var": "raw_users" } },
    "activeCount": { "length": {
        "filter": [
            { "var": "raw_users" },
            { "==": [{ "var": "status" }, "active"] }
        ]
    }}
});
}

Report Generation

#![allow(unused)]
fn main() {
let template = json!({
    "report": {
        "title": { "cat": ["Sales Report - ", { "var": "period" }] },
        "generated": { "format_date": [{ "now": [] }, "%Y-%m-%d %H:%M"] },
        "summary": {
            "totalSales": { "reduce": [
                { "var": "transactions" },
                { "+": [{ "var": "accumulator" }, { "var": "current.amount" }] },
                0
            ]},
            "avgTransaction": { "/": [
                { "reduce": [
                    { "var": "transactions" },
                    { "+": [{ "var": "accumulator" }, { "var": "current.amount" }] },
                    0
                ]},
                { "length": { "var": "transactions" } }
            ]},
            "topCategory": { "var": "top_category" }
        }
    }
});
}

Notification Rules

Determine when and how to send notifications.

Alert Conditions

#![allow(unused)]
fn main() {
let rule = json!({
    "if": [
        // Critical: immediate
        { ">": [{ "var": "error_rate" }, 10] },
        { "channel": "pager", "priority": "critical" },
        // Warning: Slack
        { "if": [
            { ">": [{ "var": "error_rate" }, 5] },
            { "channel": "slack", "priority": "warning" },
            // Info: email digest
            { "if": [
                { ">": [{ "var": "error_rate" }, 1] },
                { "channel": "email", "priority": "info" },
                null
            ]}
        ]}
    ]
});
}

User Preferences

#![allow(unused)]
fn main() {
let rule = json!({
    "and": [
        // User has enabled notifications
        { "var": "user.notifications_enabled" },
        // Notification type is in user's preferences
        { "in": [
            { "var": "notification.type" },
            { "var": "user.enabled_types" }
        ]},
        // Within user's quiet hours
        { "!": { "and": [
            { ">=": [{ "var": "current_hour" }, { "var": "user.quiet_start" }] },
            { "<": [{ "var": "current_hour" }, { "var": "user.quiet_end" }] }
        ]}}
    ]
});
}

Performance

This guide covers performance optimization, benchmarking, and best practices for datalogic-rs.

Performance Characteristics

Compilation vs Evaluation

datalogic-rs uses a two-phase approach:

1. Compilation (slower): Parse and optimize the JSONLogic expression
2. Evaluation (faster): Execute compiled logic against data

Best practice: compile once, evaluate many times.

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;

let engine = Engine::new();
let compiled = engine.compile(rule_json).unwrap();

let mut session = engine.session();
for data in datasets {
    session.eval_str(&compiled, data)?;
}
}

OpCode Dispatch

Built-in operators use direct OpCode dispatch instead of string lookups:

• 59 built-in operators have direct dispatch
• Custom operators use a single map lookup
• No runtime reflection or dynamic dispatch

Memory Efficiency

v5 optimizations:

• Arena allocation — &DataValue<'a> results live in a bumpalo::Bump for one evaluation. Read-through ops like var borrow zero-copy from the caller’s input.
• Reusable arenas — Session reuses one Bump across calls; the caller calls session.reset() between batches so peak memory tracks the largest single evaluation rather than the sum.
• Pre-built literal singletons — trivial literals (Null, Bool, empty primitives) are static and incur no per-call allocation.
• Arc<Logic> — cheap clone for cross-thread sharing.

Benchmarking

Running Benchmarks

The benchmark harness lives in its own dev-only crate, datalogic-bench, under tools/benchmark/. Two binaries share a common harness:

# Single-engine benchmark (datalogic-rs alone, fast arena path)
cargo run --release -p datalogic-bench --bin self
cargo run --release -p datalogic-bench --bin self -- --all   # every suite + JSON report

# Cross-library comparison (only datalogic-rs ships by default; see
# tools/benchmark/README.md for adding more subjects)
cargo run --release -p datalogic-bench --bin compare -- --all

Reports land in tools/benchmark/output/ (gitignored).

Creating Custom Benchmarks

use std::time::Instant;
use datalogic_rs::Engine;

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

    let iterations = 100_000;
    let start = Instant::now();

    for _ in 0..iterations {
        let _ = session.eval_str(&compiled, r#"{"x": 1}"#);
    }

    let elapsed = start.elapsed();
    let per_op = elapsed / iterations;
    println!("Time per evaluation: {:?}", per_op);
}

For the absolute hot path, drop down to Engine::evaluate and manage the arena yourself — the result is a zero-copy &DataValue<'a> and avoids the deep-clone Session does at the boundary.

#![allow(unused)]
fn main() {
use bumpalo::Bump;

let arena = Bump::new();
let result = engine.evaluate(&compiled, r#"{"x": 1}"#, &arena).unwrap();
// `result` is `&DataValue<'_>` — borrows from `arena`.
}

Optimization Tips

1. Reuse Compiled Rules

#![allow(unused)]
fn main() {
// Good
let compiled = engine.compile(rule).unwrap();
for data in datasets {
    session.eval_str(&compiled, data)?;
}

// Bad — recompiles every iteration
for data in datasets {
    let compiled = engine.compile(rule).unwrap();
    engine.eval_str(rule, data)?;
    let _ = compiled;
}
}

2. Pick the Right Entry Point

3. Short-Circuit Evaluation

and, or, if, ?:, and ?? short-circuit. Order conditions so the cheapest / most-likely-to-decide check comes first:

{
  "and": [
    {"var": "isActive"},
    {"in": ["admin", {"var": "roles"}]}
  ]
}

4. Minimize Cloning in Custom Operators

CustomOperator receives args as &DataValue<'a> borrows. Avoid materialising into owned values unless you actually need to mutate.

#![allow(unused)]
fn main() {
let n = args[0].as_f64().unwrap_or(0.0); // cheap read
}

5. Minimize Nested Variable Access

Deep paths require multiple lookups:

{"var": "user.profile.settings.theme.color"}   // slow
{"var": "themeColor"}                           // fast

JavaScript / WASM Performance

CompiledRule Advantage

const iterations = 10_000;

console.time('evaluate');
for (let i = 0; i < iterations; i++) {
  evaluate(logic, data, false);
}
console.timeEnd('evaluate');

const rule = new CompiledRule(logic, false);
console.time('compiled');
for (let i = 0; i < iterations; i++) {
  rule.evaluate(data);
}
console.timeEnd('compiled');

Typical improvement: 2–5× faster with CompiledRule.

React UI Performance

For the DataLogicEditor component:

1. Memoise expressions:

   const expression = useMemo(() => ({ ... }), [deps]);
   

2. Debounce data changes in debug mode:

   const debouncedData = useDebouncedValue(data, 200);
   <DataLogicEditor value={expr} data={debouncedData} mode="debug" />
   

3. Use visualize mode when debugging isn’t needed:

   <DataLogicEditor value={expr} mode="visualize" />
   

Profiling

Rust Profiling

# perf (Linux)
cargo build --release
perf record ./target/release/your-binary
perf report

# Instruments (macOS)
cargo instruments --release -t "CPU Profiler"

Tracing for Bottlenecks

Enable the trace feature and call engine.trace().eval_str(...) to inspect every executed node.

#![allow(unused)]
fn main() {
#[cfg(feature = "trace")]
{
    let run = engine.trace().eval_str(rule, data);
    for step in &run.steps {
        // step.node_id, step.expression, step.context, step.result, ...
    }
}
}

Production Recommendations

1. Pre-compile all rules at startup
2. Use a worker pool with per-worker Sessions for parallel evaluation
3. Monitor evaluation latency in production
4. Set appropriate timeouts for untrusted rules
5. Consider rule complexity limits for user-defined logic

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, Logic};
use std::collections::HashMap;
use std::sync::Arc;

struct RuleEngine {
    engine: Arc<Engine>,
    rules: HashMap<String, Arc<Logic>>,
}

impl RuleEngine {
    pub fn new() -> Self {
        let engine = Arc::new(Engine::new());
        let mut rules = HashMap::new();

        for (name, logic) in load_rules() {
            let compiled = engine.compile_arc(&logic).unwrap();
            rules.insert(name, compiled);
        }

        Self { engine, rules }
    }

    pub fn evaluate(&self, rule_name: &str, data: &str) -> datalogic_rs::Result<String> {
        let compiled = self.rules.get(rule_name)
            .ok_or_else(|| datalogic_rs::Error::custom_message(format!("unknown rule: {rule_name}")))?;
        let mut session = self.engine.session();
        let result = session.eval_str(compiled, data);
        session.reset();
        result
    }
}
fn load_rules() -> Vec<(String, String)> { Vec::new() }
}

Migration Guide

This page is a quick conceptual overview. The full v4 → v5 cookbook — every renamed call, every cargo-feature swap, every error-handling update — lives in MIGRATION.md at the repo root. Treat that file as authoritative.

v4 to v5 Migration

v5 is a hard cliff

v5 has no compatibility shim. The pre-release compat feature and the LegacyApi trait are gone — there is no transitional crate configuration. Plan a single cutover: update Cargo.toml, run a find-and-replace pass, and re-run your test suite.

The on-the-wire JSONLogic spec is unchanged — your rules and data still look the same. Everything that changes is on the Rust side.

What changed at a glance

• Type renames. DataLogic → Engine, CompiledLogic → Logic, Operator → CustomOperator, ArenaValue → DataValue, ArenaContextStack → operator::EvalContext. Evaluator is gone (args arrive pre-evaluated).
• Method renames. Every evaluate_* is now eval_*. evaluate_str → eval_str, evaluate_borrowed → eval_borrowed. The serde_json::Value-shaped variants (evaluate_json_value, evaluate_owned, evaluate_ref, …) collapse into one typed entry point: engine.eval_into::<T, _, _>(rule, data) (or datalogic_rs::eval_into::<T, _, _>(...) at the module level), gated on feature = "serde_json".
• Builder construction. DataLogic::with_config(c) / with_preserve_structure() / with_config_and_structure(c, s) all collapse into Engine::builder() with .with_config(c) and .with_templating(s) setters.
• Compilation accepts more shapes. engine.compile(rule) takes any IntoLogic: &str, &String, &OwnedDataValue, OwnedDataValue, &serde_json::Value (gated on serde_json).
• Module-level helpers for one-shot calls. datalogic_rs::eval, datalogic_rs::eval_str, datalogic_rs::eval_into, and datalogic_rs::compile use a shared default engine — no need to construct an Engine for the simple cases.
• Sessions are explicit. Reusable arenas live on Session (engine.session()); the session never auto-resets, so callers call session.reset() between batches.
• Trace surface is a session. engine.trace().eval_str(rule, data) returns a TracedRun<R> with result: Result<R, Error> plus steps and expression_tree. Available on feature = "trace". The old TracedResult type is gone — successful and failed runs share the same TracedRun<R> shape.
• Custom operators take pre-evaluated args. Implementations get args: &[&'a DataValue<'a>], a &mut EvalContext<'_, 'a>, and a &'a bumpalo::Bump; they return &'a DataValue<'a>.
• Operator registration is builder-only. Engine is immutable after build(). Register every custom operator on the EngineBuilder before calling .build().
• Error is structured. Error is a struct with kind, operator(), node_ids(), tag(), plus a stable JSON wire format. Construct via Error::invalid_arguments(...), Error::type_error(...), Error::custom_message(...), Error::wrap(...).
• preserve operator removed. Literal scalars and arrays already pass through inline; templated objects belong in templating mode (rebuild with Engine::builder().with_templating(true).build(), requires feature = "templating").
• Edition 2024 + #![forbid(unsafe_code)].

Feature-flag rename

The pre-release compat feature is gone. The replacement is purpose-named:

Quick before/after sketch

#![allow(unused)]
fn main() {
// v4
use datalogic_rs::DataLogic;
let mut engine = DataLogic::with_config(my_config);
engine.add_operator("double".to_string(), Box::new(MyOp));
let compiled = engine.compile(&rule_value)?;
let result: Value = engine.evaluate_owned(&compiled, data)?;
}

#![allow(unused)]
fn main() {
// v5
use datalogic_rs::Engine;
let engine = Engine::builder()
    .with_config(my_config)
    .add_operator("double", MyOp)
    .build();
let compiled = engine.compile(&rule_value)?;             // accepts &Value via `serde_json`
let result = engine.eval(&compiled, &data_value);        // OwnedDataValue
let result_str = engine.eval_str(&compiled, data_str)?;  // String (JSON)
let v: serde_json::Value = engine.eval_into(&compiled, &data_value)?;  // typed
}

Custom operators

#![allow(unused)]
fn main() {
// v5 (final)
use datalogic_rs::{CustomOperator, DataValue, Engine, Result};
use datalogic_rs::operator::EvalContext;
use bumpalo::Bump;

struct DoubleOperator;
impl CustomOperator for DoubleOperator {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a Bump,
    ) -> Result<&'a DataValue<'a>> {
        // args are already evaluated — no Evaluator call.
        let n = args.first()
            .and_then(|v| v.as_f64())
            .unwrap_or(0.0);
        Ok(arena.alloc(DataValue::from_f64(n * 2.0)))
    }
}

let engine = Engine::builder()
    .add_operator("double", DoubleOperator)
    .build();
}

Where to look next

• The repo-root MIGRATION.md has the per-call cookbook.
• api/reference.md covers every v5 method.
• getting-started/quick-start.md walks through the new module-level helpers.

v3 to v4 Migration

If you’re stepping from v3 directly to v5, the v3 → v4 jump is a historical layer that no longer matches anything in this codebase. Read the v4-to-v5 section above and the repo-root MIGRATION.md; everything you need to land on v5 is covered there.

Getting Help

If you encounter issues during migration:

1. Check the API Reference
2. Review the examples
3. Open an issue on GitHub

FAQ

Frequently asked questions about datalogic-rs.

General

What is JSONLogic?

JSONLogic is a way to write portable, safe logic rules as JSON. The specification is available at jsonlogic.com.

Why use datalogic-rs instead of the reference implementation?

• Performance — significantly faster than JS implementations
• Thread Safety — Logic is Send + Sync; wrap in Arc to share
• Extended Operators — datetime, regex, error handling, more
• Type Safety — full Rust type system benefits
• WASM Support — same engine in browsers and Node.js
• Zero unsafe — the crate is built with #![forbid(unsafe_code)]

Is datalogic-rs fully compatible with JSONLogic?

Yes. datalogic-rs passes the complete official JSONLogic test suite. It also includes additional operators that extend the specification.

Rust Usage

Should I use v4 or v5?

Use v5 for new projects. The API is cleaner, the default build does not pull in serde_json, and the arena evaluation path is exposed directly. See the Migration Guide for the move from v4.

v5 is a hard cliff — there is no compatibility shim, so plan a single cutover when upgrading from v4. The repo-root MIGRATION.md has the per-call cookbook.

How do I share compiled rules across threads?

Logic is Send + Sync. Wrap it in Arc to share:

#![allow(unused)]
fn main() {
use datalogic_rs::Engine;
use std::sync::Arc;

let engine = Arc::new(Engine::new());
let compiled = engine.compile_arc(rule).unwrap();

let compiled_clone = Arc::clone(&compiled);
std::thread::spawn(move || {
    let mut session = engine.session();
    session.eval_str(&compiled_clone, data)
});
}

Why are custom operator arguments pre-evaluated in v5?

The pre-evaluated, arena-based design makes custom operators behave like built-ins: the engine recurses, hands you &DataValue<'a> borrows, and you return another arena allocation. This avoids the boundary conversion that the v4 Operator trait paid on every call and removes the need for a separate Evaluator trait.

If you need lazy / short-circuit semantics like and / or, that lives in built-in operators today (none of the v5 short-circuit operators are exposed through the public custom-operator surface).

What’s the difference between eval, eval_str, eval_into, and evaluate?

The typed eval_into::<T> paths (and the serde_json::Value boundary on EvalInput / IntoLogic) require feature = "serde_json".

JavaScript / WASM Usage

Do I need to call init() in Node.js?

No. The Node.js target does not require initialization:

const { evaluate } = require('@goplasmatic/datalogic-wasm');
evaluate('{"==": [1, 1]}', '{}', false);

Why do I need to JSON.stringify my data?

The WASM interface uses string-based communication for maximum compatibility:

const result = evaluate(
  JSON.stringify(logic),
  JSON.stringify(data),
  false
);
const value = JSON.parse(result);

How do I use this with TypeScript?

Types are included in the package:

import init, { evaluate, CompiledRule } from '@goplasmatic/datalogic-wasm';

await init();
const result: string = evaluate('{"==": [1, 1]}', '{}', false);

React UI

Why does the editor need explicit dimensions?

React Flow (the underlying library) requires a container with defined dimensions to calculate node positions and viewport.

<div style={{ height: '500px' }}>
  <DataLogicEditor value={expression} />
</div>

Can I use this with Next.js?

Yes. For the App Router, wrap in a client component:

'use client';

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';
import { DataLogicEditor } from '@goplasmatic/datalogic-ui';

export function Editor({ expression }) {
  return <DataLogicEditor value={expression} />;
}

Operators

How do I access array elements by index?

Use the var operator with numeric path segments:

{"var": "items.0.name"}

What’s the difference between == and ===?

• ==: Loose equality (with type coercion, like JavaScript)
• ===: Strict equality (no type coercion)

{"==": [1, "1"]}   // true
{"===": [1, "1"]}  // false

How do I handle missing data?

Use the missing or missing_some operators:

{"if": [
    {"missing": ["user.email"]},
    "Email required",
    "Valid"
]}

Or use default values with var:

{"var": ["user.email", "no-email@example.com"]}

What happened to the preserve operator?

It was removed in v5. Literal scalars and arrays already pass through inline, and templated objects belong in templating mode (Engine::builder().with_templating(true).build(), requires feature = "templating").

Configuration

How do I handle NaN in arithmetic?

Use the NanHandling configuration:

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig, NanHandling};

let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue,
    ..Default::default()
};
let engine = Engine::builder().with_config(config).build();
}

Options: ThrowError (default), CoerceToZero, IgnoreValue, ReturnNull.

How do I change division by zero behavior?

#![allow(unused)]
fn main() {
use datalogic_rs::{EvaluationConfig, DivisionByZeroHandling};

let config = EvaluationConfig {
    division_by_zero: DivisionByZeroHandling::ReturnNull,
    ..Default::default()
};
}

Options: ReturnSaturated (default — f64::MAX/MIN), ThrowError, ReturnNull, ReturnInfinity.

Troubleshooting

“Invalid operator” error

In standard mode, unrecognized keys are treated as errors. Either:

1. Fix the operator name (operators are case-sensitive)
2. Register a custom operator on the builder
3. Enable templating mode (feature = "templating") — Engine::builder().with_templating(true).build()

Performance issues with large expressions

1. Use Session for repeated calls (arena reuse)
2. Drop to Engine::evaluate with a caller-managed bumpalo::Bump for the absolute hot path
3. Profile with feature = "trace" to identify slow sub-expressions

WASM initialization fails

Ensure you await init() before calling other functions:

await init();
const result = evaluate(...);

For more troubleshooting, see the Troubleshooting Guide.

Troubleshooting

Common issues and solutions for datalogic-rs.

Rust Issues

“Invalid operator: xyz”

Cause: Using an unrecognized operator name.

Solutions:

1. Check the operator name spelling (operators are case-sensitive).
2. Register a custom operator on the builder.
3. Enable templating mode (requires feature = "templating") — unknown keys then become literal output fields.

#![allow(unused)]
fn main() {
// Option 1: Fix spelling
let logic = r#"{"and": [...]}"#;  // not "AND"

// Option 2: Custom operator
let engine = datalogic_rs::Engine::builder()
    .add_operator("xyz", XyzOperator)
    .build();

// Option 3: Templating mode (feature = "templating")
#[cfg(feature = "templating")]
let engine = datalogic_rs::Engine::builder().with_templating(true).build();
}

“Variable not found”

Cause: Accessing a path that doesn’t exist in the data.

Solutions:

1. Check the variable path spelling
2. Use a default value
3. Use missing to check first

{"var": ["user.name", "Anonymous"]}

{"if": [
    {"missing": ["user.name"]},
    "No name",
    {"var": "user.name"}
]}

Unexpected NaN / Thrown errors from arithmetic

Cause: Non-numeric values in arithmetic operations.

Solution: Configure NaN handling:

#![allow(unused)]
fn main() {
use datalogic_rs::{Engine, EvaluationConfig, NanHandling};

let config = EvaluationConfig {
    arithmetic_nan_handling: NanHandling::IgnoreValue, // or CoerceToZero
    ..Default::default()
};
let engine = Engine::builder().with_config(config).build();
}

“the trait bound T: CustomOperator is not satisfied” / Send-Sync errors

Cause: Custom operator type that isn’t Send + Sync.

Solution: Use thread-safe primitives. Avoid Rc, RefCell, etc., in operator state — wrap shared state in Arc<Mutex<_>> or atomics.

v4 method calls fail to compile in v5

Cause: v5 renamed the public surface (DataLogic → Engine, CompiledLogic → Logic, Operator → CustomOperator, evaluate_* → eval_*, etc.) and removed the pre-release compat shim. v5 is a hard cliff — there is no transitional feature flag.

Solutions:

• Follow the conceptual overview in the Migration Guide and the per-call cookbook in the repo-root MIGRATION.md.
• Common mappings:
  • DataLogic::with_config(c) → Engine::builder().with_config(c).build()
  • engine.evaluate_str(rule, data) → engine.eval_str(rule, data) (or datalogic_rs::eval_str(rule, data) for the zero-config path)
  • engine.evaluate_json_value(&rule, &data) → engine.eval_into::<Value, _, _>(&rule, &data) (requires feature = "serde_json")
  • engine.evaluate_json_with_trace(rule, data) → engine.trace().eval_str(rule, data) returning TracedRun<String>

Slow compilation

Cause: Very large or deeply nested expressions.

Solutions:

• Compile once, evaluate many times
• Break expressions into smaller composable pieces
• Profile with feature = "trace" to see which sub-expressions dominate

#![allow(unused)]
fn main() {
let compiled = engine.compile(rule).unwrap();
let mut session = engine.session();
for data in dataset {
    session.eval_str(&compiled, data)?;
    session.reset();
}
}

JavaScript / WASM Issues

“RuntimeError: memory access out of bounds”

Cause: WASM module not initialized.

Solution: Call init() before using any functions:

import init, { evaluate } from '@goplasmatic/datalogic-wasm';

await init();
evaluate(logic, data, false);

“TypeError: Cannot read properties of undefined”

Cause: Wrong import style for your environment.

Solutions:

// Browser/Bundler — need default import for init
import init, { evaluate } from '@goplasmatic/datalogic-wasm';

// Node.js — no init needed
const { evaluate } = require('@goplasmatic/datalogic-wasm');

“Failed to fetch” in browser

Cause: WASM file not accessible from the browser.

Solutions:

1. Check your bundler configuration
2. Ensure WASM files are served correctly
3. Check CORS headers if loading from CDN

For Webpack:

// webpack.config.js
module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
};

Results are strings, not values

Cause: WASM returns JSON strings, not native values.

Solution: Parse the result:

const resultString = evaluate(logic, data, false);
const result = JSON.parse(resultString);

Performance issues

Cause: Recompiling rules repeatedly.

Solution: Use CompiledRule:

const rule = new CompiledRule(logic, false);
for (const item of items) {
  rule.evaluate(JSON.stringify(item));
}

React UI Issues

“ResizeObserver loop completed with undelivered notifications”

Cause: Container size changes rapidly. Usually harmless.

Editor shows blank / empty

Causes:

1. Container has no dimensions
2. CSS not imported
3. Expression is null

Solutions:

<div style={{ width: '100%', height: '500px' }}>
  <DataLogicEditor value={expression} />
</div>

import '@xyflow/react/dist/style.css';
import '@goplasmatic/datalogic-ui/styles.css';

Debug mode not showing results

Cause: data prop not provided.

Solution:

<DataLogicEditor
  value={expression}
  data={{ x: 1, y: 2 }}
  mode="debug"
/>

SSR / Hydration errors in Next.js

Cause: WASM doesn’t run on server.

Solution: Use a client component with dynamic import:

'use client';

import dynamic from 'next/dynamic';

const DataLogicEditor = dynamic(
  () => import('@goplasmatic/datalogic-ui').then(mod => mod.DataLogicEditor),
  { ssr: false }
);

Build Issues

WASM build fails

Cause: Missing wasm-pack or target.

Solution:

cargo install wasm-pack
rustup target add wasm32-unknown-unknown
cd bindings/wasm && ./build.sh

TypeScript errors with imports

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  }
}

Bundler can’t find WASM file

// Webpack — enable async WASM
experiments: { asyncWebAssembly: true }

Getting Help

If you can’t resolve an issue:

1. Check existing issues
2. Create a minimal reproduction
3. Open a new issue with:
   • datalogic-rs version
   • Environment (Rust / Node / Browser)
   • Minimal code to reproduce
   • Expected vs actual behavior