ruby_reactor 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 778bc5305c6d1f20833819afd9ccd46f5a5b4c2c135d8e63344d6530f9a733f1
-  data.tar.gz: 32e769816eba846f419e3f31e8290b94e8ff04fe6ea71fef125bb128b3085b82
+  metadata.gz: b41cd34a4e2437fdeead7ad0b9ddeebc493f711e0cc7db8a31ab7c61f3e2be8d
+  data.tar.gz: 4179974d1156150a84ca60ef75e04b619dc9a7a2b26fefa5ef7e40beba5c8e14
 SHA512:
-  metadata.gz: 592db1d0ef94153a4ea028aa3cdeb59f7e4c73929ebec5afd5a9795a93d27a0cfb0c4bd3e135ccf1b14c0329123be6cf0905ad4a141018993832d21212754db3
-  data.tar.gz: 2fd90e47af8e26cf2d58468a1f0629fd1dc04890df0a6e1704e8d6cba5c65b1e050f10f56628c27c7c90b0545d081e33169e3bfd62f416affd761b62edeb24a0
+  metadata.gz: bc39fd70ce8a3318dbd41cd49deb4e7ebd66c084e7fb007ff5651d26cf1853c97cf32577ffda863c754328a49518b629aa41f1341398c49e43cd4e5df5070439
+  data.tar.gz: 83eddedaebfe39c7b3dad5b88eeaab15c08e11d78a8c894473ab82044047d8c392a4387674199fbb80d4542cf1698f64ce95b7448b8a8cf421ef7ca703b1cbb6

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.3"
+  ".": "0.5.4"
 }

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.4](https://github.com/arturictus/ruby_reactor/compare/v0.5.3...v0.5.4) (2026-06-18)
+
+
+### documentation
+
+* emphasize class-based steps as preferred way  ([#38](https://github.com/arturictus/ruby_reactor/issues/38)) ([0ee6234](https://github.com/arturictus/ruby_reactor/commit/0ee62346fd0c49d97c57cef780a6a7135d4253cd))
+
 ## [0.5.3](https://github.com/arturictus/ruby_reactor/compare/v0.5.2...v0.5.3) (2026-06-17)
 
 

data/README.md

@@ -52,6 +52,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Quick Start](#quick-start)
+- [Defining Steps](#defining-steps)
 - [Web Dashboard](#web-dashboard)
   - [Rails Installation](#rails-installation)
 - [Usage](#usage)
@@ -198,6 +199,60 @@ result = HelloReactor.run
 puts result.value  # => "Hello from Ruby Reactor!"
 ```
 
+> **Note:** Examples in this README use inline `step` blocks where a step is trivial. For production workflows, prefer [class-based steps](#defining-steps).
+
+## Defining Steps
+
+RubyReactor supports two ways to define step logic:
+
+| Style | Best for |
+|-------|----------|
+| **Class steps** (preferred) | Real business logic, compensation/undo, shared steps, testability |
+| **Inline blocks** | Quick prototypes, trivial one-liners, documentation examples |
+
+Whichever style you use, a step's `run` returns one of three signals — all exposed as bare helpers in both class steps and inline blocks:
+
+- **`Success(value)`** — step succeeded; `value` flows to dependent steps.
+- **`Failure(error)`** — step failed; the reactor rolls back completed steps (compensate/undo).
+- **`Skipped(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Skipping a reactor cleanly](documentation/core_concepts.md#skipping-a-reactor-cleanly).
+
+**Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
+
+```ruby
+class ReserveInventoryStep
+  include RubyReactor::Step
+
+  def self.run(arguments, context)
+    reservation_id = InventoryService.reserve(arguments[:order][:items])
+    Success(reservation_id: reservation_id)
+  end
+
+  def self.compensate(error, arguments, context)
+    InventoryService.release_partial(arguments[:order][:items])
+    Success()
+  end
+
+  def self.undo(result, arguments, context)
+    InventoryService.release(result[:reservation_id])
+    Success()
+  end
+end
+
+class OrderProcessingReactor < RubyReactor::Reactor
+  step :reserve_inventory, ReserveInventoryStep do
+    argument :order, result(:validate_order)
+  end
+end
+```
+
+**Why prefer class steps?**
+
+- **Testability** — unit-test `run`, `compensate`, and `undo` in isolation without booting the whole reactor
+- **Composability** — share the same step class across multiple reactors and compose larger workflows from small, focused units
+- **Readability** — reactor files stay orchestration-only; business logic lives in named classes instead of growing inline blocks
+
+See [Core Concepts — Step Classes](documentation/core_concepts.md#step-classes-preferred) for the full reference. Usage examples below mix class and inline steps — inline where the logic is trivial.
+
 ## Web Dashboard
 
 RubyReactor ships with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps. The dashboard is a Rack app (a [Roda](https://roda.jeremyevans.net/) application) bundled inside the gem with its pre-compiled JS/CSS assets — no extra install or asset build step is required.
@@ -237,60 +292,59 @@ You can secure the dashboard using standard Rails authentication methods (e.g.,
 
 ## Usage
 
-RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs.
+RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs. Examples in this section mix class steps with inline blocks; see [Defining Steps](#defining-steps) for guidance.
 
 ### Basic Example: User Registration
 
 ```ruby
 require 'ruby_reactor'
 
+class ValidateEmailStep
+  include RubyReactor::Step
+
+  def self.run(arguments, _context)
+    email = arguments[:email]
+    email&.include?('@') ? Success(email.strip) : Failure("Email must contain @")
+  end
+end
+
+class CreateUserStep
+  include RubyReactor::Step
+
+  def self.run(arguments, _context)
+    Success(
+      id: rand(10000),
+      email: arguments[:email],
+      password_hash: arguments[:password_hash],
+      created_at: Time.now
+    )
+  end
+
+  def self.compensate(_error, arguments, _context)
+    Notify.to(arguments[:email])
+    Success()
+  end
+end
+
 class UserRegistrationReactor < RubyReactor::Reactor
-  # Define inputs with optional validation
   input :email
   input :password
 
-  # Define steps with their dependencies
-  step :validate_email do
+  step :validate_email, ValidateEmailStep do
     argument :email, input(:email)
-
-    run do |args, context|
-      if args[:email] && args[:email].include?('@')
-        Success(args[:email].strip)
-      else
-        Failure("Email must contain @")
-      end
-    end
   end
 
   step :hash_password do
     argument :password, input(:password)
-
-    run do |args, context|
+    run do |args, _context|
       require 'digest'
-      hashed = Digest::SHA256.hexdigest(args[:password])
-      Success(hashed)
+      Success(Digest::SHA256.hexdigest(args[:password]))
     end
   end
 
-  step :create_user do
-    # Arguments can reference results from other steps
+  step :create_user, CreateUserStep do
     argument :email, result(:validate_email)
     argument :password_hash, result(:hash_password)
-
-    run do |args, context|
-      user = {
-        id: rand(10000),
-        email: args[:email],
-        password_hash: args[:password_hash],
-        created_at: Time.now
-      }
-      Success(user)
-    end
-
-    compensate do |error, args, context|
-      Notify.to(args[:email])
-      Success()
-    end
   end
 
   step :notify_user do
@@ -302,12 +356,12 @@ class UserRegistrationReactor < RubyReactor::Reactor
       Success()
     end
 
-    compensate do |error, args, context|
+    compensate do |_error, args, _context|
       Email.send("support@acme.com", "Email verification for #{args[:email]} couldn't be sent")
       Success()
     end
   end
-  # Specify which step's result to return
+
   returns :create_user
 end
 
@@ -613,14 +667,14 @@ result.success?  # true (Skipped is a Success subclass)
 result.skipped?  # true on dedup hit, false otherwise
 ```
 
-A step's `run` block can also return `RubyReactor.Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back").
+A step's `run` block can also return `Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back"). `Skipped` is a bare helper just like `Success`/`Failure` (or use the fully-qualified `RubyReactor.Skipped(...)`).
 
 ```ruby
 step :ensure_active do
   argument :user, result(:fetch_user)
-  run do |args|
-    next RubyReactor.Skipped(reason: "user_opted_out") if args[:user].opted_out?
-    RubyReactor.Success(args[:user])
+  run do |args, _ctx|
+    next Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    Success(args[:user])
   end
 end
 ```
@@ -1089,7 +1143,7 @@ end
 
 ### Testing
 
-RubyReactor provides testing utilities for RSpec. See the [Testing with RSpec](documentation/testing.md) guide for comprehensive documentation.
+RubyReactor provides testing utilities for RSpec. See the [Testing with RSpec](documentation/testing.md) guide for comprehensive documentation — including [unit-testing class-based steps](documentation/testing.md#testing-step-classes) directly.
 
 ```ruby
 RSpec.describe PaymentReactor do
@@ -1116,7 +1170,7 @@ end
 For detailed documentation, see the following guides:
 
 ### [Core Concepts](documentation/core_concepts.md)
-Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Context, and Results. Understand how steps are defined, how data flows between them, and how the context maintains state throughout execution.
+Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Context, and Results. Covers class-based steps (the preferred approach) and inline blocks, how data flows between steps, and how the context maintains state throughout execution.
 
 ### [DAG (Directed Acyclic Graph)](documentation/DAG.md)
 Deep dive into how RubyReactor manages dependencies. This guide explains how the Directed Acyclic Graph is constructed to ensure steps execute in the correct topological order, enabling automatic parallelization of independent steps.

data/lib/ruby_reactor/dsl/template_helpers.rb

@@ -19,7 +19,7 @@ module RubyReactor
         RubyReactor::Template::Element.new(map_name, path)
       end
 
-      # Make Success and Failure available in DSL contexts
+      # Make Success, Failure, and Skipped available in DSL contexts
       # rubocop:disable Naming/MethodName
       def Success(value = nil)
         # rubocop:enable Naming/MethodName
@@ -31,6 +31,12 @@ module RubyReactor
         # rubocop:enable Naming/MethodName
         RubyReactor.Failure(error)
       end
+
+      # rubocop:disable Naming/MethodName
+      def Skipped(reason: nil, **kwargs)
+        # rubocop:enable Naming/MethodName
+        RubyReactor.Skipped(reason: reason, **kwargs)
+      end
     end
   end
 end

data/lib/ruby_reactor/step.rb

@@ -15,6 +15,10 @@ module RubyReactor
       def Failure(error = nil)
         RubyReactor::Failure(error)
       end
+
+      def Skipped(reason: nil, **kwargs)
+        RubyReactor.Skipped(reason: reason, **kwargs)
+      end
       # rubocop:enable Naming/MethodName
 
       def run(arguments, context)

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Artur