servus 0.3.0 → 0.4.0

data/docs/guides/2_migration_guide.md

@@ -1,225 +0,0 @@
-# @title Guides / 2. Migration Guide
-
-# Migration Guide
-
-Strategies for adopting Servus in existing Rails applications, and version-specific migration notes.
-
-## Migrating to 0.3.0
-
-### Breaking: `result.data` is no longer guaranteed nil on failure
-
-In 0.2.x, `failure()` always set `result.data` to `nil`. Some code relied on this to distinguish success from failure:
-
-```ruby
-# ❌ Unsafe in 0.3.0 — result.data can be non-nil on failure
-if result.data
-  # handle success
-else
-  # handle failure
-end
-```
-
-In 0.3.0, `failure()` accepts an optional `data:` kwarg, so failure responses can carry structured data. Use `result.success?` or `result.failure?` instead:
-
-```ruby
-# ✅ Correct — always use success? or failure?
-if result.success?
-  render json: result.data, status: :ok
-else
-  render json: { error: result.error.api_error, details: result.data }, status: result.error.http_status
-end
-```
-
-**How to find affected code**: Search your codebase for patterns like `if result.data`, `result.data.present?`, or `result.data.nil?` used as success/failure checks. Replace them with `result.success?` or `result.failure?`.
-
-### Removed: `Response#with_data`
-
-`with_data` was removed in favor of the `data:` kwarg on `failure()`:
-
-```ruby
-# ❌ 0.2.x — no longer available
-failure("Declined").tap { |r| r.with_data(reason: "insufficient_funds") }
-
-# ✅ 0.3.0
-failure("Declined", data: { reason: "insufficient_funds" })
-```
-
-### New: DataObject wrapping
-
-Response data is now wrapped in a `DataObject` when it is a Hash. This is backwards compatible — `result.data[:key]` still works. You can also use accessor-style access:
-
-```ruby
-result.data[:user]       # still works
-result.data.user         # also works (new)
-result.data.user.email   # nested access (new)
-```
-
-## Incremental Adoption
-
-Servus coexists with existing code - no need to rewrite your entire application. Start with one complex use case, validate the pattern works for your team, then expand gradually.
-
-## Extracting from Fat Controllers
-
-Identify controller actions with complex business logic and extract to services:
-
-**Before**:
-```ruby
-class OrdersController < ApplicationController
-  def create
-    # 50 lines of business logic
-    # Multiple model operations
-    # External API calls
-    # Email sending
-  end
-end
-```
-
-**After**:
-```ruby
-class OrdersController < ApplicationController
-  def create
-    result = Orders::Create::Service.call(order_params)
-    if result.success?
-      render json: { order: result.data[:order] }, status: :created
-    else
-      render json: { error: result.error.api_error }, status: :unprocessable_entity
-    end
-  end
-end
-
-# Or use the helper
-class OrdersController < ApplicationController
-  include Servus::Helpers::ControllerHelpers
-
-  def create
-    run_service(Orders::Create::Service, order_params) do |result|
-      render json: { order: result.data[:order] }, status: :created
-    end
-  end
-end
-```
-
-## Extracting from Fat Models
-
-Move orchestration logic from models to services. Keep data-related methods in models:
-
-**Before**:
-```ruby
-class Order < ApplicationRecord
-  def complete_purchase
-    charge_payment
-    update_inventory
-    send_confirmation_email
-    create_invoice
-  end
-end
-```
-
-**After**:
-```ruby
-class Order < ApplicationRecord
-  # Model focuses on data
-  validates :total, presence: true
-  belongs_to :user
-end
-
-class Orders::CompletePurchase::Service < Servus::Base
-  # Service handles orchestration
-  def initialize(order_id:)
-    @order_id = order_id
-  end
-
-  def call
-    order = Order.find(@order_id)
-    Payments::Charge::Service.call(order_id: order.id)
-    Inventory::Update::Service.call(order_id: order.id)
-    Mailers::SendConfirmation::Service.call(order_id: order.id)
-    success(order: order)
-  end
-end
-```
-
-## Replacing Callbacks
-
-Extract callback logic to explicit service calls:
-
-**Before**:
-```ruby
-class User < ApplicationRecord
-  after_create :send_welcome_email
-  after_create :create_default_account
-  after_update :notify_changes, if: :email_changed?
-end
-```
-
-**After**:
-```ruby
-class User < ApplicationRecord
-  # Minimal or no callbacks
-end
-
-class Users::Create::Service < Servus::Base
-  def call
-    user = User.create!(params)
-    send_welcome_email(user)
-    create_default_account(user)
-    success(user: user)
-  end
-end
-```
-
-## Migrating Background Jobs
-
-Extract job logic to services, call via `.call_async`:
-
-**Before**:
-```ruby
-class ProcessOrderJob < ApplicationJob
-  def perform(order_id)
-    # 50 lines of business logic
-  end
-end
-
-ProcessOrderJob.perform_later(order.id)
-```
-
-**After**:
-```ruby
-class Orders::Process::Service < Servus::Base
-  def initialize(order_id:)
-    @order_id = order_id
-  end
-
-  def call
-    # Business logic
-  end
-end
-
-Orders::Process::Service.call_async(order_id: order.id)
-```
-
-Now the service can be called synchronously (from console, tests) or asynchronously (from controllers, jobs).
-
-## Testing During Migration
-
-Keep existing tests working while adding service tests:
-
-```ruby
-# Keep existing controller test
-describe OrdersController do
-  it "creates order" do
-    post :create, params: params
-    expect(response).to be_successful
-  end
-end
-
-# Add service test
-describe Orders::Create::Service do
-  it "creates order" do
-    result = described_class.call(params)
-    expect(result.success?).to be true
-  end
-end
-```
-
-Remove legacy tests after service tests prove comprehensive.

data/docs/integration/1_configuration.md

@@ -1,154 +0,0 @@
-# @title Integration / 1. Configuration
-
-# Configuration
-
-Servus works without configuration. Optional settings exist for customizing directories and event validation.
-
-## Directory Configuration
-
-Configure where Servus looks for schemas, services, event handlers, and guards:
-
-```ruby
-# config/initializers/servus.rb
-Servus.configure do |config|
-  # Default: 'app/schemas'
-  config.schemas_dir = 'app/schemas'
-
-  # Default: 'app/services'
-  config.services_dir = 'app/services'
-
-  # Default: 'app/events'
-  config.events_dir = 'app/events'
-
-  # Default: 'app/guards'
-  config.guards_dir = 'app/guards'
-end
-```
-
-These affect legacy file-based schemas, handler auto-loading, and guard auto-loading. Schemas defined via the `schema` DSL method do not use files.
-
-## Schema Cache
-
-Schemas are cached after first load for performance. Clear the cache during development when schemas change:
-
-```ruby
-Servus::Support::Validator.clear_cache!
-```
-
-In production, schemas are deployed with code - no need to clear cache.
-
-## Log Level
-
-Servus uses `Rails.logger` (or stdout in non-Rails apps). Control logging via Rails configuration:
-
-```ruby
-# config/environments/production.rb
-config.log_level = :info  # Hides DEBUG argument logs
-```
-
-## ActiveJob Configuration
-
-Async execution uses ActiveJob. Configure your adapter:
-
-```ruby
-# config/application.rb
-config.active_job.queue_adapter = :sidekiq
-config.active_job.default_queue_name = :default
-```
-
-Servus respects ActiveJob queue configuration - no Servus-specific setup needed.
-
-## Guards Configuration
-
-### Default Guards
-
-Servus includes built-in guards (`PresenceGuard`, `TruthyGuard`, `FalseyGuard`, `StateGuard`) that are loaded by default. Disable them if you want to define your own:
-
-```ruby
-# config/initializers/servus.rb
-Servus.configure do |config|
-  # Default: true
-  config.include_default_guards = false
-end
-```
-
-### Guard Auto-Loading
-
-In Rails, custom guards in `app/guards/` are automatically loaded. The Railtie eager-loads all `*_guard.rb` files from `config.guards_dir`:
-
-```
-app/guards/
-├── sufficient_balance_guard.rb
-├── valid_amount_guard.rb
-└── authorized_guard.rb
-```
-
-Guards define methods on `Servus::Guards` when inherited from `Servus::Guard`. The `Guard` suffix is stripped from the method name:
-
-```ruby
-# app/guards/sufficient_balance_guard.rb
-class SufficientBalanceGuard < Servus::Guard
-  http_status 422
-  error_code 'insufficient_balance'
-
-  message 'Insufficient balance: need %<required>s, have %<available>s' do
-    { required: amount, available: account.balance }
-  end
-
-  def test(account:, amount:)
-    account.balance >= amount
-  end
-end
-
-# Usage in services:
-# enforce_sufficient_balance!(account: account, amount: 100)  # throws on failure
-# check_sufficient_balance?(account: account, amount: 100)    # returns boolean
-```
-
-## Event Bus Configuration
-
-### Strict Event Validation
-
-Enable strict validation to catch handlers subscribing to events that aren't emitted by any service:
-
-```ruby
-# config/initializers/servus.rb
-Servus.configure do |config|
-  # Default: true
-  config.strict_event_validation = true
-end
-```
-
-When enabled, you can validate handlers at boot or in CI:
-
-```ruby
-# In a rake task or initializer
-Servus::EventHandler.validate_all_handlers!
-```
-
-This raises `Servus::Events::OrphanedHandlerError` if any handler subscribes to a non-existent event.
-
-### Handler Auto-Loading
-
-In Rails, handlers in `app/events/` are automatically loaded. The Railtie:
-- Clears the event bus on reload in development
-- Eager-loads all `*_handler.rb` files from `config.events_dir`
-
-```
-app/events/
-├── user_created_handler.rb
-├── payment_processed_handler.rb
-└── order_completed_handler.rb
-```
-
-### Event Instrumentation
-
-Events are instrumented via ActiveSupport::Notifications with the prefix `servus.events.`:
-
-```ruby
-# Subscribe to all Servus events
-ActiveSupport::Notifications.subscribe(/^servus\.events\./) do |name, *args|
-  event_name = name.sub('servus.events.', '')
-  Rails.logger.info "Event: #{event_name}"
-end
-```

data/docs/integration/2_testing.md

@@ -1,304 +0,0 @@
-# @title Integration / 2. Testing
-
-# Testing
-
-Services are designed for easy testing with explicit inputs (arguments) and outputs (Response objects). No special test infrastructure needed.
-
-## Schema Example Helpers
-
-Servus provides test helpers that extract `example` values from your JSON schemas, making it easy to generate test fixtures without maintaining separate factories.
-
-### Setup
-
-Include the helpers in your test suite:
-
-```ruby
-# spec/spec_helper.rb
-require 'servus/testing'
-
-RSpec.configure do |config|
-  config.include Servus::Testing::ExampleBuilders
-end
-```
-
-### Using Schema Examples
-
-Add `example` or `examples` keywords to your schemas:
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  schema(
-    arguments: {
-      type: "object",
-      properties: {
-        user_id: { type: "integer", example: 123 },
-        amount: { type: "number", example: 100.0 },
-        currency: { type: "string", examples: ["USD", "EUR", "GBP"] }
-      }
-    },
-    result: {
-      type: "object",
-      properties: {
-        transaction_id: { type: "string", example: "txn_abc123" },
-        status: { type: "string", example: "approved" }
-      }
-    },
-    failure: {
-      type: "object",
-      properties: {
-        reason: { type: "string", example: "card_declined" },
-        decline_code: { type: "string", example: "insufficient_funds" }
-      }
-    }
-  )
-end
-```
-
-Then use the helpers in your tests:
-
-```ruby
-RSpec.describe ProcessPayment::Service do
-  it "processes payment successfully" do
-    # Extract examples from schema and override specific values
-    args = servus_arguments_example(ProcessPayment::Service, amount: 50.0)
-    # => { user_id: 123, amount: 50.0, currency: "USD" }
-
-    result = ProcessPayment::Service.call(**args)
-
-    expect(result).to be_success
-    expect(result.data.keys).to match_array(
-      servus_result_example(ProcessPayment::Service).data.keys
-    )
-  end
-
-  it "returns structured failure data on decline" do
-    args = servus_arguments_example(ProcessPayment::Service, amount: 999_999)
-    result = ProcessPayment::Service.call(**args)
-
-    expected = servus_failure_example(ProcessPayment::Service)
-    expect(result).to be_failure
-    expect(result.data.keys).to match_array(expected.data.keys)
-  end
-
-  it "handles different currencies" do
-    %w[USD EUR GBP].each do |currency|
-      result = ProcessPayment::Service.call(
-        **servus_arguments_example(ProcessPayment::Service, currency: currency)
-      )
-      expect(result).to be_success
-    end
-  end
-end
-```
-
-### Deep Merging
-
-Overrides are deep-merged with schema examples, allowing you to override nested values:
-
-```ruby
-# Schema has nested structure
-args = servus_arguments_example(
-  CreateUser::Service,
-  user: { profile: { age: 35 } }
-)
-# => { user: { id: 1, profile: { name: 'Alice', age: 35 } } }
-```
-
-### Available Helpers
-
-- `servus_arguments_example(ServiceClass, **overrides)` - Returns hash of argument examples
-- `servus_result_example(ServiceClass, **overrides)` - Returns successful Response with result examples
-- `servus_failure_example(ServiceClass, **overrides)` - Returns failure Response with failure schema examples
-
-## Basic Testing Pattern
-
-```ruby
-RSpec.describe ProcessPayment::Service do
-  describe ".call" do
-    let(:user) { create(:user, balance: 1000) }
-
-    subject(:result) { described_class.call(user_id: user.id, amount: amount) }
-
-    context "with sufficient balance" do
-      let(:amount) { 50 }
-
-      it "processes payment" do
-        expect(result.success?).to be true
-        expect(result.data[:new_balance]).to eq(950)
-        expect(result.reload.balance).to eq(950)
-      end
-    end
-
-    context "with insufficient balance" do
-      let(:amount) { 2000 }
-
-      it "returns failure" do
-        expect(result.success?).to be false
-        expect(result.error.message).to eq("Insufficient funds")
-        expect(result.error).to be_a(Servus::Support::Errors::ServiceError)
-      end
-    end
-  end
-end
-```
-
-## Testing Service Composition
-
-When testing services that call other services, mock the child services:
-
-```ruby
-describe Users::CreateWithAccount::Service do
-  # Make local or global helpers to clean up tests
-  def servus_success_result(data)
-    Servus::Support::Response.new(success: true, data: data, error: nil)
-  end
-
-  it "calls both create services" do
-    # Mock child services
-    allow(Users::Create::Service).to receive(:call).and_return(servus_success_result{ user: user })
-    allow(Accounts::Create::Service).to receive(:call).and_return(servus_success_result{ account: account })
-
-    result = described_class.call(email: "test@example.com", plan: "premium")
-
-    expect(Users::Create::Service).to have_received(:call)
-    expect(Accounts::Create::Service).to have_received(:call)
-
-    expect(result.success?).to be true
-  end
-end
-```
-
-## Testing Schema Validation
-
-Don't test that valid arguments pass validation - that's testing the framework. Do test that your schema catches invalid inputs:
-
-```ruby
-it "validates required fields" do
-  expect {
-    Service.call(invalid: "params")
-  }.to raise_error(Servus::Support::Errors::ValidationError, /required/)
-end
-```
-
-## Testing Event Emission
-
-Servus provides RSpec matchers for testing that services emit events.
-
-### Setup
-
-Include the matchers in your test suite:
-
-```ruby
-# spec/spec_helper.rb
-require 'servus/testing'
-```
-
-### emit_event Matcher
-
-Assert that a block emits an event:
-
-```ruby
-RSpec.describe CreateUser::Service do
-  it 'emits user_created event on success' do
-    expect {
-      described_class.call(email: 'test@example.com', name: 'Test')
-    }.to emit_event(:user_created)
-  end
-
-  it 'emits event with expected payload' do
-    expect {
-      described_class.call(email: 'test@example.com', name: 'Test')
-    }.to emit_event(:user_created).with(hash_including(email: 'test@example.com'))
-  end
-
-  # Using handler class instead of symbol
-  it 'emits to UserCreatedHandler' do
-    expect {
-      described_class.call(email: 'test@example.com', name: 'Test')
-    }.to emit_event(UserCreatedHandler)
-  end
-end
-```
-
-### call_service Matcher
-
-Assert that a handler invokes a service:
-
-```ruby
-RSpec.describe UserCreatedHandler do
-  let(:payload) { { user_id: 123, email: 'test@example.com' } }
-
-  it 'invokes SendWelcomeEmail::Service' do
-    expect {
-      described_class.handle(payload)
-    }.to call_service(SendWelcomeEmail::Service).with(user_id: 123)
-  end
-
-  it 'invokes service asynchronously' do
-    expect {
-      described_class.handle(payload)
-    }.to call_service(SendWelcomeEmail::Service).async
-  end
-end
-```
-
-### Testing EventHandler Directly
-
-Test handlers by calling their `handle` class method:
-
-```ruby
-RSpec.describe UserCreatedHandler do
-  let(:payload) { { user_id: 123, email: 'test@example.com' } }
-
-  before do
-    allow(SendWelcomeEmail::Service).to receive(:call_async)
-    allow(TrackAnalytics::Service).to receive(:call_async)
-  end
-
-  it 'invokes SendWelcomeEmail with mapped arguments' do
-    described_class.handle(payload)
-
-    expect(SendWelcomeEmail::Service)
-      .to have_received(:call_async)
-      .with(user_id: 123, email: 'test@example.com')
-  end
-
-  it 'invokes TrackAnalytics with event data' do
-    described_class.handle(payload)
-
-    expect(TrackAnalytics::Service)
-      .to have_received(:call_async)
-      .with(event: 'user_created', user_id: 123)
-  end
-
-  context 'with conditional invocation' do
-    it 'skips premium rewards for non-premium users' do
-      allow(GrantPremiumRewards::Service).to receive(:call)
-
-      described_class.handle(payload.merge(premium: false))
-
-      expect(GrantPremiumRewards::Service).not_to have_received(:call)
-    end
-  end
-end
-```
-
-### Testing Event Emission from Handler
-
-Test the `emit` class method:
-
-```ruby
-RSpec.describe UserCreatedHandler do
-  it 'emits the user_created event' do
-    expect {
-      described_class.emit({ user_id: 123, email: 'test@example.com' })
-    }.to emit_event(:user_created)
-  end
-
-  it 'validates payload against schema' do
-    expect {
-      described_class.emit({ invalid: 'payload' })
-    }.to raise_error(Servus::Support::Errors::ValidationError)
-  end
-end
-```