senro_usecaser 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91d516c2b304a836d4b476c177083ddff38bf8344ddbba14293aa60bee3e07f5
-  data.tar.gz: 0167aac25683c97feeb378123294073025c86d405307facb5e0392f5bf8eec35
+  metadata.gz: cbfc07ede41cc295ceb0a019774a480744b226e88edc46f72a6447d59375f4e4
+  data.tar.gz: b86aaade8ccc9f2479f18d0f3bd5204203718ce26740eb3a51b5cccf1ed06798
 SHA512:
-  metadata.gz: 9592f2b84a831c56b80010cd207588e171407f07a143f19bb25f6cb4bb103bfa23b449c98517c887b4a0d5ff571b5e666afa82877df887978881121c01943996
-  data.tar.gz: f4cdbec706095b338c537eec61179ec9a2d9e251bd570d5ddceef2d0b2503deede7be514501e395c47e191a6e1c5c97f49144c0eb0fc728b3741d98b47ecc0e3
+  metadata.gz: 2ce95671ffefc951140c3625db940f1b077fe8bf40138d790b25067ab010a087d9f96b6c2e31bab2819ea89f0b2e6e905c70288f9409e24782cd73a0bca832cd
+  data.tar.gz: aa3b27b6eff694929f8cfc33ca47e5d7fb450eeb4ac5da9fecba2023cc70393a2edfa1b033e89d0fe0f0e1abe5cda3817841e8b92e04294062c0cd4a02ef8879

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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

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.
@@ -1007,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

@@ -276,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 types as an array
+      #
+      #: () -> Array[Module]
+      def input_types
+        @input_types || []
       end
 
-      # Returns the input class
+      # Returns the input class (for backwards compatibility)
+      # If a Class is specified, returns it. Otherwise returns the first type.
       #
-      #: () -> Class?
-      attr_reader :input_class
+      #: () -> 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
       #
@@ -340,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
 
@@ -372,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
@@ -416,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]
@@ -423,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
@@ -692,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/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.2.0"
+  VERSION = "0.3.0"
 end

data/sig/generated/senro_usecaser/base.rbs

@@ -188,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 types as an array
+    #
+    # : () -> Array[Module]
+    def self.input_types: () -> Array[Module]
 
-    # Returns the input class
+    # Returns the input class (for backwards compatibility)
+    # If a Class is specified, returns it. Otherwise returns the first type.
     #
-    # : () -> Class?
-    attr_reader input_class: untyped
+    # : () -> Module?
+    def self.input_class: () -> Module?
 
     # Declares the expected output type for this UseCase
     #
@@ -267,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]
@@ -378,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/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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Shogo Kawahara