philiprehberger-rule_engine 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1531d969d2e58539f6f31038b21c7f7e8f3c4fe4f95c6eadb13d4161c9ad7c88
-  data.tar.gz: 292d0874c8a64d66a491a0e066a2ceac66c3e65dffad26089b4a6d667ff7370e
+  metadata.gz: 48759336967f009c48193bd19ba3abc3edf2c45712e21f18bbc3382b50ce2c19
+  data.tar.gz: 2894eca7b2c22440eb52c0920ae3edcb1642ada7193668f3e2d01213c6d0f560
 SHA512:
-  metadata.gz: f247a8f155ab5d05f061ae5d67f77ce87696f74aee2753f3dccc6e21fac594772e9999cf40fbda28b53e96c8a6fcc6456b04821086ad4f43ff02ca9efa277f17
-  data.tar.gz: 9866f9b3968839a76851a77e8575faf3a3d0892c527ce10e7e505dd14fb790877f5c9d4386210df59f09f3eec958eddffcab12fc80a82b8bb407b5f85b9db836
+  metadata.gz: 0f1df77fa3a9caa8dc480eeb6cdb9c2010806f2b57108b8c4fde06b60830c853387918d225d48584d56cca89aeb2e790eee245ef0081debe6f9b8af723b3fa47
+  data.tar.gz: 9cd80a35da5092a44dd170965cd508faed0d3aba1d25a4005a91af5da037dff4a2e41cf9e54cb4995533e7240f4dd47155c5c26259d495d238f0eb41fd8bb9ee

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+### Added
+- `engine.to_h` and `RuleEngine.from_h` for rule configuration serialization
+- Composite condition helpers: `all?`, `any?`, `none?` for readable logic
+- `engine.stats` for per-rule execution statistics with timing
+- Dynamic rule management: `add_rule`, `remove_rule`, `disable_rule`, `enable_rule`
+- `engine.chain(*rule_names)` for sequential rule pipelines
+
 ## [0.1.2] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -2,7 +2,12 @@
 
 [![Tests](https://github.com/philiprehberger/rb-rule-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-rule-engine/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-rule_engine.svg)](https://rubygems.org/gems/philiprehberger-rule_engine)
+[![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-rule-engine)](https://github.com/philiprehberger/rb-rule-engine/releases)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-rule-engine)](https://github.com/philiprehberger/rb-rule-engine/commits/main)
 [![License](https://img.shields.io/github/license/philiprehberger/rb-rule-engine)](LICENSE)
+[![Bug Reports](https://img.shields.io/github/issues/philiprehberger/rb-rule-engine/bug)](https://github.com/philiprehberger/rb-rule-engine/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+[![Feature Requests](https://img.shields.io/github/issues/philiprehberger/rb-rule-engine/enhancement)](https://github.com/philiprehberger/rb-rule-engine/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ec6cb9)](https://github.com/sponsors/philiprehberger)
 
 Lightweight rule engine with declarative conditions and actions
 
@@ -15,7 +20,7 @@ Lightweight rule engine with declarative conditions and actions
 Add to your Gemfile:
 
 ```ruby
-gem "philiprehberger-rule_engine"
+gem 'philiprehberger-rule_engine'
 ```
 
 Or install directly:
@@ -27,7 +32,7 @@ gem install philiprehberger-rule_engine
 ## Usage
 
 ```ruby
-require "philiprehberger/rule_engine"
+require 'philiprehberger/rule_engine'
 
 engine = Philiprehberger::RuleEngine.new do
   rule 'discount' do
@@ -84,6 +89,100 @@ results = engine.evaluate({ tier: 'premium' })
 # => [{ rule: 'premium', result: { discount: 0.20 } }]
 ```
 
+### Composite Conditions
+
+```ruby
+engine = Philiprehberger::RuleEngine.new do
+  rule 'access' do
+    condition { |f| all?(f[:active], any?(f[:admin], f[:moderator])) }
+    action { |_| 'granted' }
+  end
+
+  rule 'blocked' do
+    condition { |f| none?(f[:verified], f[:trusted]) }
+    action { |_| 'denied' }
+  end
+end
+```
+
+### Dynamic Rule Management
+
+```ruby
+engine = Philiprehberger::RuleEngine.new
+
+engine.add_rule('dynamic') do
+  condition { |f| f[:ready] }
+  action { |_| 'go' }
+end
+
+engine.disable_rule('dynamic')
+engine.evaluate({ ready: true })  # => []
+
+engine.enable_rule('dynamic')
+engine.evaluate({ ready: true })  # => [{ rule: 'dynamic', result: 'go' }]
+
+engine.remove_rule('dynamic')
+```
+
+### Rule Chaining
+
+```ruby
+engine = Philiprehberger::RuleEngine.new do
+  rule 'fetch' do
+    action { |_| 10 }
+  end
+
+  rule 'double' do
+    action { |f| f[:input] * 2 }
+  end
+
+  rule 'format' do
+    action { |f| "Result: #{f[:input]}" }
+  end
+end
+
+engine.chain('fetch', 'double', 'format')
+# => 'Result: 20'
+```
+
+### Execution Statistics
+
+```ruby
+engine = Philiprehberger::RuleEngine.new do
+  rule 'tracked' do
+    condition { |_| true }
+    action { |_| 'ok' }
+  end
+end
+
+3.times { engine.evaluate({}) }
+
+engine.stats
+# => { 'tracked' => { evaluations: 3, matches: 3, executions: 3, avg_time: 0.00001, last_triggered: <Time> } }
+
+engine.reset_stats!
+```
+
+### Serialization
+
+```ruby
+engine = Philiprehberger::RuleEngine.new(mode: :first) do
+  rule 'alpha' do
+    priority 1
+    condition { |_| true }
+    action { |_| 'go' }
+  end
+end
+
+data = engine.to_h
+# => { mode: :first, rules: [{ name: 'alpha', priority: 1, enabled: true }] }
+
+restored = Philiprehberger::RuleEngine.from_h(data) do |r|
+  r.condition { |_| true }
+  r.action { |_| 'restored' }
+end
+```
+
 ## API
 
 ### `Engine`
@@ -91,10 +190,19 @@ results = engine.evaluate({ tier: 'premium' })
 | Method | Description |
 |--------|-------------|
 | `.new(mode:) { }` | Create engine with rule definitions |
+| `.from_h(data, &resolver)` | Reconstruct engine from serialized hash |
 | `#rule(name) { }` | Define a rule with condition and action |
 | `#evaluate(facts)` | Evaluate rules against facts |
 | `#rules` | Array of registered rules |
 | `#mode` | Current evaluation mode |
+| `#to_h` | Serialize engine configuration to hash |
+| `#add_rule(name) { }` | Add a rule after engine creation |
+| `#remove_rule(name)` | Remove a rule by name |
+| `#disable_rule(name)` | Disable a rule (skipped during evaluation) |
+| `#enable_rule(name)` | Re-enable a disabled rule |
+| `#chain(*rule_names)` | Execute rules sequentially as a pipeline |
+| `#stats` | Per-rule execution statistics |
+| `#reset_stats!` | Clear all execution statistics |
 
 ### Rule DSL
 
@@ -104,6 +212,14 @@ results = engine.evaluate({ tier: 'premium' })
 | `action { \|facts\| }` | Set the action to execute |
 | `priority(n)` | Set priority (lower runs first) |
 
+### Composite Condition Helpers
+
+| Method | Description |
+|--------|-------------|
+| `all?(*conditions)` | True if all conditions are truthy |
+| `any?(*conditions)` | True if any condition is truthy |
+| `none?(*conditions)` | True if no conditions are truthy |
+
 ## Development
 
 ```bash
@@ -112,6 +228,12 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+- [Bug Reports](https://github.com/philiprehberger/rb-rule-engine/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+- [Feature Requests](https://github.com/philiprehberger/rb-rule-engine/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+- [GitHub Sponsors](https://github.com/sponsors/philiprehberger)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/rule_engine/engine.rb

@@ -4,6 +4,8 @@ module Philiprehberger
   module RuleEngine
     # A lightweight rule engine with declarative conditions and actions.
     class Engine
+      include Helpers
+
       # @return [Array<Rule>] the registered rules
       attr_reader :rules
 
@@ -15,10 +17,11 @@ module Philiprehberger
       # @param mode [Symbol] :all to run all matching rules, :first to stop after first match
       # @yield [engine] block for defining rules using the DSL
       def initialize(mode: :all, &block)
-        raise Error, "mode must be :all or :first" unless %i[all first].include?(mode)
+        raise Error, 'mode must be :all or :first' unless %i[all first].include?(mode)
 
         @rules = []
         @mode = mode
+        @stats = {}
         instance_eval(&block) if block
       end
 
@@ -31,27 +34,151 @@ module Philiprehberger
         r = Rule.new(name)
         r.instance_eval(&block) if block
         @rules << r
+        @stats[name] = new_stat_entry
         r
       end
 
+      # Add a rule after engine creation.
+      #
+      # @param name [String] the rule name
+      # @yield [rule] block for configuring the rule
+      # @return [Rule] the created rule
+      def add_rule(name, &)
+        rule(name, &)
+      end
+
+      # Remove a rule by name.
+      #
+      # @param name [String] the rule name to remove
+      # @return [Rule, nil] the removed rule, or nil if not found
+      def remove_rule(name)
+        index = @rules.index { |r| r.name == name }
+        return nil unless index
+
+        removed = @rules.delete_at(index)
+        @stats.delete(name)
+        removed
+      end
+
+      # Disable a rule by name (skipped during evaluation).
+      #
+      # @param name [String] the rule name to disable
+      # @return [void]
+      def disable_rule(name)
+        found = @rules.find { |r| r.name == name }
+        raise Error, "rule not found: #{name}" unless found
+
+        found.enabled = false
+      end
+
+      # Enable a rule by name.
+      #
+      # @param name [String] the rule name to enable
+      # @return [void]
+      def enable_rule(name)
+        found = @rules.find { |r| r.name == name }
+        raise Error, "rule not found: #{name}" unless found
+
+        found.enabled = true
+      end
+
       # Evaluate all rules against the given facts.
       #
       # @param facts [Object] the facts to evaluate
       # @return [Array<Hash>] results with :rule and :result for each matched rule
       def evaluate(facts)
-        sorted = @rules.sort_by(&:priority)
+        sorted = @rules.select(&:enabled).sort_by(&:priority)
         results = []
 
         sorted.each do |r|
+          stat = @stats[r.name] ||= new_stat_entry
+          stat[:evaluations] += 1
+
           next unless r.matches?(facts)
 
+          stat[:matches] += 1
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           result = r.execute(facts)
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+          stat[:executions] += 1
+          stat[:total_time] += elapsed
+          stat[:avg_time] = stat[:total_time] / stat[:executions]
+          stat[:last_triggered] = Time.now
+
           results << { rule: r.name, result: result }
           break if @mode == :first
         end
 
         results
       end
+
+      # Return per-rule execution statistics.
+      #
+      # @return [Hash] stats keyed by rule name
+      def stats
+        @stats.transform_values do |s|
+          {
+            evaluations: s[:evaluations],
+            matches: s[:matches],
+            executions: s[:executions],
+            avg_time: s[:avg_time],
+            last_triggered: s[:last_triggered]
+          }
+        end
+      end
+
+      # Reset all execution statistics.
+      #
+      # @return [void]
+      def reset_stats!
+        @stats.each_key { |k| @stats[k] = new_stat_entry }
+      end
+
+      # Serialize the engine configuration to a hash.
+      #
+      # @return [Hash] engine metadata including mode and rules
+      def to_h
+        {
+          mode: @mode,
+          rules: @rules.map(&:to_h)
+        }
+      end
+
+      # Execute rules sequentially as a pipeline.
+      # Each rule's action result is passed as input: to the next rule.
+      #
+      # @param rule_names [Array<String>] ordered rule names to chain
+      # @return [Object] the final action's result
+      def chain(*rule_names)
+        chain_rules = rule_names.map do |name|
+          found = @rules.find { |r| r.name == name }
+          raise Error, "rule not found: #{name}" unless found
+
+          found
+        end
+
+        input = nil
+        chain_rules.each do |r|
+          facts = { input: input }
+          input = r.execute(facts)
+        end
+
+        input
+      end
+
+      private
+
+      def new_stat_entry
+        {
+          evaluations: 0,
+          matches: 0,
+          executions: 0,
+          total_time: 0.0,
+          avg_time: 0.0,
+          last_triggered: nil
+        }
+      end
     end
   end
 end

data/lib/philiprehberger/rule_engine/helpers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module RuleEngine
+    # Composite condition helpers for readable logic in condition blocks.
+    module Helpers
+      # Returns true if all conditions are truthy.
+      #
+      # @param conditions [Array<Boolean, Proc>] values or procs to evaluate
+      # @return [Boolean]
+      def all?(*conditions)
+        conditions.all? { |c| c.is_a?(Proc) ? c.call : c }
+      end
+
+      # Returns true if any condition is truthy.
+      #
+      # @param conditions [Array<Boolean, Proc>] values or procs to evaluate
+      # @return [Boolean]
+      def any?(*conditions)
+        conditions.any? { |c| c.is_a?(Proc) ? c.call : c }
+      end
+
+      # Returns true if no conditions are truthy.
+      #
+      # @param conditions [Array<Boolean, Proc>] values or procs to evaluate
+      # @return [Boolean]
+      def none?(*conditions)
+        conditions.none? { |c| c.is_a?(Proc) ? c.call : c }
+      end
+    end
+  end
+end

data/lib/philiprehberger/rule_engine/rule.rb

@@ -4,15 +4,21 @@ module Philiprehberger
   module RuleEngine
     # A single rule with a name, condition, action, and priority.
     class Rule
+      include Helpers
+
       # @return [String] the rule name
       attr_reader :name
 
+      # @return [Boolean] whether the rule is enabled
+      attr_accessor :enabled
+
       # @param name [String] the rule name
       def initialize(name)
         @name = name
         @priority = 0
         @condition = nil
         @action = nil
+        @enabled = true
       end
 
       # Set the condition for this rule.
@@ -50,7 +56,7 @@ module Philiprehberger
       def matches?(facts)
         return false unless @condition
 
-        !!@condition.call(facts)
+        !!instance_exec(facts, &@condition)
       end
 
       # Execute the action with the given facts.
@@ -60,7 +66,18 @@ module Philiprehberger
       def execute(facts)
         return nil unless @action
 
-        @action.call(facts)
+        instance_exec(facts, &@action)
+      end
+
+      # Serialize rule metadata to a hash.
+      #
+      # @return [Hash] rule metadata (name, priority, enabled)
+      def to_h
+        {
+          name: @name,
+          priority: @priority,
+          enabled: @enabled
+        }
       end
     end
   end

data/lib/philiprehberger/rule_engine/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module RuleEngine
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/rule_engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'rule_engine/version'
+require_relative 'rule_engine/helpers'
 require_relative 'rule_engine/rule'
 require_relative 'rule_engine/engine'
 
@@ -16,5 +17,33 @@ module Philiprehberger
     def self.new(mode: :all, &block)
       Engine.new(mode: mode, &block)
     end
+
+    # Reconstruct an engine from a serialized hash.
+    # The resolver block maps rule names to condition/action implementations.
+    #
+    # @param data [Hash] serialized engine data from Engine#to_h
+    # @yield [name] block that receives a rule name and should configure the rule
+    # @return [Engine] the reconstructed engine
+    def self.from_h(data, &resolver)
+      raise Error, 'resolver block is required' unless resolver
+
+      mode = (data[:mode] || data['mode'] || :all).to_sym
+      engine = Engine.new(mode: mode)
+
+      rules = data[:rules] || data['rules'] || []
+      rules.each do |rule_data|
+        name = rule_data[:name] || rule_data['name']
+        priority_val = rule_data[:priority] || rule_data['priority'] || 0
+        enabled_val = rule_data.key?(:enabled) ? rule_data[:enabled] : rule_data.fetch('enabled', true)
+
+        r = engine.add_rule(name) do
+          priority priority_val
+        end
+        r.enabled = enabled_val
+        resolver.call(r)
+      end
+
+      engine
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-rule_engine
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-29 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight rule engine with a declarative DSL for defining conditions
   and actions. Supports priority-based ordering, first-match and all-match evaluation
@@ -24,6 +24,7 @@ files:
 - README.md
 - lib/philiprehberger/rule_engine.rb
 - lib/philiprehberger/rule_engine/engine.rb
+- lib/philiprehberger/rule_engine/helpers.rb
 - lib/philiprehberger/rule_engine/rule.rb
 - lib/philiprehberger/rule_engine/version.rb
 homepage: https://github.com/philiprehberger/rb-rule-engine