servus 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f20bb1c0b41657377b94a29aef1915dc7a0c4c65442d21b9f6a60c75537dd8a
-  data.tar.gz: 9273a9d2e3efa50c3ce2d80935e7538a1fa89e0cc3195acfde974621f7960277
+  metadata.gz: 58e6098b9ea316c670b5b8aa6f61828d961cc3c8ad6e72357d71c442dfe75151
+  data.tar.gz: 215f0f790ad36575b0b9de3f956cf585f19051c16d5250ada1ae152a969dd1d7
 SHA512:
-  metadata.gz: e2e4ec7e3390784c35acbe238b3d809c4e07859c39ccd159a1618daf3439d04d7bb4eb3c847ea30e1a3b94a1d4dfac2508601ce263160ddee1d7e0a9e20ed13b
-  data.tar.gz: 4f135793c078f9230436a6ff3f9508847469a198dfa818afadcbace146b7b85fdb78844a864538b96bded6cb3eed910002c0fdc8b6802ad4cae3189e06349a54
+  metadata.gz: 48142cd74cbd766846ccd9d8bf4a71a8d67136cbd60bdc948ddda6a0fa99f7e6072351b6ff98958500a6d84e49d1cb7d122e8e435efeb8b1384d39a4be9932ad
+  data.tar.gz: 13899ee4220e2e25b888eae9b6675a77780770628717bc11a2abda9bdd82e49b0798d70c954f91e5649a3bc281d9b3ad0e50dce41374f3c2ebc42125d7321848

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [0.3.0] - 2026-04-03
+
+### Breaking Changes
+
+- **Failure responses can now carry data**: `failure()` accepts an optional `data:` kwarg. Previously,
+  `result.data` was guaranteed to be `nil` on failure. Code that checks `result.data` for truthiness
+  to determine success/failure must switch to `result.success?` or `result.failure?`.
+  See the [Migration Guide](docs/guides/2_migration_guide.md#migrating-to-030) for details.
+- **`Response#with_data` removed**: Replaced by the `data:` kwarg on `failure()`. The `with_data` method
+  allowed arbitrary mutation of responses after creation, bypassing schema validation.
+
+### Added
+
+- **`lazily` resolver DSL**: Declare lazy record resolvers on services with `lazily :user, finds: User`.
+  Accepts either an ID or an already-loaded instance — resolves on first access, memoizes the result.
+  Supports custom columns (`by: :uuid`), array input (via `.where`), and dry-initializer compatibility.
+  Loaded as an extension via Railtie when ActiveRecord is present.
+- **Failure data support**: `failure()` accepts an optional `data:` keyword argument for attaching
+  structured data to failure responses (e.g., `failure("Declined", data: { reason: "insufficient_funds" })`).
+  Defaults to `nil` for backwards compatibility with services that don't use it.
+- **Failure schema validation**: Define a `failure` schema via the `schema` DSL, `FAILURE_SCHEMA` constant,
+  or `failure.json` file. When present, failure response data is validated against it — just like success
+  results are validated against `result` schemas.
+- **`servus_failure_example` test helper**: Extracts example values from a service's `failure` schema,
+  returning a failure `Response` for use in tests.
+- **`failure?` predicate on Response**: Complement to `success?` for cleaner conditional handling.
+- **`DataObject` wrapper for response data**: Hash data returned by services is wrapped in a read-only
+  `DataObject` that supports accessor-style access (`result.data.user.email`) alongside bracket access
+  (`result.data[:user]`). Nested Hashes and Hashes inside Arrays are recursively wrapped. Non-Hash values
+  (models, nil) pass through unwrapped.
+
 ## [0.2.1] - 2025-12-20
 
 ### Added
@@ -101,21 +132,37 @@
 - 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
-- Added: Added `schema` DSL method for cleaner schema definition. Supports `schema arguments: {...}, result: {...}` syntax. Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
-- Added: Added support from blocks on `rescue_from` to override default failure handler.
-- Fixed: YARD link resolution warnings in documentation
+
+### Added
+
+- **Schema DSL method**: `schema arguments: {...}, result: {...}` syntax for cleaner schema definition.
+  Fully backwards compatible with existing `ARGUMENTS_SCHEMA` and `RESULT_SCHEMA` constants.
+- **Test helpers**: `servus_arguments_example` and `servus_result_example` for extracting example values
+  from schemas in tests
+- **`rescue_from` block support**: Override the default failure handler with a custom block
+- **YARD documentation**: Configuration with README homepage and markdown file support
+
+### Fixed
+
+- YARD link resolution warnings in documentation
 
 ## [0.1.3] - 2025-10-10
-- Added: Added `call_async` method to `Servus::Base` to enqueue a job for calling the service asynchronously
-- Added: Added `Async::Job` to handle async enqueing with support for ActiveJob set options
+
+### Added
+
+- **`call_async`**: Enqueue service calls as background jobs via ActiveJob
+- **`Async::Job`**: Job class for async enqueueing with support for ActiveJob `set` options
 
 ## [0.1.1] - 2025-08-20
 
-- Added: Added `rescue_from` method to `Servus::Base` to rescue from standard errors and use custom error types.
-- Added: Added `run_service` and `render_service_object_error` helpers to `Servus::Helpers::ControllerHelpers`.
-- Fixed: All rubocop warnings.
+### Added
+
+- **`rescue_from`**: Rescue from standard errors and convert them to failure responses with custom error types
+- **Controller helpers**: `run_service` and `render_service_object_error` in `Servus::Helpers::ControllerHelpers`
+
+### Fixed
+
+- All rubocop warnings
 
 ## [0.1.0] - 2025-04-28
 

data/docs/core/1_overview.md

@@ -39,11 +39,15 @@ Services return `Response` objects instead of raising exceptions for business fa
 ```ruby
 result = SomeService.call(params)
 if result.success?
-  result.data  # Hash or object returned by success()
+  result.data            # DataObject wrapping the success data
+  result.data[:user]     # bracket access
+  result.data.user       # accessor access
+  result.data.user.email # nested accessor access
 else
-  result.error # ServiceError instance
+  result.error           # ServiceError instance
   result.error.message
   result.error.api_error # { code: :symbol, message: "string" }
+  result.data            # optional failure data (nil unless data: kwarg was used)
 end
 ```
 

data/docs/core/3_service_objects.md

@@ -35,6 +35,39 @@ result.success? # => true
 result.data[:user] # => #<User>
 ```
 
+## Accessing Response Data
+
+Response data can be accessed with bracket syntax or accessor-style methods. Both are fully supported — use whichever reads better in context.
+
+```ruby
+result = Users::Create::Service.call(email: "user@example.com", name: "John")
+
+# Bracket access
+result.data[:user]          # => #<User>
+result.data[:user].email    # => "user@example.com"
+
+# Accessor access
+result.data.user            # => #<User>
+result.data.user.email      # => "user@example.com"
+```
+
+Nested Hashes are wrapped automatically, so accessor chains work at any depth:
+
+```ruby
+result = Orders::Create::Service.call(items: [...])
+
+result.data.order.shipping.address.city  # => "Berlin"
+result.data[:order][:shipping]           # also works
+```
+
+Arrays of Hashes are also wrapped, so you can access elements naturally:
+
+```ruby
+result.data.order.items.first.sku   # => "A1"
+```
+
+Non-Hash values like model instances, strings, and integers pass through unchanged — accessor access on those values uses the object's own methods.
+
 ## Service Composition
 
 Services can call other services. Use the returned Response to decide whether to continue or propagate the failure.

data/docs/features/1_schema_validation.md

@@ -28,6 +28,12 @@ class ProcessPayment::Service < Servus::Base
         transaction_id: { type: "string", example: "txn_abc123" },
         new_balance: { type: "number", example: 950.0 }
       }
+    },
+    failure: {
+      type: "object",
+      properties: {
+        reason: { type: "string", example: "insufficient_funds" }
+      }
     }
   )
 end
@@ -73,6 +79,13 @@ class ProcessPayment::Service < Servus::Base
       new_balance: { type: "number" }
     }
   }.freeze
+
+  FAILURE_SCHEMA = {
+    type: "object",
+    properties: {
+      reason: { type: "string" }
+    }
+  }.freeze
 end
 ```
 
@@ -81,12 +94,13 @@ end
 For complex schemas, use JSON files instead of inline definitions. Create files at:
 - `app/schemas/services/service_name/arguments.json`
 - `app/schemas/services/service_name/result.json`
+- `app/schemas/services/service_name/failure.json`
 
 ### Schema Lookup Precedence
 
 Servus checks for schemas in this order:
 1. **schema DSL method** (if defined)
-2. **Inline constants** (ARGUMENTS_SCHEMA, RESULT_SCHEMA)
+2. **Inline constants** (ARGUMENTS_SCHEMA, RESULT_SCHEMA, FAILURE_SCHEMA)
 3. **JSON files** (in schema_root directory)
 
 Schemas are cached after first load for performance.
@@ -101,6 +115,34 @@ Schemas are cached after first load for performance.
 
 Each layer has a different purpose - don't duplicate validation across layers.
 
+## Failure Data Validation
+
+Services can optionally attach structured data to failure responses using the `data:` keyword argument on `failure()`. When a `failure` schema is defined, this data is validated against it — just like success results are validated against `result` schemas.
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  schema(
+    failure: {
+      type: "object",
+      required: ["reason"],
+      properties: {
+        reason: { type: "string" },
+        decline_code: { type: "string" }
+      }
+    }
+  )
+
+  def call
+    return failure("Card declined", data: { reason: "insufficient_funds", decline_code: "do_not_honor" })
+  end
+end
+```
+
+Failure data validation is skipped when:
+- No `failure` schema is defined
+- The failure response has no data (`data: nil`, the default)
+- The response is a success
+
 ## Configuration
 
 Change the schema file location if needed:

data/docs/features/2_error_handling.md

@@ -29,6 +29,14 @@ def call
 end
 ```
 
+Failures can optionally carry structured data using the `data:` keyword argument. When a `failure` schema is defined on the service, this data is validated against it.
+
+```ruby
+def call
+  return failure("Approval required", data: { requires_human_approval: true, ai_approved: true })
+end
+```
+
 ## Error Classes
 
 All error classes inherit from `ServiceError` and map to HTTP status codes. Use them for API-friendly errors.
@@ -101,7 +109,7 @@ class ProcessPayment::Service < Servus::Base
 end
 ```
 
-The block has access to `success(data)` and `failure(message, type:)` methods. This allows conditional error handling and even recovering from exceptions.
+The block has access to `success(data)` and `failure(message, data:, type:)` methods. This allows conditional error handling and even recovering from exceptions.
 
 ## Custom Errors
 

data/docs/features/7_lazy_resolvers.md

@@ -0,0 +1,238 @@
+# @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.

data/docs/guides/2_migration_guide.md

@@ -2,7 +2,57 @@
 
 # Migration Guide
 
-Strategies for adopting Servus in existing Rails applications.
+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
 

data/docs/integration/2_testing.md

@@ -42,6 +42,13 @@ class ProcessPayment::Service < Servus::Base
         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
@@ -64,6 +71,15 @@ RSpec.describe ProcessPayment::Service do
     )
   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(
@@ -91,7 +107,8 @@ args = servus_arguments_example(
 ### Available Helpers
 
 - `servus_arguments_example(ServiceClass, **overrides)` - Returns hash of argument examples
-- `servus_result_example(ServiceClass, **overrides)` - Returns Response object with result 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
 

data/lib/servus/base.rb

@@ -88,6 +88,8 @@ module Servus
     # The failure is logged automatically and returns a response containing the error.
     #
     # @param message [String, nil] custom error message (uses error type's default if nil)
+    # @param data [Object, nil] optional structured data to attach to the failure response.
+    #   When a +failure+ schema is defined, this data will be validated against it.
     # @param type [Class] error class to instantiate (must inherit from ServiceError)
     # @return [Servus::Support::Response] response with success: false and the error
     #
@@ -109,12 +111,17 @@ module Servus
     #     # Uses "Not found" as the message
     #   end
     #
+    # @example Attaching structured data to a failure
+    #   def call
+    #     return failure("Approval required", data: { requires_human_approval: true })
+    #   end
+    #
     # @see #success
     # @see #error!
     # @see Servus::Support::Errors
-    def failure(message = nil, type: Servus::Support::Errors::ServiceError)
+    def failure(message = nil, data: nil, type: Servus::Support::Errors::ServiceError)
       error = type.new(message)
-      Response.new(false, nil, error)
+      Response.new(false, data, error)
     end
 
     # Logs an error and raises an exception, halting service execution.
@@ -207,15 +214,16 @@ module Servus
       end
       # rubocop:enable Metrics/MethodLength
 
-      # Defines schema validation rules for the service's arguments and/or result.
+      # Defines schema validation rules for the service's arguments, result, and/or failure data.
       #
       # This method provides a clean DSL for specifying JSON schemas that will be used
       # to validate service inputs and outputs. Schemas defined via this method take
-      # precedence over ARGUMENTS_SCHEMA and RESULT_SCHEMA constants. The next major
-      # version will deprecate those constants in favor of this DSL.
+      # precedence over ARGUMENTS_SCHEMA, RESULT_SCHEMA, and FAILURE_SCHEMA constants.
+      # The next major version will deprecate those constants in favor of this DSL.
       #
       # @param arguments [Hash, nil] JSON schema for validating service arguments
       # @param result [Hash, nil] JSON schema for validating service result data
+      # @param failure [Hash, nil] JSON schema for validating failure response data
       # @return [void]
       #
       # @example Defining both arguments and result schemas
@@ -245,9 +253,10 @@ module Servus
       #   end
       #
       # @see Servus::Support::Validator
-      def schema(arguments: nil, result: nil)
+      def schema(arguments: nil, result: nil, failure: nil)
         @arguments_schema = arguments.with_indifferent_access if arguments
         @result_schema    = result.with_indifferent_access    if result
+        @failure_schema   = failure.with_indifferent_access   if failure
       end
 
       # Returns the arguments schema defined via the schema DSL method.
@@ -262,6 +271,12 @@ module Servus
       # @api private
       attr_reader :result_schema
 
+      # Returns the failure schema defined via the schema DSL method.
+      #
+      # @return [Hash, nil] the failure schema or nil if not defined
+      # @api private
+      attr_reader :failure_schema
+
       # Executes pre-call hooks including logging and argument validation.
       #
       # This method is automatically called before service execution and handles:

data/lib/servus/extensions/lazily/call.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Provides lazy record resolution for service inputs.
+      #
+      # This module extends {Servus::Base} with the {#lazily} class method, enabling
+      # services to accept either a record ID or an already-loaded record instance.
+      # Resolution happens lazily on first access and is memoized.
+      #
+      # @see Lazily#lazily
+      module Call
+        # Declares a lazy record resolver for a service input.
+        #
+        # Defines an accessor method that lazily resolves the input value to a record.
+        # If the value is already an instance of the target class, it is returned directly.
+        # If the value is an ID (or other lookup value), it is resolved via the target
+        # class's +.find+ or +.find_by!+ method. Arrays are resolved via +.where+.
+        #
+        # The resolved record is written back to the instance variable, so subsequent
+        # calls return the same object without re-querying.
+        #
+        # @param name [Symbol] the param/ivar name, also becomes the accessor method
+        # @param finds [Class] the model class to resolve against (e.g., +User+, +Account+)
+        # @param by [Symbol] the lookup column (default: +:id+). When +:id+, uses +.find+.
+        #   Otherwise uses +.find_by!(column: value)+.
+        # @return [void]
+        #
+        # @example Basic usage with .find
+        #   lazily :user, finds: User
+        #   # user: 123       → User.find(123)
+        #   # user: user_inst → returns user_inst directly
+        #
+        # @example Custom column lookup
+        #   lazily :account, finds: Account, by: :uuid
+        #   # account: "abc-def" → Account.find_by!(uuid: "abc-def")
+        #
+        # @example Array input
+        #   lazily :users, finds: User
+        #   # users: [1, 2, 3] → User.where(id: [1, 2, 3])
+        #
+        # @note Only available when ActiveRecord is loaded (via Railtie)
+        # @see Servus::Base.call
+        def lazily(name, finds:, by: :id)
+          (@lazy_resolvers ||= {})[name] = { klass: finds, by: by }
+          define_resolver_method(name, finds, by)
+        end
+
+        # Returns the hash of registered lazy resolvers for this service class.
+        #
+        # @return [Hash{Symbol => Hash}] resolver configurations keyed by name
+        # @api private
+        def lazy_resolvers
+          @lazy_resolvers || {}
+        end
+
+        private
+
+        # Defines a lazy accessor method on a prepended module.
+        #
+        # @param name [Symbol] the method/ivar name
+        # @param klass [Class] the target model class
+        # @param by [Symbol] the lookup column
+        # @api private
+        def define_resolver_method(name, klass, by)
+          mod = (@_resolver_module ||= Module.new)
+          prepend(mod) unless ancestors.include?(mod)
+
+          mod.define_method(name) do
+            @_lazily_resolved ||= {}
+            return instance_variable_get(:"@#{name}") if @_lazily_resolved[name]
+
+            resolved = Resolver.call(instance_variable_get(:"@#{name}"), klass: klass, by: by, name: name)
+            @_lazily_resolved[name] = true
+            instance_variable_set(:"@#{name}", resolved)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servus/extensions/lazily/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Error classes for lazy record resolution.
+      #
+      # These errors are raised when lazy resolution fails, such as when
+      # a required record reference is nil.
+      module Errors
+        # Base error class for all lazily extension errors.
+        #
+        # All lazy resolution errors inherit from this class for easy rescue handling.
+        class LazilyError < StandardError; end
+
+        # Raised when a lazily-resolved record reference is nil.
+        #
+        # This occurs when a service declares +lazily :user, finds: User+ but
+        # receives +user: nil+. A nil reference is always a bug at the call site.
+        #
+        # @example
+        #   class MyService < Servus::Base
+        #     lazily :user, finds: User
+        #
+        #     def initialize(user:)
+        #       @user = user
+        #     end
+        #
+        #     def call
+        #       user # => raises NotFoundError if @user is nil
+        #     end
+        #   end
+        class NotFoundError < LazilyError; end
+      end
+    end
+  end
+end

data/lib/servus/extensions/lazily/ext.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    # Lazy record resolution extensions for Servus services.
+    #
+    # This module provides the infrastructure for lazily resolving record
+    # references (IDs or instances) in service inputs. When loaded, it extends
+    # {Servus::Base} with the {Call#lazily} class method.
+    #
+    # @see Servus::Extensions::Lazily::Call
+    module Lazily
+      require 'servus/extensions/lazily/errors'
+      require 'servus/extensions/lazily/resolver'
+      require 'servus/extensions/lazily/call'
+
+      # Extension module for lazily functionality.
+      #
+      # @api private
+      module Ext; end
+    end
+  end
+end

data/lib/servus/extensions/lazily/resolver.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Servus
+  module Extensions
+    module Lazily
+      # Performs the actual record resolution for a lazily-declared input.
+      #
+      # Handles the decision logic: is the raw value already an instance,
+      # nil, an array, or a lookup value? Delegates to the appropriate
+      # finder method on the target class.
+      #
+      # @api private
+      class Resolver
+        # Resolves a raw value to a record (or collection of records).
+        #
+        # @param raw [Object] the raw input value (ID, instance, Array, or nil)
+        # @param klass [Class] the target model class
+        # @param by [Symbol] the lookup column
+        # @param name [Symbol] the param name (for error messages)
+        # @return [Object] the resolved record or collection
+        # @raise [Errors::NotFoundError] if raw is nil
+        def self.call(raw, klass:, by:, name:)
+          return raw if raw.is_a?(klass)
+          raise Errors::NotFoundError, "Couldn't find #{klass} (#{name} was nil)" if raw.nil?
+          return klass.where(by => raw) if raw.is_a?(Array)
+
+          by == :id ? klass.find(raw) : klass.find_by!(by => raw)
+        end
+      end
+    end
+  end
+end

data/lib/servus/railtie.rb

@@ -14,11 +14,17 @@ module Servus
     initializer 'servus.job_async' do
       ActiveSupport.on_load(:active_job) do
         require 'servus/extensions/async/ext'
-        # Extend the base service with the async call method
         Servus::Base.extend Servus::Extensions::Async::Call
       end
     end
 
+    initializer 'servus.lazily' do
+      ActiveSupport.on_load(:active_record) do
+        require 'servus/extensions/lazily/ext'
+        Servus::Base.extend Servus::Extensions::Lazily::Call
+      end
+    end
+
     # Load guards and event handlers, clear caches on reload
     config.to_prepare do
       # Load custom guards from guards_dir

data/lib/servus/support/data_object.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Servus
+  module Support
+    # A read-only wrapper around Hash data that provides accessor-style access.
+    #
+    # When service results contain Hash data, +DataObject+ wraps it so keys can be
+    # accessed as methods in addition to the standard bracket syntax. Nested Hashes
+    # are recursively wrapped, enabling chained access like +data.user.address.city+.
+    #
+    # Non-Hash values (nil, String, Integer, Array, model instances) pass through
+    # unwrapped. This means +data.user+ returns the original object when +user+ is
+    # an ActiveRecord model, allowing natural method chaining (+data.user.email+).
+    #
+    # +DataObject+ inherits from +SimpleDelegator+, so all standard Hash methods
+    # (+[]+, +keys+, +each+, +as_json+, +==+, etc.) are delegated transparently.
+    #
+    # @example Accessor-style access
+    #   data = DataObject.wrap({ user: { email: "alice@example.com" } })
+    #   data.user.email   # => "alice@example.com"
+    #   data[:user]        # => { email: "alice@example.com" } (plain Hash)
+    #
+    # @example Mixed values
+    #   data = DataObject.wrap({ user: user_model, metadata: { source: "api" } })
+    #   data.user.email       # => delegates to model's #email method
+    #   data.metadata.source  # => "api" (wrapped Hash accessor)
+    #
+    # @see Servus::Support::Response
+    class DataObject < SimpleDelegator
+      # Wraps a value in a DataObject if it is a Hash.
+      #
+      # Non-Hash values are returned unchanged. This is the preferred way to
+      # create DataObject instances, as it handles nil and non-Hash types safely.
+      #
+      # @param data [Object] the value to potentially wrap
+      # @return [DataObject] if data is a Hash
+      # @return [Array] with Hash elements wrapped if data is an Array
+      # @return [Object] the original value otherwise
+      def self.wrap(data)
+        case data
+        when Hash  then new(data)
+        when Array then data.map { |item| wrap(item) }
+        else data
+        end
+      end
+
+      private
+
+      # Provides accessor-style access to Hash keys.
+      #
+      # Only zero-argument, no-block calls trigger key lookup. Methods with
+      # arguments (e.g., +fetch+, +dig+) delegate to Hash normally.
+      # When the value is a Hash, it is recursively wrapped in a DataObject.
+      #
+      # @param method_name [Symbol] the method name to look up as a key
+      # @return [Object] the value for the key, wrapped if it is a Hash
+      # @raise [NoMethodError] if the key does not exist
+      def method_missing(method_name, *args, &block)
+        return super if args.any? || block
+
+        hash = __getobj__
+        if hash.key?(method_name.to_sym)
+          self.class.wrap(hash[method_name.to_sym])
+        elsif hash.key?(method_name.to_s)
+          self.class.wrap(hash[method_name.to_s])
+        else
+          super
+        end
+      end
+
+      # @api private
+      def respond_to_missing?(method_name, include_private = false)
+        hash = __getobj__
+        hash.key?(method_name.to_sym) || hash.key?(method_name.to_s) || super
+      end
+    end
+  end
+end

data/lib/servus/support/response.rb

@@ -51,7 +51,7 @@ module Servus
       # @api private
       def initialize(success, data, error)
         @success = success
-        @data = data
+        @data = DataObject.wrap(data)
         @error = error
       end
 
@@ -69,6 +69,17 @@ module Servus
       def success?
         @success
       end
+
+      # Checks if the service execution failed.
+      #
+      # @return [Boolean] true if the service failed, false if it succeeded
+      #
+      # @example
+      #   result = MyService.call(params)
+      #   return render_error(result.error.message) if result.failure?
+      def failure?
+        !@success
+      end
     end
   end
 end

data/lib/servus/support/validator.rb

@@ -58,11 +58,11 @@ module Servus
         true
       end
 
-      # Validates service result data against the RESULT_SCHEMA.
+      # Validates service result data against the appropriate schema.
       #
-      # Checks the result.data against either an inline RESULT_SCHEMA constant or
-      # a file-based schema at app/schemas/services/namespace/result.json.
-      # Only validates successful responses; failures are skipped.
+      # For successful responses, validates against the +result+ schema.
+      # For failure responses with data, validates against the +failure+ schema.
+      # Failure responses without data are skipped.
       #
       # @param service_class [Class] the service class being validated
       # @param result [Servus::Support::Response] the response object to validate
@@ -74,16 +74,15 @@ module Servus
       #
       # @api private
       def self.validate_result!(service_class, result)
-        return result unless result.success?
-
-        schema = load_schema(service_class, 'result')
-        return result unless schema # Skip validation if no schema exists
+        schema = result_schema_for(service_class, result)
+        return result unless schema
 
         serialized_result = result.data.as_json
         validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
 
         if validation_errors.any?
-          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(', ')}"
+          schema_type = result.success? ? 'result' : 'failure'
+          error_message = "Invalid #{schema_type} structure from #{service_class.name}: #{validation_errors.join(', ')}"
           raise Servus::Base::ValidationError, error_message
         end
 
@@ -127,7 +126,7 @@ module Servus
       # Schemas are cached after first load for performance.
       #
       # @param service_class [Class] the service class
-      # @param type [String] schema type ("arguments" or "result")
+      # @param type [String] schema type ("arguments", "result", or "failure")
       # @return [Hash, nil] the schema hash, or nil if no schema found
       #
       # @api private
@@ -141,10 +140,10 @@ module Servus
         return @schema_cache[schema_path] if @schema_cache.key?(schema_path)
 
         # Check for DSL-defined schema first
-        dsl_schema = if type == 'arguments'
-                       service_class.arguments_schema
-                     else
-                       service_class.result_schema
+        dsl_schema = case type
+                     when 'arguments' then service_class.arguments_schema
+                     when 'result'    then service_class.result_schema
+                     when 'failure'   then service_class.failure_schema
                      end
 
         inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
@@ -180,6 +179,21 @@ module Servus
         @schema_cache
       end
 
+      # Resolves the appropriate schema for a result based on its success/failure state.
+      #
+      # @param service_class [Class] the service class
+      # @param result [Servus::Support::Response] the response to resolve schema for
+      # @return [Hash, nil] the schema, or nil if none applies
+      #
+      # @api private
+      def self.result_schema_for(service_class, result)
+        if result.success?
+          load_schema(service_class, 'result')
+        elsif result.data
+          load_schema(service_class, 'failure')
+        end
+      end
+
       # Fetches schema from DSL, inline constant, or file.
       #
       # Implements the schema resolution precedence:

data/lib/servus/testing/example_builders.rb

@@ -116,6 +116,28 @@ module Servus
         Servus::Support::Response.new(true, example, nil)
       end
 
+      # Extracts example failure data values from a service's schema.
+      #
+      # Looks for `example` or `examples` keywords in the service's failure schema
+      # and returns them wrapped in a failure Response. Useful for validating failure
+      # response structure in tests.
+      #
+      # @param service_class [Class] The service class to extract examples from
+      # @param overrides [Hash] Optional values to override the schema examples
+      # @return [Servus::Support::Response] Failure response object with example data
+      #
+      # @example Basic usage
+      #   expected = servus_failure_example(ProcessPayment::Service)
+      #   # => Servus::Support::Response with failure? == true, data:
+      #   #    { reason: 'card_declined', decline_code: 'insufficient_funds' }
+      #
+      # @note Override keys can be strings or symbols; they'll be converted to symbols
+      # @note Returns empty hash if service has no failure schema defined
+      def servus_failure_example(service_class, overrides = {})
+        example = extract_example_from(service_class, :failure, overrides)
+        Servus::Support::Response.new(false, example, Servus::Support::Errors::ServiceError.new)
+      end
+
       private
 
       # Helper method to extract and merge examples from schema

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/servus.rb

@@ -20,6 +20,7 @@ require_relative 'servus/config'
 
 # Support
 require_relative 'servus/support/logger'
+require_relative 'servus/support/data_object'
 require_relative 'servus/support/response'
 require_relative 'servus/support/validator'
 require_relative 'servus/support/errors'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -27,14 +27,14 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 - !ruby/object:Gem::Dependency
@@ -55,14 +55,14 @@ dependencies:
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 description: Servus is a Ruby gem that provides a structured way to create and manage
@@ -97,6 +97,7 @@ files:
 - docs/features/4_logging.md
 - docs/features/5_event_bus.md
 - docs/features/6_guards.md
+- docs/features/7_lazy_resolvers.md
 - docs/features/guards_naming_convention.md
 - docs/guides/1_common_patterns.md
 - docs/guides/2_migration_guide.md
@@ -203,6 +204,10 @@ files:
 - lib/servus/extensions/async/errors.rb
 - lib/servus/extensions/async/ext.rb
 - lib/servus/extensions/async/job.rb
+- lib/servus/extensions/lazily/call.rb
+- lib/servus/extensions/lazily/errors.rb
+- lib/servus/extensions/lazily/ext.rb
+- lib/servus/extensions/lazily/resolver.rb
 - lib/servus/guard.rb
 - lib/servus/guards.rb
 - lib/servus/guards/falsey_guard.rb
@@ -211,6 +216,7 @@ files:
 - lib/servus/guards/truthy_guard.rb
 - lib/servus/helpers/controller_helpers.rb
 - lib/servus/railtie.rb
+- lib/servus/support/data_object.rb
 - lib/servus/support/errors.rb
 - lib/servus/support/logger.rb
 - lib/servus/support/message_resolver.rb
@@ -245,7 +251,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A gem for managing service objects.
 test_files: []