JSONLogic Explainer

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

Installation

``bash
npm install jsonlogic-explainer


or

yarn add jsonlogic-explainer

or

pnpm add jsonlogic-explainer
`

Usage

$3

`typescript
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"
`

$3

You can customize the explainer with options:

`typescript
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:

$3

- +: 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")

$3

- ==: 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")

$3

- 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")

$3

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

$3

- 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

$3

- 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")

$3

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

API Reference

$3

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

#### Constructor

`typescript
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