servus 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af1900cb767ad43568bf7e2c8c14a98bebc479a9b3ec0cc5d76d5ed3c13c5289
-  data.tar.gz: d75379a7b744f9ae6d4938c9f21601af02dbedfe7befbd3b748410aff8b6e7d9
+  metadata.gz: f1094a06fd6195a99ef33f849a6ea30e6ec1a539eeb7ef73e7c27d1d4ac411bf
+  data.tar.gz: f6891749189216f6391396d79a29fd695fc3da5ff7647691318a90929781a90a
 SHA512:
-  metadata.gz: 011756b6fc695253bca1cedd31c4f3be14426305ed1d698f1e8963f62734a7ceb19dab0f77c75892b6aef326ce04d2ce6d07b22f97c9622131988ff4c24b9989
-  data.tar.gz: 04d948bd35038d768f0786ec253c771c50abc4e8d95d85b39bb2a573b411ee5e4486daec6b460548562e1a87fc5b7b4b3a47ddf2a27105d3ecb3cedd6f09c779
+  metadata.gz: 02e57566af4b419281991b2b0a361010dd7eff9f7d061c226e32153292d60c060e58781099eee1113d8eab678859164a09be26b1ad790dea47ba0e7f2bfe4275
+  data.tar.gz: 2cfd4e9ae6f71bb051b61f2ea7b4315fef58289ffaf610f21669d6f6c98cd635479502a22af3819aa0a41eb3aed6b8de9972e74e8311a7e619fa09cf82c66ff9

data/.claude/commands/check-docs.md

@@ -0,0 +1 @@
+Scan the documentation in docs/ then check the current git changeset. If the changeset has modifications that might affect the documentation, then review the related documentation and make any necessary updates.

data/.claude/commands/consistency-check.md

@@ -0,0 +1 @@
+Are the latest changes consistent with the way that similar functionality has been implemented in the rest of the codebase? #$ARGUMENTS

data/.claude/commands/fine-tooth-comb.md

@@ -0,0 +1 @@
+We're going to go over #$ARGUMENTS with a fine-tooth comb. I want detailed explanations and no edits unless I ask for them. Start by identifying the first thing that looks wrong and explain why.

data/.claude/commands/red-green-refactor.md

@@ -0,0 +1,5 @@
+During this session we will be practicing TDD in the red-green-refactor cycle. The first step in the cycle is to write a test for the smallest possible unit of functionality. Once the test is written, run the test and it should fail. This is the red phase. The next step is to write the code to make the test pass. This is the green phase. Once the test passes, the code is refactored to be more readable and maintainable. This is the refactor phase.
+
+If we get into a situation where more than one test fails, we will focus on the test that is most important to fix first. During that fix phase, we will only run the test that is failing until it passes.
+
+While we're in this mode, you will not use your TODO tool to track tasks. You will rely on me (the human user) to tell you what the next step is.

data/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bundle exec rubocop -A"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.rubocop.yml

@@ -1,11 +1,27 @@
 AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
   Include:
     - 'lib/**/*.rb'
     - 'spec/**/*.rb'
+  Exclude:
+    - 'spec/dummy/**/*'
+    - 'vendor/bundle/**/*'
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/ConstantReassignment:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/MissingSuper:
+  Exclude:
+    - 'spec/**/*'
 
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
 
-Lint/ConstantDefinitionInBlock:
-  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 ## [Unreleased]
 
+## [0.1.5] - 2025-12-03
+
+### Added
+
+- **Event Bus Architecture**: Introduced event-driven architecture for decoupling service logic from side effects
+  - `Servus::EventHandler` base class for creating event handlers that subscribe to events and invoke services
+  - `emits` DSL on `Servus::Base` for declaring events that fire on `:success`, `:failure`, or `:error!`
+  - `Servus::Events::Bus` for routing events to handlers via ActiveSupport::Notifications
+  - Rails generator: `rails g servus:event_handler event_name` creates handler and spec files
+  - Event handlers auto-load from `app/events/` directory in Rails applications
+
+- **Event Payload Validation**: JSON Schema validation for event payloads
+  - `schema payload: {...}` DSL on EventHandler for declaring payload schemas
+  - Validation occurs when events are emitted via `EventHandler.emit(payload)`
+
+- **Event Testing Matchers**: RSpec matchers for testing event emission
+  - `emit_event(:event_name)` matcher to assert events are emitted
+  - `emit_event(:event_name).with(payload)` for payload assertions
+  - `call_service(ServiceClass).with(args)` matcher for handler testing
+  - `call_service(ServiceClass).async` for async invocation testing
+
+- **Configuration Options**: New and updated configuration settings
+  - `config.schemas_dir` - Directory for JSON schema files (default: `app/schemas`)
+  - `config.services_dir` - Directory for service files (default: `app/services`)
+  - `config.events_dir` - Directory for event handlers (default: `app/events`)
+  - `config.strict_event_validation` - Validate handlers subscribe to emitted events (default: `true`)
+  - `Servus::EventHandler.validate_all_handlers!` for CI validation of handler-event mappings
+
+- **Generator Improvements**: Enhanced service and event handler generators
+  - Service templates now include comprehensive YARD documentation
+  - Service spec templates include example test patterns
+  - JSON schema templates include proper structure with `$schema` reference
+  - Event handler templates include full documentation and examples
+  - `--no-docs` flag to skip documentation comments in generated files
+
+### Changed
+
+- Updated execution flow to include event emission after result validation
+- Enhanced Railtie to auto-load event handlers and clear the event bus on reload in development
+
 ## [0.1.4] - 2025-11-21
 - Added: Test helpers (`servus_arguments_example` and `servus_result_example`) to extract example values from schemas for testing
 - Added: YARD documentation configuration with README homepage and markdown file support

data/CLAUDE.md

@@ -0,0 +1,10 @@
+Before starting a session, always review the latest docs in the following order:
+
+1. `/docs/core/**/*.md`
+2. `/docs/features/**/*.md`
+3. `/docs/guides/**/*.md`
+4. `/docs/integration/**/*.md`
+
+Focus on writing code consistent with the rest of the project. Use existing files as references for conventions and style.
+
+Ensure new code always encludes world class YARD documentation. If documentation looks out of date or incomplete, suggest a relevant edit.

data/IDEAS.md

@@ -2,4 +2,4 @@
 
 2. Improve error handling with an error registry that can be referenced by codes as opposed to fully qualified class names.
 
-3. Mock result objects from schema defaults
+3. Update generators to not make schema files and instead add schemas to schema: method in generators.

data/READme.md

@@ -1,5 +1,6 @@
 ## Servus Gem
 
+
 Servus is a gem for creating and managing service objects. It includes:
 
 - A base class for service objects
@@ -7,8 +8,9 @@ Servus is a gem for creating and managing service objects. It includes:
 - Support for schema validation
 - Support for error handling
 - Support for logging
+- Event-driven architecture with EventHandlers
 
-
+👉🏽 [View the docs](https://zarpay.github.io/servus/)
 
 ## Generators
 
@@ -119,10 +121,6 @@ end
 
 ```
 
-Here’s a section you can add to your README for the new `.call_async` feature, matching the style of your existing `## Inheritance` section:
-
----
-
 ## **Asynchronous Execution**
 
 You can asynchronously execute any service class that inherits from `Servus::Base` using `.call_async`. This uses `ActiveJob` under the hood and supports standard job options (`wait`, `queue`, `priority`, etc.). Only available in environments where `ActiveJob` is loaded (e.g., Rails apps)
@@ -601,3 +599,153 @@ Without explicit configuration:
 - **Non-Rails applications**: Schema root defaults to `./app/schemas/services` relative to the gem installation
 
 The configuration is accessed through the singleton `Servus.config` instance and can be modified using `Servus.configure`.
+
+## **Event Bus**
+
+Servus includes an event-driven architecture for decoupling service logic from side effects. Services emit events, and EventHandlers subscribe to them and invoke downstream services.
+
+### Emitting Events from Services
+
+Services can declare events that are emitted on success or failure:
+
+```ruby
+class CreateUser::Service < Servus::Base
+  emits :user_created, on: :success
+  emits :user_creation_failed, on: :failure
+
+  def initialize(email:, name:)
+    @email = email
+    @name = name
+  end
+
+  def call
+    user = User.create!(email: @email, name: @name)
+    success(user: user)
+  rescue ActiveRecord::RecordInvalid => e
+    failure(e.message)
+  end
+end
+```
+
+Custom payloads can be provided via blocks or method references:
+
+```ruby
+emits :user_created, on: :success do |result|
+  { user_id: result.data[:user].id, email: result.data[:user].email }
+end
+```
+
+### Event Handlers
+
+EventHandlers subscribe to events and invoke services in response. They live in `app/events/`:
+
+```ruby
+# app/events/user_created_handler.rb
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id], email: payload[:email] }
+  end
+
+  invoke TrackAnalytics::Service, async: true do |payload|
+    { event: 'user_created', user_id: payload[:user_id] }
+  end
+end
+```
+
+### Generate Event Handler
+
+```bash
+$ rails g servus:event_handler user_created
+=>    create  app/events/user_created_handler.rb
+      create  spec/events/user_created_handler_spec.rb
+```
+
+### Invocation Options
+
+```ruby
+# Synchronous (default)
+invoke NotifyAdmin::Service do |payload|
+  { message: "New user: #{payload[:email]}" }
+end
+
+# Async via ActiveJob
+invoke SendEmail::Service, async: true do |payload|
+  { user_id: payload[:user_id] }
+end
+
+# Async with specific queue
+invoke SendEmail::Service, async: true, queue: :mailers do |payload|
+  { user_id: payload[:user_id] }
+end
+
+# Conditional invocation
+invoke GrantRewards::Service, if: ->(p) { p[:premium] } do |payload|
+  { user_id: payload[:user_id] }
+end
+```
+
+### Emitting Events Directly
+
+EventHandlers provide an `emit` class method for emitting events from controllers, jobs, or other code:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    user = User.create!(user_params)
+    UserCreatedHandler.emit({ user_id: user.id, email: user.email })
+    redirect_to user
+  end
+end
+```
+
+### Payload Schema Validation
+
+Define JSON schemas to validate event payloads:
+
+```ruby
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  schema payload: {
+    type: 'object',
+    required: ['user_id', 'email'],
+    properties: {
+      user_id: { type: 'integer' },
+      email: { type: 'string', format: 'email' }
+    }
+  }
+
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id], email: payload[:email] }
+  end
+end
+```
+
+### Testing Events
+
+Servus provides RSpec matchers for testing events:
+
+```ruby
+# Test that a service emits an event
+it 'emits user_created event' do
+  expect {
+    CreateUser::Service.call(email: 'test@example.com', name: 'Test')
+  }.to emit_event(:user_created)
+end
+
+# Test payload content
+it 'emits event with expected payload' do
+  expect {
+    CreateUser::Service.call(email: 'test@example.com', name: 'Test')
+  }.to emit_event(:user_created).with(hash_including(email: 'test@example.com'))
+end
+
+# Test handler invokes service
+it 'invokes SendWelcomeEmail' do
+  expect {
+    UserCreatedHandler.handle(payload)
+  }.to call_service(SendWelcomeEmail::Service).with(user_id: 123)
+end
+```

data/docs/core/2_architecture.md

@@ -7,12 +7,12 @@ Servus wraps service execution with automatic validation, logging, and error han
 ## Execution Flow
 
 ```
-Arguments → Validation → Service#call → Result Validation → Logging → Response
-                ↓                              ↓                ↓
-          ValidationError                ValidationError     Benchmark
+Arguments → Validation → Service#call → Result Validation → Event Emission → Logging → Response
+                ↓                              ↓                   ↓              ↓
+          ValidationError                ValidationError      EventHandlers   Benchmark
 ```
 
-The framework intercepts the `.call` class method to inject cross-cutting concerns before and after your business logic runs. Your `call` instance method contains only business logic - validation, logging, and timing happen automatically.
+The framework intercepts the `.call` class method to inject cross-cutting concerns before and after your business logic runs. Your `call` instance method contains only business logic - validation, logging, event emission, and timing happen automatically.
 
 ## Core Components
 
@@ -28,6 +28,12 @@ The framework intercepts the `.call` class method to inject cross-cutting concer
 
 **Support::Errors** (`lib/servus/support/errors.rb`): HTTP-aligned error hierarchy (ServiceError, NotFoundError, ValidationError, etc.)
 
+**Events::Emitter** (`lib/servus/events/emitter.rb`): DSL for declaring events that services emit on success/failure
+
+**Events::Bus** (`lib/servus/events/bus.rb`): Central event router using ActiveSupport::Notifications for thread-safe dispatch
+
+**EventHandler** (`lib/servus/event_handler.rb`): Base class for handlers that subscribe to events and invoke services
+
 ## Extension Points
 
 ### Schema Validation
@@ -84,6 +90,28 @@ ProcessPayment::Service.call_async(
 )
 ```
 
+## Event-Driven Architecture
+
+Services can emit events that trigger downstream handlers. This decouples services from their side effects.
+
+```ruby
+# Service emits events
+class CreateUser::Service < Servus::Base
+  emits :user_created, on: :success
+end
+
+# Handler reacts to events
+class UserCreatedHandler < Servus::EventHandler
+  handles :user_created
+
+  invoke SendWelcomeEmail::Service, async: true do |payload|
+    { user_id: payload[:user_id] }
+  end
+end
+```
+
+See {file:docs/features/5_event_bus.md Event Bus} for full documentation.
+
 ## Performance
 
 - Schema loading: Cached per class after first use