senro_usecaser 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da485bb1bbc5f14668b4e79b4e3a1e840e4e749a2925cc80ad286e2df33732b7
-  data.tar.gz: 5313ff78401d64d823d6691f9c659c58bcf357843e9ee97c3636a584cdf99635
+  metadata.gz: cbfc07ede41cc295ceb0a019774a480744b226e88edc46f72a6447d59375f4e4
+  data.tar.gz: b86aaade8ccc9f2479f18d0f3bd5204203718ce26740eb3a51b5cccf1ed06798
 SHA512:
-  metadata.gz: 31e26879fc113e25048d9fde410066837502697308ca6973fe313417fe6cd6be198ef9917c9e5110ae51085032f683d66f920642557e2dd30a179af4aecaa1d7
-  data.tar.gz: 3957e5c91c088dde9e692101ca8db16840289caedb22bb9bf15a242a31da07898124841582ed8ec8eb9c4699e0b64d2805d04c52683245f51341d64cbc57b768
+  metadata.gz: 2ce95671ffefc951140c3625db940f1b077fe8bf40138d790b25067ab010a087d9f96b6c2e31bab2819ea89f0b2e6e905c70288f9409e24782cd73a0bca832cd
+  data.tar.gz: aa3b27b6eff694929f8cfc33ca47e5d7fb450eeb4ac5da9fecba2023cc70393a2edfa1b033e89d0fe0f0e1abe5cda3817841e8b92e04294062c0cd4a02ef8879

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-01-31
+
+### Added
+
+- **Runtime type validation for input**
+  - `input` now accepts Module(s) for interface-based validation
+  - Single module: `input HasUserId` - validates that input's class includes the module
+  - Multiple modules: `input HasUserId, HasEmail` - validates that input's class includes all modules
+  - Class validation remains supported for backwards compatibility
+- **Runtime type validation for output**
+  - When `output` is declared with a Class, the success result's value is validated
+  - Raises `TypeError` if the output value is not an instance of the declared class
+  - Hash schema (`output({ key: Type })`) skips validation for backwards compatibility
+- **New class methods**
+  - `input_types` - Returns an array of declared input types (Module/Class)
+  - `input_class` - Backwards compatible method, returns Class if specified or first type
+
+### Changed
+
+- Type validation errors raise exceptions with `.call` and return `Result.failure` with `.call!`
+  - Input validation: `ArgumentError`
+  - Output validation: `TypeError`
+
+## [0.2.0] - 2026-01-31
+
+### Added
+
+- **Hook class with dependency injection** - New `SenroUsecaser::Hook` base class for creating hooks with `depends_on` support
+  - Supports `namespace` declaration for scoped dependency resolution
+  - Supports `infer_namespace_from_module` configuration
+  - Can inherit namespace from the UseCase when not explicitly declared
+- **Block hooks can access dependencies**
+  - `before` and `after` blocks now run in instance context via `instance_exec`
+  - Dependencies declared with `depends_on` are directly accessible in block hooks
+
+### Changed
+
+- **Around block signature** - Changed from `|input, &block|` to `|input, use_case, &block|`
+  - The `use_case` argument provides access to dependencies
+- **Input class is now mandatory** - All UseCases must define an `input` class
+- **Renamed `context` to `input`** - Hook parameters renamed for clarity
+
+## [0.1.0] - 2026-01-30
+
+- Initial release

data/README.md

@@ -442,6 +442,179 @@ end
 
 The `**_rest` parameter in Input's initialize allows extra fields to be passed through pipeline steps without errors.
 
+### Runtime Type Validation
+
+In addition to static type checking with RBS, SenroUsecaser provides runtime type validation for Input and Output. This ensures that the actual values passed at runtime match the expected types.
+
+#### Input Type Validation
+
+The `input` declaration supports three patterns:
+
+##### 1. Class Validation (Traditional)
+
+When a Class is specified, input must be an instance of that class:
+
+```ruby
+class CreateUserUseCase < SenroUsecaser::Base
+  input CreateUserInput  # Class
+
+  def call(input)
+    # input must be a CreateUserInput instance
+    success(input.name)
+  end
+end
+
+# OK
+CreateUserUseCase.call(CreateUserInput.new(name: "Taro"))
+
+# ArgumentError: Input must be an instance of CreateUserInput, got String
+CreateUserUseCase.call("invalid")
+```
+
+##### 2. Interface Validation (Single Module)
+
+When a Module is specified, input's class must include that module. This enables duck-typing with explicit interface contracts:
+
+```ruby
+# Define interface
+module HasUserId
+  def user_id
+    raise NotImplementedError
+  end
+end
+
+# UseCase expects input that includes HasUserId
+class FindUserUseCase < SenroUsecaser::Base
+  input HasUserId
+
+  #: (HasUserId) -> SenroUsecaser::Result[User]
+  def call(input)
+    user = User.find(input.user_id)
+    success(user)
+  end
+end
+
+# Input class that implements the interface
+class UserQuery
+  include HasUserId
+
+  attr_reader :user_id
+
+  def initialize(user_id:)
+    @user_id = user_id
+  end
+end
+
+# OK - UserQuery includes HasUserId
+FindUserUseCase.call(UserQuery.new(user_id: 123))
+
+# ArgumentError: Input UserQuery must include HasUserId
+class InvalidInput
+  attr_reader :user_id
+  def initialize(user_id:) = @user_id = user_id
+end
+FindUserUseCase.call(InvalidInput.new(user_id: 123))
+```
+
+##### 3. Multiple Interfaces Validation
+
+Multiple Modules can be specified. The input must include ALL of them:
+
+```ruby
+module HasUserId
+  def user_id = raise NotImplementedError
+end
+
+module HasEmail
+  def email = raise NotImplementedError
+end
+
+# UseCase requires both interfaces
+class NotifyUserUseCase < SenroUsecaser::Base
+  input HasUserId, HasEmail
+
+  #: ((HasUserId & HasEmail)) -> SenroUsecaser::Result[bool]
+  def call(input)
+    notify(input.user_id, input.email)
+    success(true)
+  end
+end
+
+# Input class must include both modules
+class NotificationRequest
+  include HasUserId
+  include HasEmail
+
+  attr_reader :user_id, :email
+
+  def initialize(user_id:, email:)
+    @user_id = user_id
+    @email = email
+  end
+end
+
+# OK
+NotifyUserUseCase.call(NotificationRequest.new(user_id: 123, email: "test@example.com"))
+```
+
+##### Interface Pattern in Pipelines
+
+Interface validation is especially useful for sub-UseCases in pipelines. A parent UseCase's Input can include multiple interfaces, and each step only requires the interfaces it needs:
+
+```ruby
+# Parent UseCase - Input includes both interfaces
+class ProcessOrderUseCase < SenroUsecaser::Base
+  class Input
+    include HasUserId
+    include HasEmail
+
+    attr_reader :user_id, :email, :order_items
+
+    def initialize(user_id:, email:, order_items:)
+      @user_id = user_id
+      @email = email
+      @order_items = order_items
+    end
+  end
+
+  input Input
+
+  organize do
+    step FindUserUseCase      # Only needs HasUserId
+    step NotifyUserUseCase    # Needs HasUserId and HasEmail
+    step CreateOrderUseCase
+  end
+end
+```
+
+#### Output Type Validation
+
+When `output` is declared with a Class, the success result's value is validated:
+
+```ruby
+class UserOutput
+  attr_reader :user
+  def initialize(user:) = @user = user
+end
+
+class FindUserUseCase < SenroUsecaser::Base
+  input FindUserInput
+  output UserOutput  # Class declaration enables validation
+
+  def call(input)
+    user = User.find(input.user_id)
+    success(UserOutput.new(user: user))  # OK
+
+    # TypeError: Output must be an instance of UserOutput, got User
+    # success(user)  # Wrong! Must wrap in UserOutput
+  end
+end
+```
+
+**Note:** When `output` is a Hash schema (e.g., `output({ user: User })`), validation is skipped for backwards compatibility.
+
+**Note:** Type validation errors raise exceptions (`ArgumentError` for input, `TypeError` for output). See [`.call` vs `.call!`](#call-vs-call-1) for how exceptions are handled.
+
 ### Simplicity
 
 Define UseCases with minimal boilerplate. Avoids over-abstraction and provides an intuitive API.
@@ -659,20 +832,30 @@ end
 
 ##### Block Syntax
 
+Block hooks are executed in the UseCase instance context, allowing access to `depends_on` dependencies.
+
 ```ruby
 class CreateUserUseCase < SenroUsecaser::Base
+  depends_on :logger
+  depends_on :metrics
+  input Input
+
+  # before/after blocks can access dependencies directly
   before do |input|
-    # runs before call
+    logger.info("Starting with #{input.class.name}")
   end
 
   after do |input, result|
-    # runs after call
+    logger.info("Finished: #{result.success? ? 'success' : 'failure'}")
+    metrics.increment(:use_case_completed)
   end
 
-  around do |input, &block|
-    ActiveRecord::Base.transaction do
-      block.call
-    end
+  # around block receives use_case as second argument for dependency access
+  around do |input, use_case, &block|
+    use_case.logger.info("Transaction start")
+    result = ActiveRecord::Base.transaction { block.call }
+    use_case.logger.info("Transaction end")
+    result
   end
 
   def call(input)
@@ -681,6 +864,77 @@ class CreateUserUseCase < SenroUsecaser::Base
 end
 ```
 
+##### Hook Classes
+
+For more complex hooks with their own dependencies, use `SenroUsecaser::Hook` class:
+
+```ruby
+class LoggingHook < SenroUsecaser::Hook
+  depends_on :logger
+  depends_on :metrics
+
+  def before(input)
+    logger.info("Starting with #{input.class.name}")
+  end
+
+  def after(input, result)
+    logger.info("Finished: #{result.success? ? 'success' : 'failure'}")
+    metrics.increment(:use_case_completed)
+  end
+
+  def around(input)
+    logger.info("Around start")
+    result = yield
+    logger.info("Around end")
+    result
+  end
+end
+
+class CreateUserUseCase < SenroUsecaser::Base
+  extend_with LoggingHook
+
+  def call(input)
+    # main logic
+  end
+end
+```
+
+Hook classes support:
+- `depends_on` for dependency injection
+- `namespace` for scoped dependency resolution
+- Automatic namespace inference from module structure (when `infer_namespace_from_module` is enabled)
+- Inheriting namespace from the UseCase if not explicitly declared
+
+```ruby
+# Hook with explicit namespace
+class Admin::AuditHook < SenroUsecaser::Hook
+  namespace :admin
+  depends_on :audit_logger
+
+  def after(input, result)
+    audit_logger.log(action: "create", success: result.success?)
+  end
+end
+
+# Hook inheriting namespace from UseCase
+class MetricsHook < SenroUsecaser::Hook
+  depends_on :metrics  # resolved from UseCase's namespace
+
+  def after(input, result)
+    metrics.increment(:completed)
+  end
+end
+
+class Admin::CreateUserUseCase < SenroUsecaser::Base
+  namespace :admin
+  extend_with MetricsHook  # metrics resolved from :admin namespace
+
+  def call(input)
+    # ...
+  end
+end
+```
+
 ##### Input/Output Validation
 
 Use `extend_with` to integrate validation libraries like ActiveModel::Validations:
@@ -926,6 +1180,28 @@ end
 
 Use `.call!` when you want to ensure all exceptions are captured as `Result.failure` without explicit rescue blocks in your UseCase.
 
+**Type validation errors** (from `input` and `output` declarations) also follow this pattern:
+
+```ruby
+# With .call - type validation errors raise exceptions
+begin
+  UseCase.call(invalid_input)
+rescue ArgumentError => e
+  puts e.message  # "Input SomeClass must include HasUserId"
+end
+
+# With .call! - type validation errors become Result.failure
+result = UseCase.call!(invalid_input)
+result.failure?              # => true
+result.errors.first.code     # => :exception
+result.errors.first.message  # => "Input SomeClass must include HasUserId"
+```
+
+| Validation | Exception type | With `.call` | With `.call!` |
+|------------|---------------|--------------|---------------|
+| Input type | `ArgumentError` | Raises | `Result.failure` |
+| Output type | `TypeError` | Raises | `Result.failure` |
+
 #### Exception Handling in Pipelines
 
 When using `.call!` with `organize` pipelines, the exception capture behavior is **chained** to all steps. This is especially useful with `on_failure: :collect`:

data/lib/senro_usecaser/base.rb

@@ -262,8 +262,9 @@ module SenroUsecaser
       end
 
       # Adds an around hook
+      # Block receives (input, use_case, &block) where use_case allows access to dependencies
       #
-      #: () { (untyped) { () -> Result[untyped] } -> Result[untyped] } -> void
+      #: () { (untyped, Base) { () -> Result[untyped] } -> Result[untyped] } -> void
       def around(&block)
         around_hooks << block if block
       end
@@ -275,17 +276,41 @@ module SenroUsecaser
         @around_hooks ||= []
       end
 
-      # Declares the expected input type for this UseCase
+      # Declares the expected input type(s) for this UseCase
+      # Accepts a Class or one or more Modules that input must include
       #
-      #: (Class) -> void
-      def input(type)
-        @input_class = type
+      # @example Single class
+      #   input UserInput
+      #
+      # @example Single module (interface)
+      #   input HasUserId
+      #
+      # @example Multiple modules (interfaces)
+      #   input HasUserId, HasEmail
+      #
+      #: (*Module) -> void
+      def input(*types)
+        @input_types = types
       end
 
-      # Returns the input class
+      # Returns the input types as an array
       #
-      #: () -> Class?
-      attr_reader :input_class
+      #: () -> Array[Module]
+      def input_types
+        @input_types || []
+      end
+
+      # Returns the input class (for backwards compatibility)
+      # If a Class is specified, returns it. Otherwise returns the first type.
+      #
+      #: () -> Module?
+      def input_class
+        types = input_types
+        return nil if types.empty?
+
+        # Class があればそれを返す（単一 Class 指定の後方互換）
+        types.find { |t| t.is_a?(Class) } || types.first
+      end
 
       # Declares the expected output type for this UseCase
       #
@@ -339,7 +364,7 @@ module SenroUsecaser
         subclass.instance_variable_set(:@use_case_namespace, @use_case_namespace)
         subclass.instance_variable_set(:@organized_steps, @organized_steps&.dup)
         subclass.instance_variable_set(:@on_failure_strategy, @on_failure_strategy)
-        subclass.instance_variable_set(:@input_class, @input_class)
+        subclass.instance_variable_set(:@input_types, @input_types&.dup)
         subclass.instance_variable_set(:@output_schema, @output_schema)
       end
 
@@ -371,6 +396,8 @@ module SenroUsecaser
         raise ArgumentError, "#{self.class.name} must define `input` class"
       end
 
+      validate_input!(input)
+
       execute_with_hooks(input) do
         call(input)
       end
@@ -415,6 +442,48 @@ module SenroUsecaser
       Result.capture(*exception_classes, code: code, &)
     end
 
+    # Validates that input satisfies all declared input types
+    # For Modules: checks if input's class includes the module
+    # For Classes: checks if input is an instance of the class
+    #
+    #: (untyped) -> void
+    def validate_input!(input)
+      types = self.class.input_types
+      return if types.empty?
+
+      types.each do |expected_type|
+        if expected_type.is_a?(Module) && !expected_type.is_a?(Class)
+          # Module の場合: include しているかを検査
+          unless input.class.include?(expected_type)
+            raise ArgumentError,
+                  "Input #{input.class} must include #{expected_type}"
+          end
+        elsif !input.is_a?(expected_type)
+          # Class の場合: インスタンスかを検査
+          raise ArgumentError,
+                "Input must be an instance of #{expected_type}, got #{input.class}"
+        end
+      end
+    end
+
+    # Validates that the result's value satisfies the declared output type
+    # Only validates if result is success and output_schema is a Class
+    #
+    #: (Result[untyped]) -> void
+    def validate_output!(result)
+      return unless result.success?
+
+      expected_type = self.class.output_schema
+      return if expected_type.nil?
+      return unless expected_type.is_a?(Class)
+
+      value = result.value
+      return if value.is_a?(expected_type)
+
+      raise TypeError,
+            "Output must be an instance of #{expected_type}, got #{value.class}"
+    end
+
     # Executes the core logic with before/after/around hooks
     #
     #: (untyped) { () -> Result[untyped] } -> Result[untyped]
@@ -422,6 +491,7 @@ module SenroUsecaser
       execution = build_around_chain(input, core_block)
       run_before_hooks(input)
       result = execution.call
+      validate_output!(result)
       run_after_hooks(input, result)
       result
     end
@@ -440,22 +510,39 @@ module SenroUsecaser
     #: (untyped, Proc) -> Proc
     def build_around_chain(input, core_block)
       wrapped_core = -> { wrap_result(core_block.call) }
-      all_around_hooks = collect_around_hooks
+      chain = wrap_extension_around_hooks(input, wrapped_core)
+      wrap_block_around_hooks(input, chain)
+    end
 
-      all_around_hooks.reverse.reduce(wrapped_core) do |inner, hook|
+    # Wraps extension/module around hooks
+    #
+    #: (untyped, Proc) -> Proc
+    def wrap_extension_around_hooks(input, chain)
+      collect_extension_around_hooks.reverse.reduce(chain) do |inner, hook|
         -> { wrap_result(hook.call(input) { inner.call }) }
       end
     end
 
-    # Collects all around hooks from extensions and block-based hooks
+    # Wraps block-based around hooks (pass self as second argument)
+    #
+    #: (untyped, Proc) -> Proc
+    def wrap_block_around_hooks(input, chain)
+      use_case_instance = self
+      self.class.around_hooks.reverse.reduce(chain) do |inner, hook|
+        -> { wrap_result(hook.call(input, use_case_instance) { inner.call }) }
+      end
+    end
+
+    # Collects around hooks from Hook classes and extension modules (not block-based)
     #
     #: () -> Array[Proc]
-    def collect_around_hooks
-      hooks = [] #: Array[Proc]
+    def collect_extension_around_hooks
+      hooks = hook_instances.map { |hook_instance| hook_instance.method(:around).to_proc }
       self.class.extensions.each do |ext|
+        next if hook_class?(ext)
+
         hooks << ext.method(:around).to_proc if ext.respond_to?(:around)
       end
-      hooks.concat(self.class.around_hooks)
       hooks
     end
 
@@ -463,20 +550,49 @@ module SenroUsecaser
     #
     #: (untyped) -> void
     def run_before_hooks(input)
+      hook_instances.each do |hook_instance|
+        hook_instance.before(input)
+      end
       self.class.extensions.each do |ext|
+        next if hook_class?(ext)
+
         ext.send(:before, input) if ext.respond_to?(:before)
       end
-      self.class.before_hooks.each { |hook| hook.call(input) }
+      self.class.before_hooks.each { |hook| instance_exec(input, &hook) } # steep:ignore BlockTypeMismatch
     end
 
     # Runs all after hooks
     #
     #: (untyped, Result[untyped]) -> void
     def run_after_hooks(input, result)
+      hook_instances.each do |hook_instance|
+        hook_instance.after(input, result)
+      end
       self.class.extensions.each do |ext|
+        next if hook_class?(ext)
+
         ext.send(:after, input, result) if ext.respond_to?(:after)
       end
-      self.class.after_hooks.each { |hook| hook.call(input, result) }
+      self.class.after_hooks.each { |hook| instance_exec(input, result, &hook) } # steep:ignore BlockTypeMismatch
+    end
+
+    # Returns instantiated hook objects
+    #
+    #: () -> Array[Hook]
+    def hook_instances
+      @hook_instances ||= self.class.extensions.filter_map do |ext|
+        next unless hook_class?(ext)
+
+        hook_class = ext #: singleton(Hook)
+        hook_class.new(container: @_container, use_case_namespace: effective_namespace)
+      end
+    end
+
+    # Checks if the extension is a Hook class
+    #
+    #: (untyped) -> bool
+    def hook_class?(ext)
+      ext.is_a?(Class) && ext < Hook
     end
 
     # Resolves dependencies from the container
@@ -645,12 +761,12 @@ module SenroUsecaser
     end
 
     # Calls a single UseCase in the pipeline
-    # Requires input_class to be defined for pipeline steps
+    # Requires input type(s) to be defined for pipeline steps
     #
     #: (singleton(Base), untyped) -> Result[untyped]
     def call_use_case(use_case_class, input)
-      unless use_case_class.input_class
-        raise ArgumentError, "#{use_case_class.name} must define `input` class to be used in a pipeline"
+      if use_case_class.input_types.empty?
+        raise ArgumentError, "#{use_case_class.name} must define `input` type(s) to be used in a pipeline"
       end
 
       call_method = @_capture_exceptions || false ? :call! : :call #: Symbol

data/lib/senro_usecaser/hook.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Base class for hooks with dependency injection support
+  #
+  # Hook classes provide a way to define before/after/around hooks
+  # with access to the DI container and automatic dependency resolution.
+  #
+  # @example Basic hook
+  #   class LoggingHook < SenroUsecaser::Hook
+  #     depends_on :logger, Logger
+  #
+  #     def before(input)
+  #       logger.info("Starting with #{input.class.name}")
+  #     end
+  #
+  #     def after(input, result)
+  #       logger.info("Finished: #{result.success? ? 'success' : 'failure'}")
+  #     end
+  #   end
+  #
+  # @example Hook with namespace
+  #   class Admin::AuditHook < SenroUsecaser::Hook
+  #     namespace :admin
+  #     depends_on :audit_logger, AuditLogger
+  #
+  #     def after(input, result)
+  #       audit_logger.log(input: input, result: result)
+  #     end
+  #   end
+  #
+  # @example Hook with around
+  #   class TransactionHook < SenroUsecaser::Hook
+  #     def around(input)
+  #       ActiveRecord::Base.transaction { yield }
+  #     end
+  #   end
+  class Hook
+    class << self
+      # Declares a dependency to be injected from the container
+      #
+      #: (Symbol, ?Class) -> void
+      def depends_on(name, type = nil)
+        dependencies << name unless dependencies.include?(name)
+        dependency_types[name] = type if type
+
+        define_method(name) do
+          @_dependencies[name]
+        end
+      end
+
+      # Returns the list of declared dependencies
+      #
+      #: () -> Array[Symbol]
+      def dependencies
+        @dependencies ||= []
+      end
+
+      # Returns the dependency type mapping
+      #
+      #: () -> Hash[Symbol, Class]
+      def dependency_types
+        @dependency_types ||= {}
+      end
+
+      # Sets or returns the namespace for dependency resolution
+      #
+      #: (?(Symbol | String)) -> (Symbol | String)?
+      def namespace(name = nil)
+        if name
+          @hook_namespace = name
+        else
+          @hook_namespace
+        end
+      end
+
+      # Alias for namespace() without arguments
+      #
+      #: () -> (Symbol | String)?
+      def hook_namespace # rubocop:disable Style/TrivialAccessors
+        @hook_namespace
+      end
+
+      # @api private
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@dependencies, dependencies.dup)
+        subclass.instance_variable_set(:@dependency_types, dependency_types.dup)
+        subclass.instance_variable_set(:@hook_namespace, @hook_namespace)
+      end
+    end
+
+    # Initializes the hook with dependencies resolved from the container
+    #
+    #: (container: Container, ?use_case_namespace: (Symbol | String)?) -> void
+    def initialize(container:, use_case_namespace: nil)
+      @_container = container
+      @_use_case_namespace = use_case_namespace
+      @_dependencies = {} #: Hash[Symbol, untyped]
+
+      resolve_dependencies
+    end
+
+    # Called before the UseCase executes
+    # Override in subclass to add before logic
+    #
+    #: (untyped) -> void
+    def before(input)
+      # Override in subclass
+    end
+
+    # Called after the UseCase executes
+    # Override in subclass to add after logic
+    #
+    #: (untyped, Result[untyped]) -> void
+    def after(input, result)
+      # Override in subclass
+    end
+
+    # Wraps the UseCase execution
+    # Override in subclass to add around logic
+    #
+    #: (untyped) { () -> Result[untyped] } -> Result[untyped]
+    def around(_input)
+      yield
+    end
+
+    private
+
+    # Returns the effective namespace for dependency resolution
+    #
+    #: () -> (Symbol | String)?
+    def effective_namespace
+      return self.class.hook_namespace if self.class.hook_namespace
+      return @_use_case_namespace if @_use_case_namespace
+      return nil unless SenroUsecaser.configuration.infer_namespace_from_module
+
+      infer_namespace_from_class
+    end
+
+    # Infers namespace from the class's module structure
+    #
+    #: () -> String?
+    def infer_namespace_from_class
+      class_name = self.class.name
+      return nil unless class_name
+
+      parts = class_name.split("::")
+      return nil if parts.length <= 1
+
+      module_parts = parts[0...-1] || [] #: Array[String]
+      return nil if module_parts.empty?
+
+      module_parts.map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2').downcase }.join("::")
+    end
+
+    # Resolves dependencies from the container
+    #
+    #: () -> void
+    def resolve_dependencies
+      self.class.dependencies.each do |name|
+        @_dependencies[name] = resolve_from_container(name)
+      end
+    end
+
+    # Resolves a single dependency from the container
+    #
+    #: (Symbol) -> untyped
+    def resolve_from_container(name)
+      namespace = effective_namespace
+      if namespace
+        @_container.resolve_in(namespace, name)
+      else
+        @_container.resolve(name)
+      end
+    end
+  end
+end

data/lib/senro_usecaser/provider.rb

@@ -72,7 +72,7 @@ module SenroUsecaser
       #     enabled_if { Rails.env.development? }
       #   end
       #
-      #: () { () -> bool } -> void
+      #: () { () -> boolish } -> void
       def enabled_if(&block)
         @enabled_condition = block
       end

data/lib/senro_usecaser/version.rb

@@ -4,5 +4,5 @@
 
 module SenroUsecaser
   #: String
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/senro_usecaser.rb

@@ -8,6 +8,7 @@ require_relative "senro_usecaser/result"
 require_relative "senro_usecaser/container"
 require_relative "senro_usecaser/configuration"
 require_relative "senro_usecaser/provider"
+require_relative "senro_usecaser/hook"
 require_relative "senro_usecaser/base"
 
 # SenroUsecaser is a type-safe UseCase pattern implementation library for Ruby.

data/sig/generated/senro_usecaser/base.rbs

@@ -178,8 +178,9 @@ module SenroUsecaser
     def self.after_hooks: () -> Array[Proc]
 
     # Adds an around hook
+    # Block receives (input, use_case, &block) where use_case allows access to dependencies
     #
-    # : () { (untyped) { () -> Result[untyped] } -> Result[untyped] } -> void
+    # : () { (untyped, Base) { () -> Result[untyped] } -> Result[untyped] } -> void
     def self.around: () ?{ (?) -> untyped } -> untyped
 
     # Returns the list of around hooks
@@ -187,15 +188,31 @@ module SenroUsecaser
     # : () -> Array[Proc]
     def self.around_hooks: () -> Array[Proc]
 
-    # Declares the expected input type for this UseCase
+    # Declares the expected input type(s) for this UseCase
+    # Accepts a Class or one or more Modules that input must include
     #
-    # : (Class) -> void
-    def self.input: (Class) -> void
+    # @example Single class
+    #   input UserInput
+    #
+    # @example Single module (interface)
+    #   input HasUserId
+    #
+    # @example Multiple modules (interfaces)
+    #   input HasUserId, HasEmail
+    #
+    # : (*Module) -> void
+    def self.input: (*Module) -> void
 
-    # Returns the input class
+    # Returns the input types as an array
     #
-    # : () -> Class?
-    attr_reader input_class: untyped
+    # : () -> Array[Module]
+    def self.input_types: () -> Array[Module]
+
+    # Returns the input class (for backwards compatibility)
+    # If a Class is specified, returns it. Otherwise returns the first type.
+    #
+    # : () -> Module?
+    def self.input_class: () -> Module?
 
     # Declares the expected output type for this UseCase
     #
@@ -266,6 +283,19 @@ module SenroUsecaser
     # : [T] (*Class, ?code: Symbol) { () -> T } -> Result[T]
     def capture: [T] (*Class, ?code: Symbol) { () -> T } -> Result[T]
 
+    # Validates that input satisfies all declared input types
+    # For Modules: checks if input's class includes the module
+    # For Classes: checks if input is an instance of the class
+    #
+    # : (untyped) -> void
+    def validate_input!: (untyped) -> void
+
+    # Validates that the result's value satisfies the declared output type
+    # Only validates if result is success and output_schema is a Class
+    #
+    # : (Result[untyped]) -> void
+    def validate_output!: (Result[untyped]) -> void
+
     # Executes the core logic with before/after/around hooks
     #
     # : (untyped) { () -> Result[untyped] } -> Result[untyped]
@@ -281,10 +311,20 @@ module SenroUsecaser
     # : (untyped, Proc) -> Proc
     def build_around_chain: (untyped, Proc) -> Proc
 
-    # Collects all around hooks from extensions and block-based hooks
+    # Wraps extension/module around hooks
+    #
+    # : (untyped, Proc) -> Proc
+    def wrap_extension_around_hooks: (untyped, Proc) -> Proc
+
+    # Wraps block-based around hooks (pass self as second argument)
+    #
+    # : (untyped, Proc) -> Proc
+    def wrap_block_around_hooks: (untyped, Proc) -> Proc
+
+    # Collects around hooks from Hook classes and extension modules (not block-based)
     #
     # : () -> Array[Proc]
-    def collect_around_hooks: () -> Array[Proc]
+    def collect_extension_around_hooks: () -> Array[Proc]
 
     # Runs all before hooks
     #
@@ -296,6 +336,16 @@ module SenroUsecaser
     # : (untyped, Result[untyped]) -> void
     def run_after_hooks: (untyped, Result[untyped]) -> void
 
+    # Returns instantiated hook objects
+    #
+    # : () -> Array[Hook]
+    def hook_instances: () -> Array[Hook]
+
+    # Checks if the extension is a Hook class
+    #
+    # : (untyped) -> bool
+    def hook_class?: (untyped) -> bool
+
     # Resolves dependencies from the container
     #
     # : (Container, Hash[Symbol, untyped]) -> void
@@ -357,7 +407,7 @@ module SenroUsecaser
     def step_should_stop?: (Step) -> bool
 
     # Calls a single UseCase in the pipeline
-    # Requires input_class to be defined for pipeline steps
+    # Requires input type(s) to be defined for pipeline steps
     #
     # : (singleton(Base), untyped) -> Result[untyped]
     def call_use_case: (singleton(Base), untyped) -> Result[untyped]

data/sig/generated/senro_usecaser/hook.rbs

@@ -0,0 +1,112 @@
+# Generated from lib/senro_usecaser/hook.rb with RBS::Inline
+
+module SenroUsecaser
+  # Base class for hooks with dependency injection support
+  #
+  # Hook classes provide a way to define before/after/around hooks
+  # with access to the DI container and automatic dependency resolution.
+  #
+  # @example Basic hook
+  #   class LoggingHook < SenroUsecaser::Hook
+  #     depends_on :logger, Logger
+  #
+  #     def before(input)
+  #       logger.info("Starting with #{input.class.name}")
+  #     end
+  #
+  #     def after(input, result)
+  #       logger.info("Finished: #{result.success? ? 'success' : 'failure'}")
+  #     end
+  #   end
+  #
+  # @example Hook with namespace
+  #   class Admin::AuditHook < SenroUsecaser::Hook
+  #     namespace :admin
+  #     depends_on :audit_logger, AuditLogger
+  #
+  #     def after(input, result)
+  #       audit_logger.log(input: input, result: result)
+  #     end
+  #   end
+  #
+  # @example Hook with around
+  #   class TransactionHook < SenroUsecaser::Hook
+  #     def around(input)
+  #       ActiveRecord::Base.transaction { yield }
+  #     end
+  #   end
+  class Hook
+    # Declares a dependency to be injected from the container
+    #
+    # : (Symbol, ?Class) -> void
+    def self.depends_on: (Symbol, ?Class) -> void
+
+    # Returns the list of declared dependencies
+    #
+    # : () -> Array[Symbol]
+    def self.dependencies: () -> Array[Symbol]
+
+    # Returns the dependency type mapping
+    #
+    # : () -> Hash[Symbol, Class]
+    def self.dependency_types: () -> Hash[Symbol, Class]
+
+    # Sets or returns the namespace for dependency resolution
+    #
+    # : (?(Symbol | String)) -> (Symbol | String)?
+    def self.namespace: (?Symbol | String) -> (Symbol | String)?
+
+    # Alias for namespace() without arguments
+    #
+    # : () -> (Symbol | String)?
+    def self.hook_namespace: () -> (Symbol | String)?
+
+    # @api private
+    def self.inherited: (untyped subclass) -> untyped
+
+    # Initializes the hook with dependencies resolved from the container
+    #
+    # : (container: Container, ?use_case_namespace: (Symbol | String)?) -> void
+    def initialize: (container: Container, ?use_case_namespace: (Symbol | String)?) -> void
+
+    # Called before the UseCase executes
+    # Override in subclass to add before logic
+    #
+    # : (untyped) -> void
+    def before: (untyped) -> void
+
+    # Called after the UseCase executes
+    # Override in subclass to add after logic
+    #
+    # : (untyped, Result[untyped]) -> void
+    def after: (untyped, Result[untyped]) -> void
+
+    # Wraps the UseCase execution
+    # Override in subclass to add around logic
+    #
+    # : (untyped) { () -> Result[untyped] } -> Result[untyped]
+    def around: (untyped) { () -> Result[untyped] } -> Result[untyped]
+
+    private
+
+    # Returns the effective namespace for dependency resolution
+    #
+    # : () -> (Symbol | String)?
+    def effective_namespace: () -> (Symbol | String)?
+
+    # Infers namespace from the class's module structure
+    #
+    # : () -> String?
+    def infer_namespace_from_class: () -> String?
+
+    # Resolves dependencies from the container
+    #
+    # : () -> void
+    def resolve_dependencies: () -> void
+
+    # Resolves a single dependency from the container
+    #
+    # : (Symbol) -> untyped
+    def resolve_from_container: (Symbol) -> untyped
+  end
+end

data/sig/generated/senro_usecaser/provider.rbs

@@ -62,7 +62,7 @@ module SenroUsecaser
     #     enabled_if { Rails.env.development? }
     #   end
     #
-    # : () { () -> bool } -> void
+    # : () { () -> boolish } -> void
     def self.enabled_if: () { () -> boolish } -> void
 
     # Returns whether this provider is enabled

data/sig/overrides.rbs

@@ -11,6 +11,6 @@ module SenroUsecaser
     # Class methods that rbs-inline doesn't generate correctly
     def self.organized_steps: () -> Array[Step]?
     def self.use_case_namespace: () -> (Symbol | String)?
-    def self.input_class: () -> Class?
+    def self.output_schema: () -> (Class | Hash[Symbol, Class])?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: senro_usecaser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Shogo Kawahara
@@ -22,6 +22,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile
@@ -37,6 +38,7 @@ files:
 - lib/senro_usecaser/configuration.rb
 - lib/senro_usecaser/container.rb
 - lib/senro_usecaser/error.rb
+- lib/senro_usecaser/hook.rb
 - lib/senro_usecaser/provider.rb
 - lib/senro_usecaser/result.rb
 - lib/senro_usecaser/version.rb
@@ -45,6 +47,7 @@ files:
 - sig/generated/senro_usecaser/configuration.rbs
 - sig/generated/senro_usecaser/container.rbs
 - sig/generated/senro_usecaser/error.rbs
+- sig/generated/senro_usecaser/hook.rbs
 - sig/generated/senro_usecaser/provider.rbs
 - sig/generated/senro_usecaser/result.rbs
 - sig/generated/senro_usecaser/version.rbs