json-logic-rb 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f6841b0bb7968ba96acb42d78d167b14c9757b66f7e76a87b474a6af22958e5
+  data.tar.gz: 1c6a5520ce8de25ad8191542e2e0aeb3ce57846ef40d8bcd66ed0a061a5ed407
+SHA512:
+  metadata.gz: 6c988634418f03c386e0c53ccd5323b2566bf13679d81b15c7f22538b7179b3d6a49f9998520d5155fd36e249d0b809951cc164a11d0ae425a9e09e67cf56b2d
+  data.tar.gz: 5e8e604fd9cc6cd1c927d071478db8cc4c00d6ca5bced126fba001d481998df551c766312d91aed49800495633220df85391cad88b0e6e98c235c8a9e0dc13c3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,315 @@
+# json-logic-rb
+
+Ruby implementation of [JsonLogic](https://jsonlogic.com/) — simple and extensible.  Ships with a compliance runner for the official test suite.
+
+  <a href="#"><img alt="build" src="https://img.shields.io/github/actions/workflow/status/your-org/json-logic-rb/ci.yml?branch=main"> <a href="https://rubygems.org/gems/json-logic-rb"><img alt="rubygems" src="https://img.shields.io/gem/v/json-logic-rb"></a> <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-informational"></a>
+
+
+## Table of Contents
+- [What](#what)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [How](#how)
+  - [1) Operators (default)](#1-operators-default)
+  - [2) Lazy operators](#2-lazy--operators)
+- [Supported Built-in Operations](#supported-built-in-operations)
+  - [Accessing Data](#accessing-data)
+  - [Logic and Boolean Operations](#logic-and-boolean-operations)
+  - [Numeric Operations](#numeric-operations)
+  - [Array Operations](#array-operations)
+  - [String Operations](#string-operations)
+  - [Miscellaneous](#miscellaneous)
+- [Extending (add your own operator)](#extending-add-your-own-operator)
+- [Public Interface](#public-interface)
+- [Compliance & tests](#compliance--tests)
+- [Security](#security)
+- [License](#license)
+- [Contributing](#contributing)
+
+
+
+## What
+JsonLogic rules are JSON trees. The engine walks that tree and returns a Ruby value.
+
+
+
+
+## Install
+
+```bash
+gem install json-logic-rb
+```
+
+## Quick start
+
+```ruby
+require "json-logic-rb"
+
+rule = { "+" => [1, 2, 3] }
+
+JsonLogic.apply(rule)
+# => 6.0
+```
+
+With data:
+
+```ruby
+JsonLogic.apply({ "var" => "user.age" }, { "user" => { "age" => 42 } })
+# => 42
+```
+
+
+## How
+
+There are **two kinds of operators** in this implementation. This mapping follows the official behavior described on [jsonlogic.com](https://jsonlogic.com).
+
+### 1) Operators (default)
+
+For **operators**, the engine **evaluates all arguments first** and then calls the operator with the **resulting Ruby values**.
+This matches the reference behavior for arithmetic, comparisons, string operations, and other pure operators that do not control evaluation order.
+
+**Official docs:**
+
+-   Numeric Operations — [https://jsonlogic.com/operations.html#numeric-operations](https://jsonlogic.com/operations.html#numeric-operations)
+
+-   String Operations — [https://jsonlogic.com/operations.html#string-operations](https://jsonlogic.com/operations.html#string-operations)
+
+-   Array Operations (simple transforms like `merge`, membership `in`) — [https://jsonlogic.com/operations.html#array-operations](https://jsonlogic.com/operations.html#array-operations)
+
+
+
+
+### 2) Lazy  operators
+
+Some operators must control **whether** and **when** their arguments are evaluated.
+They implement branching, short-circuiting, or “apply a rule per item” semantics.
+For these **lazy  operators**, the engine passes **raw sub-rules** and current `data`.
+The operator then evaluates only the sub-rules it actually needs.
+
+**Groups and references:**
+
+-   **Branching / boolean control** — `if`, `?:`, `and`, `or`, `var`
+    Docs: Logic and Boolean Operations — [https://jsonlogic.com/operations.html#logic-and-boolean-operations](https://jsonlogic.com/operations.html#logic-and-boolean-operations)
+    Truthiness table used by these operators — [https://jsonlogic.com/truthy.html](https://jsonlogic.com/truthy.html)
+
+-   **Enumerable operators** — `map`, `filter`, `reduce`, `all`, `none`, `some`
+    Docs: Array Operations — [https://jsonlogic.com/operations.html#array-operations](https://jsonlogic.com/operations.html#array-operations)
+
+
+**How per-item evaluation works:**
+
+1.  The first argument is a rule that returns the list of items — evaluated **once** to a Ruby array.
+
+2.  The second argument is the per-item rule — evaluated **for each item** with that item as the **current root**.
+
+3.  For `reduce`, the current item is also available as `"current"`, and the running total as `"accumulator"` (this mirrors the reference usage in docs and tests).
+
+
+**Examples**
+```ruby
+`# filter: keep numbers >= 2
+JsonLogic.apply(
+  { "filter" => [ { "var" => "ints" }, { ">=" => [ { "var" => "" }, 2 ] } ] },
+  { "ints" => [1,2,3] }
+)
+# => [2, 3]
+
+# reduce: sum using "current" and "accumulator"
+JsonLogic.apply(
+  { "reduce" => [
+      { "var" => "ints" },
+      { "+" => [ { "var" => "accumulator" }, { "var" => "current" } ] }, 0 ]
+  },
+  { "ints" => [1,2,3,4] }
+)
+# => 10.0
+```
+
+### Why laziness matters?
+
+Lazy operators **prevent evaluation** of branches you do not need.
+If division by zero raised an error (hypothetically), lazy control would avoid it:
+
+```ruby
+# "or" short-circuits: 1 is truthy, so the right side is NOT evaluated.
+# If the right side were evaluated eagerly, it would attempt 1/0 (error).
+JsonLogic.apply({ "or" => [1, { "/" => [1, 0] }] })
+# => 1
+
+# "if" evaluates only the 'then' branch when condition is true.
+# The 'else' branch with 1/0 is never evaluated.
+JsonLogic.apply({ "if" => [true, 42, { "/" => [1, 0] }] })
+# => 42
+```
+>In this gem (library) `/` returns `nil` on divide-by-zero, but these examples show **why** lazy evaluation is required by the spec: branching and boolean operators must **not** evaluate unused branches.
+
+
+
+---
+
+##  Supported Built-in Operations
+
+Below is a checklist that mirrors the sections on [**jsonlogic.com/operations.html**](https://jsonlogic.com/operations.html) and shows what this gem (library) implements.
+
+
+### Accessing Data
+| Operator | Supported | Notes |
+|---|---:|---|
+| `var` | ✅ |  |
+| `missing` | ✅ | Returns array of missing keys; works with complex sources (e.g. `merge` result). |
+| `missing_some` | ✅ | Returns `[]` when the minimum is met, otherwise missing keys. |
+
+
+### [Logic and Boolean Operations](https://jsonlogic.com/operations.html#logic-and-boolean-operations])
+| Operator | Supported | Notes |
+|---|---:|---|
+| `if` | ✅ |  |
+| `==` | ✅ |  |
+| `===` | ✅ | Strict equality (same type and value). |
+| `!=` | ✅ |  |
+| `!==` | ✅ | |
+| `!` | ✅ | Follows JsonLogic truthiness. |
+| `!!` | ✅ | Follows JsonLogic truthiness. |
+| `or` | ✅ | Returns first truthy / last value; |
+| `and` | ✅ | Returns first falsy / last value; |
+| `?:` | ✅ | Returns the truth. |
+
+
+### [Numeric Operations](https://jsonlogic.com/operations.html#numeric-operations)
+| Operator / Topic | Supported | Notes |
+|---|---:|---|
+| `>` `>=` `<` `<=` | ✅ | |
+| Between (pattern) | ✅ | Use `<`/`<=` with 3 args (not a separate op). |
+| `max` / `min` | ✅ |  |
+| `+` `-` `*` `/` | ✅ | Unary `-` negates; unary `+` casts to number; `/` returns `nil` on divide‑by‑zero. |
+| `%` | ✅ |  |
+
+
+### [Array Operations](https://jsonlogic.com/operations.html#array-operations)
+| Operator | Supported | Notes |
+|---|---:|---|
+| `map` | ✅ | |
+| `reduce` | ✅ | Per‑item rule sees `"current"` and `"accumulator"`. |
+| `filter` | ✅ | Keeps items where per‑item rule is truthy (follows JsonLogic truthiness). |
+| `all` | ✅ | `false` on empty; all per‑item are truthy (follows JsonLogic truthiness). |
+| `none` | ✅ | `true` on empty; none per‑item are truthy (follows JsonLogic truthiness). |
+| `some` | ✅ | `false` on empty; any per‑item is truthy (follows JsonLogic truthiness). |
+| `merge` | ✅ | Flattens arguments into a single array; non‑arrays cast to singleton arrays. |
+| `in` | ✅ | If second arg is an array: membership test. |
+
+
+### [String Operations](https://jsonlogic.com/operations.html#string-operations)
+| Operator | Supported | Notes |
+|---|---:|---|
+| `in` | ✅ | If second arg is a string: substring test. |
+| `cat` | ✅ | Concatenate arguments as strings (no delimiter). |
+| `substr` | ✅ | Start index can be negative; length can be omitted or negative (mirrors the official behavior). |
+
+
+### Miscellaneous
+| Operator | Supported | Notes |
+|---|---:|---|
+| `log` | 🚫 | Not implemented by default (and not part of the compliance tests). |
+
+**Summary:** From the reference page’s list, everything except `log` is implemented.
+(“Between” is not a standalone operator, but the `<`/`<=` 3‑argument form is supported.)
+
+---
+
+## Extending (add your own operator)
+
+### Operation Type
+
+Each operator is a class.
+-  **Value operations** inherit `JsonLogic::Operation` (engine passes values).
+
+- **Lazy operations** inherit `JsonLogic::LazyOperation` (engine passes raw sub‑rules).
+
+- **Enumerable operations** inherit `JsonLogic::EnumerableOperation` (standardized data binding for per‑item rules).
+
+### Guide
+
+First, create the Class for you Operation based on it's type:
+```ruby
+class JsonLogic::Operations::StartsWith < JsonLogic::Operation
+  def self.op_name = "starts_with"  # {"starts_with": [string, prefix]}
+
+  def call((str, prefix), _data)
+    str.to_s.start_with?(prefix.to_s)
+  end
+end
+```
+
+Second, register your operation:
+```ruby
+JsonLogic::Engine.default.registry.register(JsonLogic::Operations::StartsWith)
+```
+
+Use it!
+```ruby
+rule = {
+  "if" => [
+    { "starts_with" => [ { "var" => "email" }, "admin@" ] },
+    "is_admin",
+    "regular_user"
+  ]
+}
+
+p JsonLogic.apply(rule, { "email" => "admin@example.com" })
+# => "is_admin"
+p JsonLogic.apply(rule, { "email" => "user@example.com" })
+# => "regular_user"
+```
+
+---
+
+## Public Interface
+Use the high-level facade to evaluate a JsonLogic rule against input and get a plain Ruby value back.
+If you need more control (e.g., custom operator sets or multiple engines), use `JsonLogic::Engine`
+
+
+```ruby
+# Main facade
+JsonLogic.apply(rule, data = nil)  # => value
+
+# Engine/Registry (advanced)
+engine = JsonLogic::Engine.default
+engine.evaluate(rule, data)
+
+# Register a custom op class (auto‑registration is also supported)
+engine.registry.register(JsonLogic::Operations::StartsWith)
+```
+
+---
+
+## Compliance  & tests
+Optional: quick self-test
+
+```bash
+ruby test/selftest.rb
+```
+
+Official test suite
+1. Fetch the official suite
+
+```bash
+mkdir -p spec/tmp
+curl -fsSL https://jsonlogic.com/tests.json -o spec/tmp/tests.json
+```
+2. Run it
+```bash
+ruby script/compliance.rb spec/tmp/tests.json
+```
+
+Expected output
+```bash
+# => Compliance: X/X passed
+```
+
+---
+
+## Security
+
+- Rules are **data**, not code; no Ruby eval.
+- When evaluating untrusted rules, consider adding a timeout  and error handling at the call site.
+- Custom operations should be **pure** (no IO, no network, no shell).

data/lib/json_logic/engine.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'semantics'
+
+module JsonLogic
+  class Engine
+    include Semantics
+
+    def self.default
+      @default ||= new(registry: Registry.new)
+    end
+
+    def initialize(registry:)
+      @registry = registry
+    end
+
+    attr_reader :registry
+
+    def evaluate(rule, data = nil)
+      data ||= {}
+
+      case rule
+      when Numeric,
+           String,
+           TrueClass,
+           FalseClass,
+           NilClass
+        rule
+      when Array
+        rule.map { |r| evaluate(r, data) }
+      when Hash
+        name, raw_args = rule.first
+        op_class = @registry.fetch(name)
+        raise ArgumentError, "unknown operation: #{name}" unless op_class
+
+        args =
+          case raw_args
+          when nil   then []
+          when Array then raw_args
+          else            [raw_args]
+          end
+
+        if op_class.values_only?
+          values = args.map { |a| evaluate(a, data) }
+          op_class.new.call(values, data)
+        else
+          op_class.new.call(args, data)
+        end
+      else
+        rule
+      end
+    end
+  end
+end

data/lib/json_logic/enumerable_operation.rb

@@ -0,0 +1,9 @@
+class JsonLogic::EnumerableOperation < JsonLogic::LazyOperation
+  private
+
+  def resolve_items_and_per_item_rule(rules, data)
+    rule_that_returns_items, rule_applied_to_each_item = rules
+    items = Array(JsonLogic.apply(rule_that_returns_items, data))
+    [items, rule_applied_to_each_item]
+  end
+end

data/lib/json_logic/lazy_operation.rb

@@ -0,0 +1,3 @@
+class JsonLogic::LazyOperation < JsonLogic::Operation
+  def self.values_only? = false
+end

data/lib/json_logic/operation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module JsonLogic
+  class Operation
+    def self.op_name = nil
+
+    def self.values_only? = true
+
+    # Implement in subclasses.
+    def call(args, data)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/json_logic/operations/add.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Add < JsonLogic::Operation
+  def self.op_name = "+"
+  def call(values, _data) = values.map!(&:to_f).sum
+end

data/lib/json_logic/operations/all.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::All < JsonLogic::EnumerableOperation
+  def self.op_name = "all"
+
+  def call(args, data)
+    items, rule_applied_to_each_item = resolve_items_and_per_item_rule(args, data)
+    return false if items.empty?
+
+    items.all? do |item|
+      JsonLogic::Semantics.truthy?(
+        JsonLogic.apply(rule_applied_to_each_item, item)
+      )
+    end
+  end
+end

data/lib/json_logic/operations/and.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::And < JsonLogic::LazyOperation
+  def self.op_name = "and"
+
+  def call(args, data)
+    last = nil
+    args.each do |a|
+      last = JsonLogic.apply(a, data)
+      return last unless JsonLogic::Semantics.truthy?(last)
+    end
+    last
+  end
+end

data/lib/json_logic/operations/bool_cast.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::BoolCast < JsonLogic::Operation
+  def self.op_name = "!!"
+
+  def call((a), _data)
+    JsonLogic::Semantics.truthy?(a)
+  end
+end

data/lib/json_logic/operations/cat.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Cat < JsonLogic::Operation
+  def self.op_name = "cat"
+  def call(values, _data) = values.map!(&:to_s).join
+end

data/lib/json_logic/operations/div.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Div < JsonLogic::Operation
+  def self.op_name = "/"
+  def call((a,b), _data) = (b.to_f == 0 ? nil : a.to_f / b.to_f)
+end

data/lib/json_logic/operations/equal.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Equal < JsonLogic::Operation
+  def self.op_name = "=="
+  def call((a,b), _data) = JsonLogic::Semantics.loose_equal(a,b)
+end

data/lib/json_logic/operations/filter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Filter < JsonLogic::EnumerableOperation
+  def self.op_name = "filter"
+
+  def call(args, data)
+    items, rule_applied_to_each_item = resolve_items_and_per_item_rule(args, data)
+
+    items.filter do |item|
+      JsonLogic::Semantics.truthy?(
+        JsonLogic.apply(rule_applied_to_each_item, item)
+      )
+    end
+  end
+end

data/lib/json_logic/operations/gt.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::GT < JsonLogic::Operation
+  def self.op_name = ">"
+  def call((a,b), _data) = JsonLogic::Semantics.to_number(a) > JsonLogic::Semantics.to_number(b)
+end

data/lib/json_logic/operations/gte.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::GTE < JsonLogic::Operation
+  def self.op_name = ">="
+  def call((a,b), _data) = JsonLogic::Semantics.to_number(a) >= JsonLogic::Semantics.to_number(b)
+end

data/lib/json_logic/operations/if.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::If < JsonLogic::LazyOperation
+  def self.op_name = "if"
+
+  def call(args, data)
+    i = 0
+    while i < args.size - 1
+      return JsonLogic.apply(args[i + 1], data) if JsonLogic::Semantics.truthy?(JsonLogic.apply(args[i], data))
+      i += 2
+    end
+    return JsonLogic.apply(args[-1], data) if args.size.odd?
+    nil
+  end
+end

data/lib/json_logic/operations/in_op.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::InOp < JsonLogic::Operation
+  def self.op_name = "in"
+  def call((a,b), _data) = (b.respond_to?(:include?) && b.include?(a))
+end

data/lib/json_logic/operations/lt.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::LT < JsonLogic::Operation
+  def self.op_name = "<"
+  def call(values, _data)
+    nums = values.map { |v| JsonLogic::Semantics.to_number(v) }
+    return nums[0] < nums[1] if nums.size == 2
+    nums.each_cons(2).all? { |a,b| a < b }
+  end
+end

data/lib/json_logic/operations/lte.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::LTE < JsonLogic::Operation
+  def self.op_name = "<="
+  def call(values, _data)
+    nums = values.map { |v| JsonLogic::Semantics.to_number(v) }
+    return nums[0] <= nums[1] if nums.size == 2
+    nums.each_cons(2).all? { |a,b| a <= b }
+  end
+end

data/lib/json_logic/operations/map.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Map < JsonLogic::EnumerableOperation
+  def self.op_name = "map"
+
+  def call(args, data)
+    items, rule_applied_to_each_item = resolve_items_and_per_item_rule(args, data)
+    items.map { |item| JsonLogic.apply(rule_applied_to_each_item, item) }
+  end
+end

data/lib/json_logic/operations/max.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Max < JsonLogic::Operation
+  def self.op_name = "max"
+  def call(values, _data) = values.max_by { |v| JsonLogic::Semantics.to_number(v) }
+end

data/lib/json_logic/operations/merge.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Merge < JsonLogic::Operation
+  def self.op_name = "merge"
+  def call(values, _data)
+    values.flat_map { |v| v.is_a?(Array) ? v : [v] }
+  end
+end

data/lib/json_logic/operations/min.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Min < JsonLogic::Operation
+  def self.op_name = "min"
+  def call(values, _data) = values.min_by { |v| JsonLogic::Semantics.to_number(v) }
+end

data/lib/json_logic/operations/missing.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class JsonLogic::Operations::Missing < JsonLogic::Operation
+  def self.op_name = "missing"
+
+  def call(values, data)
+    keys =
+      if values.size == 1 && values.first.is_a?(Array)
+        values.first
+      else
+        values
+      end
+
+    keys.select { |k| dig(data, k).nil? }
+  end
+
+  private
+
+  def dig(obj, path)
+    return nil if obj.nil?
+    cur = obj
+    path.to_s.split(".").each do |k|
+      if cur.is_a?(Array) && k =~ /\A\d+\z/
+        cur = cur[k.to_i]
+      elsif cur.is_a?(Hash)
+        cur = cur[k] || cur[k.to_s] || cur[k.to_sym]
+      else
+        return nil
+      end
+    end
+    cur
+  end
+end