servus 0.3.0 → 0.4.0

data/docs/features/6_guards.md

@@ -1,356 +0,0 @@
-# @title Features / 6. Guards
-
-# Guards
-
-Guards are reusable validation rules that halt service execution when conditions aren't met. They provide a declarative way to enforce preconditions with rich, API-friendly error responses.
-
-## Why Guards?
-
-Instead of scattering validation logic throughout services:
-
-```ruby
-# Without guards - repetitive and verbose
-def call
-  return failure("User required", type: ValidationError) unless user
-  return failure("User must be active", type: ValidationError) unless user.active?
-  # ... business logic ...
-end
-```
-
-Use guards for clean, declarative validation:
-
-```ruby
-# With guards - clear and reusable
-def call
-  enforce_presence!(user: user)
-  enforce_truthy!(on: user, check: :active)
-  # ... business logic ...
-end
-```
-
-## Built-in Guards
-
-Servus includes four guards by default:
-
-### PresenceGuard
-
-Validates that all values are present (not nil or empty):
-
-```ruby
-# Single value
-enforce_presence!(user: user)
-
-# Multiple values - all must be present
-enforce_presence!(user: user, account: account, device: device)
-
-# Works with strings, arrays, hashes
-enforce_presence!(email: email)           # fails if nil or ""
-enforce_presence!(items: cart.items)      # fails if nil or []
-enforce_presence!(data: response.body)    # fails if nil or {}
-```
-
-Error: `"user must be present (got nil)"` or `"email must be present (got \"\")"`
-
-### TruthyGuard
-
-Validates that attribute(s) on an object are truthy:
-
-```ruby
-# Single attribute
-enforce_truthy!(on: user, check: :active)
-
-# Multiple attributes - all must be truthy
-enforce_truthy!(on: user, check: [:active, :verified, :confirmed])
-
-# Conditional check
-if check_truthy?(on: subscription, check: :valid?)
-  process_subscription
-end
-```
-
-Error: `"User.active must be truthy (got false)"`
-
-### FalseyGuard
-
-Validates that attribute(s) on an object are falsey:
-
-```ruby
-# Single attribute - user must not be banned
-enforce_falsey!(on: user, check: :banned)
-
-# Multiple attributes - all must be falsey
-enforce_falsey!(on: post, check: [:deleted, :hidden, :flagged])
-
-# Conditional check
-if check_falsey?(on: user, check: :suspended)
-  allow_action
-end
-```
-
-Error: `"User.banned must be falsey (got true)"`
-
-### StateGuard
-
-Validates that an attribute matches an expected value or one of several allowed values:
-
-```ruby
-# Single expected value
-enforce_state!(on: order, check: :status, is: :pending)
-
-# Multiple allowed values - any match passes
-enforce_state!(on: account, check: :status, is: [:active, :trial])
-
-# Conditional check
-if check_state?(on: order, check: :status, is: :shipped)
-  send_tracking_email
-end
-```
-
-Errors:
-- Single value: `"Order.status must be pending (got shipped)"`
-- Multiple values: `"Account.status must be one of active, trial (got suspended)"`
-
-## Guard Methods
-
-Each guard defines two methods on `Servus::Guards`:
-
-- **Bang method (`!`)** - Throws on failure, halts execution
-- **Predicate method (`?`)** - Returns boolean, continues execution
-
-```ruby
-# Bang method - use for preconditions that must pass
-enforce_presence!(user: user)  # throws :guard_failure if nil
-
-# Predicate method - use for conditional logic
-if check_truthy?(on: account, check: :premium)
-  apply_premium_discount
-else
-  apply_standard_rate
-end
-```
-
-## Creating Custom Guards
-
-Define guards by inheriting from `Servus::Guard`:
-
-```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
-    message_data
-  end
-
-  def test(account:, amount:)
-    account.balance >= amount
-  end
-
-  private
-
-  def message_data
-    {
-      required: kwargs[:amount],
-      available: kwargs[:account].balance
-    }
-  end
-end
-```
-
-This automatically defines `enforce_sufficient_balance!` and `check_sufficient_balance?` methods.
-
-### Guard DSL
-
-**`http_status`** - HTTP status code for API responses (default: 422)
-
-```ruby
-http_status 422  # Unprocessable Entity
-http_status 403  # Forbidden
-http_status 400  # Bad Request
-```
-
-**`error_code`** - Machine-readable error code for API clients
-
-```ruby
-error_code 'insufficient_balance'
-error_code 'daily_limit_exceeded'
-error_code 'account_locked'
-```
-
-**`message`** - Human-readable error message with optional interpolation
-
-```ruby
-# Static message
-message 'Amount must be positive'
-
-# With interpolation (uses Ruby's % formatting)
-message 'Balance: %<current>s, Required: %<required>s' do
-  { current: account.balance, required: amount }
-end
-```
-
-The message block has access to all kwargs passed to the guard via `kwargs`.
-
-**`test`** - The validation logic (must return boolean)
-
-```ruby
-def test(account:, amount:)
-  account.balance >= amount
-end
-```
-
-## Message Templates
-
-Guards support multiple message template formats:
-
-### String with Interpolation
-
-```ruby
-message 'Insufficient balance: need %<required>s, have %<available>s' do
-  { required: amount, available: account.balance }
-end
-```
-
-### I18n Symbol
-
-```ruby
-message :insufficient_balance
-# Looks up: I18n.t('guards.insufficient_balance')
-# Falls back to: "Insufficient balance" (humanized)
-```
-
-### Inline Translations
-
-```ruby
-message(
-  en: 'Insufficient balance',
-  es: 'Saldo insuficiente',
-  fr: 'Solde insuffisant'
-)
-```
-
-### Dynamic Proc
-
-```ruby
-message -> { "Limit exceeded for #{limit_type} transfers" }
-```
-
-## Error Handling
-
-When a bang guard fails, it throws `:guard_failure` with a `GuardError`. Services automatically catch this and return a failure response:
-
-```ruby
-class TransferService < Servus::Base
-  def call
-    enforce_state!(on: from_account, check: :status, is: :active)
-    # If guard fails, execution stops here
-    # Service returns: Response(success: false, error: GuardError)
-
-    transfer_funds
-    success(transfer: transfer)
-  end
-end
-```
-
-The `GuardError` includes all metadata:
-
-```ruby
-error = guard.error
-error.message     # "Account.status must be active (got suspended)"
-error.code        # "invalid_state"
-error.http_status # 422
-```
-
-## Naming Convention
-
-Guard class names are converted to method names by stripping the `Guard` suffix and converting to snake_case:
-
-| Class Name | Bang Method | Predicate Method |
-|------------|-------------|------------------|
-| `SufficientBalanceGuard` | `enforce_sufficient_balance!` | `check_sufficient_balance?` |
-| `ValidAmountGuard` | `enforce_valid_amount!` | `check_valid_amount?` |
-| `AuthorizedGuard` | `enforce_authorized!` | `check_authorized?` |
-
-The built-in guards follow this pattern: `TruthyGuard` -> `enforce_truthy!` / `check_truthy?`.
-
-## Rails Auto-Loading
-
-In Rails, guards in `app/guards/` are automatically loaded. Files must follow the `*_guard.rb` naming convention:
-
-```
-app/guards/
-├── sufficient_balance_guard.rb
-├── valid_amount_guard.rb
-└── authorized_guard.rb
-```
-
-## Configuration
-
-Disable built-in guards if you want to define your own (you can have both):
-
-```ruby
-Servus.configure do |config|
-  config.include_default_guards = false        # Default: true
-  config.guards_dir             = 'app/guards' # Default: 'app/guards'
-end
-```
-
-## Testing Guards
-
-Test guards in isolation:
-
-```ruby
-RSpec.describe Servus::Guards::TruthyGuard do
-  let(:user_class) do
-    Struct.new(:active, :verified, keyword_init: true) do
-      def self.name
-        'User'
-      end
-    end
-  end
-
-  describe '#test' do
-    it 'passes when attribute is truthy' do
-      user = user_class.new(active: true)
-      guard = described_class.new(on: user, check: :active)
-      expect(guard.test(on: user, check: :active)).to be true
-    end
-
-    it 'fails when attribute is falsey' do
-      user = user_class.new(active: false)
-      guard = described_class.new(on: user, check: :active)
-      expect(guard.test(on: user, check: :active)).to be false
-    end
-  end
-
-  describe '#error' do
-    it 'returns GuardError with correct metadata' do
-      user = user_class.new(active: false)
-      guard = described_class.new(on: user, check: :active)
-      error = guard.error
-
-      expect(error.code).to eq('must_be_truthy')
-      expect(error.message).to include('User', 'active', 'false')
-      expect(error.http_status).to eq(422)
-    end
-  end
-end
-```
-
-Test guards in service integration:
-
-```ruby
-RSpec.describe TransferService do
-  it 'fails when account is not active' do
-    result = described_class.call(
-      from_account: suspended_account,
-      to_account: recipient,
-      amount: 100
-    )
-
-    expect(result).to be_failure
-    expect(result.error.code).to eq('invalid_state')
-  end
-end
-```

data/docs/features/7_lazy_resolvers.md

@@ -1,238 +0,0 @@
-# @title Features / 7. Lazy Resolvers
-
-# Lazy Resolvers
-
-Services often accept record IDs as inputs and query for the record inside `call`. This is necessary for async execution — ActiveJob serializes arguments, so you can't pass ActiveRecord objects through a job. But when calling synchronously with an already-loaded record, re-querying is wasteful.
-
-The `lazily` DSL solves this. A service declares what records it needs, and the resolver handles both cases transparently: pass an ID and it queries; pass an instance and it skips the query.
-
-## The Problem
-
-Without `lazily`, you write this pattern repeatedly:
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  def initialize(user_id:, amount:)
-    @user_id = user_id
-    @amount = amount
-  end
-
-  def call
-    user = User.find(@user_id)  # Always queries, even if caller had the record
-    # ...
-  end
-end
-```
-
-The caller can't pass a loaded record — `user_id:` expects an integer. And if you change the param to `user:`, it breaks async execution.
-
-## Basic Usage
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  lazily :user, finds: User
-
-  def initialize(user:, amount:)
-    @user = user
-    @amount = amount
-  end
-
-  def call
-    return failure("Insufficient funds") unless user.balance >= @amount
-
-    user.update!(balance: user.balance - @amount)
-    success(user: user, new_balance: user.balance)
-  end
-end
-```
-
-The param is named `user:` — callers pass whatever they have:
-
-```ruby
-# Sync with a loaded record — no query
-ProcessPayment::Service.call(user: current_user, amount: 50)
-
-# Async with an ID — resolves via User.find(123)
-ProcessPayment::Service.call_async(user: user.id, amount: 50)
-
-# Sync with an ID — also works
-ProcessPayment::Service.call(user: 123, amount: 50)
-```
-
-## DSL Signature
-
-```ruby
-lazily :name, finds: ModelClass              # default: ModelClass.find(value)
-lazily :name, finds: ModelClass, by: :column # ModelClass.find_by!(column: value)
-```
-
-| Parameter | Description |
-|-----------|-------------|
-| `:name` | The keyword argument name and the accessor method name |
-| `finds:` | The model class constant (e.g., `User`, `Account`) |
-| `by:` | Lookup column. Defaults to `:id`. When set, uses `.find_by!` instead of `.find` |
-
-## Resolution Behavior
-
-The resolver checks the input type and acts accordingly:
-
-| Input | Behavior |
-|-------|----------|
-| Instance of target class | Returned directly — no query |
-| Integer, String, or other scalar | Resolved via `.find(value)` or `.find_by!(column: value)` |
-| Array | Resolved via `.where(column => values)` |
-| `nil` | Raises `NotFoundError` immediately |
-
-Resolution is **lazy** — it only happens when the accessor method is first called inside `call`, not during `initialize`. If a service never calls the accessor, no query is made.
-
-Resolution is **memoized** — the resolved record is written back to the instance variable. Subsequent calls return the same object without re-querying.
-
-## Custom Column Lookup
-
-Use `by:` to look up by a column other than `:id`:
-
-```ruby
-class FindAccount::Service < Servus::Base
-  lazily :account, finds: Account, by: :uuid
-
-  def initialize(account:)
-    @account = account
-  end
-
-  def call
-    success(account: account)
-  end
-end
-
-# Resolves via Account.find_by!(uuid: "abc-def-123")
-FindAccount::Service.call(account: "abc-def-123")
-
-# Passes through an Account instance directly
-FindAccount::Service.call(account: loaded_account)
-```
-
-The `by:` column accepts any value type — strings, integers, UUIDs — whatever the column expects.
-
-## Array Input
-
-When the input is an Array, the resolver uses `.where` instead of `.find`:
-
-```ruby
-class BulkNotify::Service < Servus::Base
-  lazily :users, finds: User
-
-  def initialize(users:, message:)
-    @users = users
-    @message = message
-  end
-
-  def call
-    users.each { |u| notify(u, @message) }
-    success(notified: users.count)
-  end
-end
-
-# Resolves via User.where(id: [1, 2, 3])
-BulkNotify::Service.call(users: [1, 2, 3], message: "Hello")
-```
-
-Arrays with a custom `by:` column use `.where(column => values)`.
-
-Empty arrays return an empty relation — no error is raised.
-
-## Multiple Resolvers
-
-A service can declare multiple resolvers. Each resolves independently and memoizes separately:
-
-```ruby
-class TransferFunds::Service < Servus::Base
-  lazily :sender, finds: User
-  lazily :receiver, finds: User
-  lazily :account, finds: Account, by: :uuid
-
-  def initialize(sender:, receiver:, account:, amount:)
-    @sender = sender
-    @receiver = receiver
-    @account = account
-    @amount = amount
-  end
-
-  def call
-    # Each resolver triggers independently on first access
-    success(from: sender.name, to: receiver.name, account: account.uuid)
-  end
-end
-```
-
-## Error States
-
-### Nil Input
-
-Raises `Servus::Extensions::Lazily::Errors::NotFoundError` immediately. The error message includes the param name and target class:
-
-```
-Couldn't find User (user was nil)
-```
-
-This is always a bug at the call site — the resolver never silently returns nil.
-
-### Missing Record
-
-`.find` and `.find_by!` raise `ActiveRecord::RecordNotFound` as usual. The resolver does not catch or wrap these errors — they propagate normally.
-
-```ruby
-# Raises ActiveRecord::RecordNotFound: Couldn't find User with 'id'=999
-ProcessPayment::Service.call(user: 999, amount: 50)
-```
-
-Use `rescue_from` if you want to convert these to failure responses:
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  lazily :user, finds: User
-  rescue_from ActiveRecord::RecordNotFound, use: NotFoundError
-
-  # ...
-end
-```
-
-### Empty Array
-
-Returns an empty ActiveRecord relation. No error is raised — this is intentional for batch operations where an empty set is valid.
-
-## Async Compatibility
-
-The `lazily` pattern is designed for services that run both synchronously and asynchronously:
-
-```ruby
-# Controller (sync) — pass the loaded record
-def create
-  run_service(ProcessPayment::Service, user: current_user, amount: params[:amount])
-end
-
-# Background job (async) — pass the ID
-ProcessPayment::Service.call_async(user: user.id, amount: 50)
-```
-
-Both paths use the same service code. The resolver handles the difference.
-
-## dry-initializer Compatibility
-
-`lazily` works alongside dry-initializer. The resolver defines its accessor on a prepended module, which takes priority over dry-initializer's generated method. It reads from the `@name` instance variable that dry-initializer sets:
-
-```ruby
-class ProcessPayment::Service < Servus::Base
-  option :user
-  option :amount
-
-  lazily :user, finds: User
-
-  def call
-    success(user: user, charged: amount)
-  end
-end
-```
-
-## Requirements
-
-`lazily` is an ActiveRecord extension. It loads automatically via Railtie when ActiveRecord is present in your application. It is not available in pure Ruby applications without ActiveRecord.