JSONLogic Explainer

A library to convert JSONLogic expressions into human-readable explanations.

Installation

npm install jsonlogic-explainer
# or
yarn add jsonlogic-explainer
# or
pnpm add jsonlogic-explainer

Usage

Basic Usage

import { JsonLogicExplainer } from "jsonlogic-explainer";

const explainer = new JsonLogicExplainer();

// Simple equality check
const expression1 = { "===": [{ var: "age" }, 18] };
console.log(explainer.explain(expression1));
// Output: "age equals 18"

// Conditional logic
const expression2 = { if: [{ ">": [{ var: "age" }, 18] }, "adult", "minor"] };
console.log(explainer.explain(expression2));
// Output: "if age is greater than 18 then adult else minor"

// Complex nested operations
const expression3 = {
  and: [
    { ">": [{ var: "age" }, 18] },
    {
      or: [
        { "==": [{ var: "status" }, "active"] },
        { "==": [{ var: "status" }, "pending"] },
      ],
    },
  ],
};
console.log(explainer.explain(expression3));
// Output: "age is greater than 18 and status equals active or status equals pending"

Advanced Usage

You can customize the explainer with options:

const explainer = new JsonLogicExplainer({
  variableNames: {
    age: "customer age",
    status: "account status",
  },
  data: {
    // Optional: data context for variable evaluation
  },
});

const expression = { "===": [{ var: "age" }, 18] };
console.log(explainer.explain(expression));
// Output: "customer age equals 18"

Supported JSONLogic Operations

The library supports all major JSONLogic operations:

Arithmetic Operations

• +: Addition (e.g., [2, 3, 4] → "2 plus 3 plus 4")
• -: Subtraction (e.g., [10, 5, 3] → "10 minus 5 minus 3")
• *: Multiplication (e.g., [2, 3, 4] → "2 times 3 times 4")
• /: Division (e.g., [15, 3, 2] → "15 divided by 3 divided by 2")
• %: Modulo (e.g., [10, 3] → "10 modulo 3")
• abs: Absolute value (e.g., [-5] → "absolute value of -5")
• max: Maximum value (e.g., [1, 5, 3] → "maximum of 1, 5, 3")
• min: Minimum value (e.g., [1, 5, 3] → "minimum of 1, 5, 3")

Comparison Operations

• ==: Loose equality (e.g., ["hello", "hello"] → "hello equals hello")
• ===: Strict equality (e.g., [18, 18] → "18 equals 18")
• !=: Loose inequality (e.g., ["hello", "world"] → "hello does not equal world")
• !==: Strict inequality (e.g., [18, "18"] → "18 does not strictly equal 18")
• >: Greater than (e.g., [10, 5] → "10 is greater than 5")
• >=: Greater than or equal (e.g., [10, 10] → "10 is greater than or equal to 10")
• <: Less than (e.g., [5, 10] → "5 is less than 10")
• <=: Less than or equal (e.g., [5, 5] → "5 is less than or equal to 5")
• in: Value in collection (e.g., ["Ringo", ["John", "Paul", "George", "Ringo"]] → "Ringo in John, Paul, George, Ringo")

Logical Operations

• and: Logical AND (e.g., [true, false, true] → "true and false and true")
• or: Logical OR (e.g., [false, true, false] → "false or true or false")
• !, not: Logical NOT (e.g., true → "not true")

Conditional Operations

• if: If-then-else logic (e.g., [condition, "then", "else"] → "if condition then then else else")

Array Operations

• map: Apply operation to each element
• filter: Filter elements based on condition
• reduce: Reduce array to single value
• all: Check if all elements satisfy condition
• none: Check if no elements satisfy condition
• some: Check if some elements satisfy condition
• merge: Merge arrays
• in: Check if value exists in array

String Operations

• cat: Concatenate strings (e.g., ["Hello", " ", "World"] → "Hello World")
• substr: Extract substring (e.g., ["Hello World", 0, 5] → "substring of Hello World from 0 with length 5")

Variable Operations

• var: Access variables from context (e.g., "age" → "age", ["age", 0] → "age with default value of 0")

API Reference

JsonLogicExplainer

Main class for converting JSONLogic expressions to human-readable text.

Constructor

new JsonLogicExplainer(options?: JsonLogicExplainerOptions)

Options:

• variableNames: Mapping of variable keys to human-readable names
• operatorNames: Custom operator descriptions (not currently implemented)
• includeJsonLogic: Whether to include the original JSONLogic in output (not currently implemented)
• data: Data context for variable evaluation (not currently implemented)

explain(expression: JsonLogicExpression): string

Converts a JSONLogic expression to a human-readable string.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: pnpm test
6. Submit a pull request

License

MIT