@goplasmatic/datalogic

High-performance JSONLogic engine for JavaScript/TypeScript, powered by WebAssembly.

This package provides WebAssembly bindings for datalogic-rs, a Rust implementation of JSONLogic that supports all standard operators plus extended functionality.

Installation

``bash
npm install @goplasmatic/datalogic
`

Quick Start

`javascript
import init, { evaluate, CompiledRule } from '@goplasmatic/datalogic';

// Initialize the WASM module (required for web/ES modules)
await init();

// Simple evaluation
const result = evaluate('{"==": [1, 1]}', '{}', false);
console.log(result); // "true"

// With data
const result2 = evaluate('{"var": "user.age"}', '{"user": {"age": 25}}', false);
console.log(result2); // "25"

// Compiled rule for repeated evaluation (better performance)
const rule = new CompiledRule('{"+": [{"var": "a"}, {"var": "b"}]}', false);
console.log(rule.evaluate('{"a": 1, "b": 2}')); // "3"
console.log(rule.evaluate('{"a": 10, "b": 20}')); // "30"
`

Usage by Environment

$3

`html

`

$3

`javascript
// ESM
import { evaluate, CompiledRule } from '@goplasmatic/datalogic';

// No init() needed for Node.js
const result = evaluate('{"==": [1, 1]}', '{}', false);
console.log(result); // "true"

// Compiled rule
const rule = new CompiledRule('{"if": [{"var": "premium"}, "VIP", "Standard"]}', false);
console.log(rule.evaluate('{"premium": true}')); // "\"VIP\""
console.log(rule.evaluate('{"premium": false}')); // "\"Standard\""
`

$3

`javascript
import init, { evaluate, CompiledRule } from '@goplasmatic/datalogic';

// For bundlers, you may need to initialize
await init();

const result = evaluate('{">=": [{"var": "score"}, 80]}', '{"score": 85}', false);
console.log(result); // "true"
`

$3

If you need to import a specific target build:

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

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

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

API Reference

$3

Evaluate a JSONLogic expression against data.

Parameters:
- logic - JSON string containing the JSONLogic expression
- data - JSON string containing the data to evaluate against
- preserve_structure - If true, preserves object structure for JSON templates with embedded JSONLogic (templating mode)

Returns: JSON string result

Throws: Error string on invalid JSON or evaluation error

`javascript
evaluate('{"==": [{"var": "x"}, 5]}', '{"x": 5}', false); // "true"
evaluate('{"+": [1, 2, 3]}', '{}', false); // "6"
evaluate('{"map": [[1,2,3], {"+": [{"var": ""}, 1]}]}', '{}', false); // "[2,3,4]"

// With preserve_structure for templating
evaluate('{"name": {"var": "user"}, "active": true}', '{"user": "Alice"}', true);
// '{"name":"Alice","active":true}'
`

$3

Evaluate with execution trace for debugging. Returns detailed step-by-step information about how the expression was evaluated.

Parameters:
- logic - JSON string containing the JSONLogic expression
- data - JSON string containing the data to evaluate against
- preserve_structure - If true, preserves object structure for JSON templates with embedded JSONLogic (templating mode)

Returns: JSON string containing TracedResult with:
- result - The evaluation result
- expression_tree - Tree structure of the expression with node IDs
- steps - Array of execution steps with context and intermediate results

`javascript
const trace = evaluate_with_trace('{"and": [true, {"var": "x"}]}', '{"x": true}', false);
console.log(JSON.parse(trace));
// {
// "result": true,
// "expression_tree": { "id": 0, "expression": "{\"and\": [...]}", ... },
// "steps": [...]
// }
`

$3

A compiled JSONLogic rule for repeated evaluation. Pre-compiling rules provides better performance when evaluating the same logic against different data.

#### new CompiledRule(logic: string, preserve_structure: boolean)

Create a new compiled rule.

Parameters:
- logic - JSON string containing the JSONLogic expression
- preserve_structure - If true, preserves object structure for JSON templates with embedded JSONLogic (templating mode)

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

#### evaluate(data: string): string

Evaluate the compiled rule against data.

`javascript
rule.evaluate('{"age": 21}'); // "true"
rule.evaluate('{"age": 16}'); // "false"
`

Supported Operators

This library supports 59 built-in operators covering all standard JSONLogic plus extended functionality:

Logical: and, or, !, !!

Comparison: ==, ===, !=, !==, <, <=, >, >=

Arithmetic: +, -, *, /, %, min, max, abs, ceil, floor

Control Flow: if, ?:, ?? (coalesce)

Array: map, filter, reduce, all, some, none, merge, in, sort, slice

String: cat, substr, starts_with, ends_with, upper, lower, trim, split, length

Data Access: var, val, exists, missing, missing_some

Date/Time: now, datetime, timestamp, parse_date, format_date, date_diff

Error Handling: try, throw

Type Operations: type

Special: preserve (structure preservation for templating)

For the complete list and documentation, see the main repository.

Performance

This WASM-based implementation provides near-native performance:

- Compiled rules are significantly faster for repeated evaluations
- Zero-copy where possible between JS and WASM
- Small bundle size (~50KB gzipped)

Building from Source

$3

- Rust with wasm32-unknown-unknown target
- wasm-pack

`bash


Install wasm-pack

cargo install wasm-pack

Add WASM target

rustup target add wasm32-unknown-unknown
`

$3

`bash
cd wasm
./build.sh
`

This creates a pkg/ directory with builds for all targets (web, bundler, nodejs).

$3

`bash


Run tests in headless Chrome

wasm-pack test --headless --chrome

Run tests in headless Firefox

wasm-pack test --headless --firefox
``

License

Apache-2.0

Documentation

For complete documentation including advanced usage, framework integration, and API details, see the full documentation.

Links

- GitHub Repository
- Full Documentation
- Online Playground
- JSONLogic Specification