senro_usecaser 0.3.0 → 0.4.1

data/lib/senro_usecaser/depends_on.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Module that provides dependency injection support
+  #
+  # This module can be extended into any class to enable the full DI functionality
+  # similar to UseCase and Hook classes, including:
+  # - `depends_on` for declaring dependencies
+  # - `namespace` for scoped dependency resolution
+  # - Automatic `infer_namespace_from_module` support
+  # - Default `initialize` that sets up dependency injection (uses SenroUsecaser.container if not provided)
+  #
+  # @example Basic usage (no initialize needed)
+  #   class MyService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :logger, Logger
+  #     depends_on :repository
+  #
+  #     # No initialize needed! Default is provided automatically.
+  #
+  #     def perform
+  #       logger.info("Performing...")
+  #       repository.find(1)
+  #     end
+  #   end
+  #
+  #   service = MyService.new  # Uses SenroUsecaser.container
+  #   service.logger  # => Logger instance
+  #
+  # @example Custom initialize with super
+  #   class MyService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :logger
+  #     attr_reader :extra
+  #
+  #     def initialize(extra:, container: nil)
+  #       super(container: container)  # Handles dependency resolution
+  #       @extra = extra
+  #     end
+  #   end
+  #
+  # @example With explicit namespace
+  #   class Admin::UserService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     namespace :admin
+  #     depends_on :user_repository, UserRepository
+  #   end
+  #
+  # @example With infer_namespace_from_module (when configured)
+  #   # When SenroUsecaser.configuration.infer_namespace_from_module = true
+  #   class Admin::Orders::ProcessService
+  #     extend SenroUsecaser::DependsOn
+  #
+  #     depends_on :order_repository  # resolved from "admin::orders" namespace
+  #   end
+  module DependsOn
+    # Hook called when module is extended into a class
+    # Automatically includes InstanceMethods
+    #
+    def self.extended(base)
+      base.include(InstanceMethods)
+    end
+
+    # Declares a dependency to be injected from the container
+    #
+    # @param name [Symbol] The name of the dependency
+    # @param type [Class, nil] Optional expected type for the dependency
+    #
+    # @example Basic dependency
+    #   depends_on :logger
+    #
+    # @example Typed dependency
+    #   depends_on :repository, UserRepository
+    #
+    #: (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 # steep:ignore NoMethod
+        @_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
+    #
+    # @param name [Symbol, String, nil] The namespace to set
+    # @return [Symbol, String, nil] The current namespace when no argument given
+    #
+    # @example Setting namespace
+    #   namespace :admin
+    #
+    # @example Getting namespace
+    #   current_ns = namespace
+    #
+    #: (?(Symbol | String)) -> (Symbol | String)?
+    def namespace(name = nil)
+      if name
+        @declared_namespace = name
+      else
+        @declared_namespace
+      end
+    end
+
+    # Returns the declared namespace
+    #
+    #: () -> (Symbol | String)?
+    def declared_namespace
+      @declared_namespace
+    end
+
+    # Copies dependency configuration to a subclass
+    #
+    # @param subclass [Class] The subclass to copy dependencies to
+    #
+    # @example In inherited hook
+    #   def self.inherited(subclass)
+    #     super
+    #     copy_depends_on_to(subclass)
+    #   end
+    #
+    #: (Class) -> void
+    def copy_depends_on_to(subclass)
+      subclass.instance_variable_set(:@dependencies, dependencies.dup)
+      subclass.instance_variable_set(:@dependency_types, dependency_types.dup)
+      subclass.instance_variable_set(:@declared_namespace, @declared_namespace)
+    end
+
+    # Instance methods for dependency resolution
+    #
+    # These methods are automatically included when DependsOn is extended.
+    # They require @_container and @_dependencies instance variables to be set.
+    module InstanceMethods
+      # Default initialize for classes using DependsOn
+      #
+      # This provides a default initialize that sets up dependency injection.
+      # Classes can override this and call super to extend the behavior.
+      #
+      # @param container [Container, nil] The DI container to resolve dependencies from.
+      #   If nil, uses SenroUsecaser.container.
+      #
+      # @example Default usage (no arguments needed)
+      #   class MyService
+      #     extend SenroUsecaser::DependsOn
+      #     depends_on :logger
+      #   end
+      #   service = MyService.new  # Uses SenroUsecaser.container
+      #
+      # @example With explicit container
+      #   service = MyService.new(container: custom_container)
+      #
+      # @example Custom initialize with super
+      #   class MyService
+      #     extend SenroUsecaser::DependsOn
+      #     depends_on :logger
+      #     attr_reader :extra
+      #
+      #     def initialize(extra:, container: nil)
+      #       super(container: container)
+      #       @extra = extra
+      #     end
+      #   end
+      #
+      #: (?container: Container?) -> void
+      def initialize(container: nil)
+        @_container = container || SenroUsecaser.container
+        @_dependencies = {} #: Hash[Symbol, untyped]
+        resolve_dependencies
+      end
+
+      # Resolves all declared dependencies from the container
+      #
+      # Call this in your initialize method after setting @_container and @_dependencies.
+      #
+      # @example
+      #   def initialize(container:)
+      #     @_container = container
+      #     @_dependencies = {}
+      #     resolve_dependencies
+      #   end
+      #
+      #: () -> void
+      def resolve_dependencies
+        self.class.dependencies.each do |name| # steep:ignore NoMethod
+          @_dependencies[name] = resolve_from_container(name)
+        end
+      end
+
+      private
+
+      # Returns the effective namespace for dependency resolution
+      #
+      # Priority:
+      # 1. Explicitly declared namespace via `namespace :name`
+      # 2. Inferred namespace from module structure (if configured)
+      #
+      #: () -> (Symbol | String)?
+      def effective_namespace
+        declared = self.class.declared_namespace # steep:ignore NoMethod
+        return declared if declared
+        return nil unless SenroUsecaser.configuration.infer_namespace_from_module
+
+        infer_namespace_from_class
+      end
+
+      # Infers namespace from the class's module structure
+      #
+      # Converts CamelCase module names to snake_case and joins with "::"
+      # e.g., Admin::Orders::ProcessService -> "admin::orders"
+      #
+      #: () -> 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 a single dependency from the container
+      #
+      #: (Symbol) -> untyped
+      def resolve_from_container(name)
+        ns = effective_namespace
+        if ns
+          @_container.resolve_in(ns, name)
+        else
+          @_container.resolve(name)
+        end
+      end
+    end
+  end
+end

data/lib/senro_usecaser/hook.rb

@@ -38,57 +38,18 @@ module SenroUsecaser
   #     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
+    extend DependsOn
 
-      # 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
+    class << self
+      # Alias for backward compatibility
       #
       #: () -> (Symbol | String)?
-      def hook_namespace # rubocop:disable Style/TrivialAccessors
-        @hook_namespace
-      end
+      alias hook_namespace declared_namespace
 
       # @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)
+        copy_depends_on_to(subclass)
       end
     end
 
@@ -127,54 +88,39 @@ module SenroUsecaser
       yield
     end
 
+    # Called when the UseCase fails
+    # Override in subclass to add failure handling or rollback logic
+    #
+    # @example Basic logging
+    #   def on_failure(input, result)
+    #     logger.error("Failed: #{result.errors.first&.message}")
+    #   end
+    #
+    # @example Request retry
+    #   def on_failure(input, result, context)
+    #     if result.errors.first&.code == :network_error && context.attempt < 3
+    #       context.retry!(wait: 2.0)
+    #     end
+    #   end
+    #
+    #: (untyped, Result[untyped], ?RetryContext?) -> void
+    def on_failure(input, result, context = nil)
+      # Override in subclass
+    end
+
     private
 
     # Returns the effective namespace for dependency resolution
+    # Overrides DependsOn::InstanceMethods to add use_case_namespace fallback
     #
     #: () -> (Symbol | String)?
     def effective_namespace
-      return self.class.hook_namespace if self.class.hook_namespace
+      declared = self.class.declared_namespace
+      return declared if declared
       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/retry_configuration.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Configuration for automatic retry behavior
+  #
+  # This class defines when and how retries should occur based on
+  # error codes or exception classes, with configurable backoff strategies.
+  #
+  # @example Basic retry configuration
+  #   RetryConfiguration.new(
+  #     matchers: [:network_error, Net::OpenTimeout],
+  #     attempts: 3,
+  #     wait: 1.0
+  #   )
+  #
+  # @example With exponential backoff
+  #   RetryConfiguration.new(
+  #     matchers: [:rate_limited],
+  #     attempts: 5,
+  #     wait: 2.0,
+  #     backoff: :exponential,
+  #     max_wait: 60
+  #   )
+  class RetryConfiguration
+    # Returns the list of error matchers (Symbols for error codes, Classes for exceptions)
+    #: () -> Array[(Symbol | Class)]
+    attr_reader :matchers
+
+    # Returns the maximum number of attempts
+    #: () -> Integer
+    attr_reader :attempts
+
+    # Returns the base wait time in seconds
+    #: () -> (Float | Integer)
+    attr_reader :wait
+
+    # Returns the backoff strategy (:fixed, :linear, :exponential)
+    #: () -> Symbol
+    attr_reader :backoff
+
+    # Returns the maximum wait time in seconds
+    #: () -> (Float | Integer)
+    attr_reader :max_wait
+
+    # Returns the jitter factor (0.0 to 1.0)
+    #: () -> (Float | Integer)
+    attr_reader :jitter
+
+    # Initializes a new retry configuration
+    #
+    # @param matchers [Array<Symbol, Class>] Error codes or exception classes to match
+    # @param attempts [Integer] Maximum number of attempts (default: 3)
+    # @param wait [Numeric] Base wait time in seconds (default: 0)
+    # @param backoff [Symbol] Backoff strategy: :fixed, :linear, or :exponential (default: :fixed)
+    # @param max_wait [Numeric] Maximum wait time in seconds (default: 3600)
+    # @param jitter [Numeric] Jitter factor 0.0-1.0 to randomize wait times (default: 0)
+    #
+    # rubocop:disable Metrics/ParameterLists
+    #: (matchers: Array[(Symbol | Class)], ?attempts: Integer, ?wait: (Float | Integer),
+    #:  ?backoff: Symbol, ?max_wait: (Float | Integer)?, ?jitter: (Float | Integer)) -> void
+    def initialize(matchers:, attempts: 3, wait: 0, backoff: :fixed, max_wait: nil, jitter: 0)
+      # rubocop:enable Metrics/ParameterLists
+      @matchers = matchers
+      @attempts = attempts
+      @wait = wait
+      @backoff = backoff
+      @max_wait = max_wait || 3600
+      @jitter = jitter
+    end
+
+    # Checks if this configuration matches the given result
+    #
+    #: (Result[untyped]) -> bool
+    def matches?(result)
+      return false unless result.failure?
+
+      result.errors.any? { |error| matches_error?(error) }
+    end
+
+    # Calculates the wait time for the given attempt number
+    #
+    #: (Integer) -> Float
+    def calculate_wait(attempt)
+      base = calculate_base_wait(attempt)
+      base = [base, @max_wait].min
+      apply_jitter(base)
+    end
+
+    private
+
+    # Checks if an error matches any of the configured matchers
+    #
+    #: (Error) -> bool
+    def matches_error?(error)
+      @matchers.any? do |matcher|
+        case matcher
+        when Symbol
+          error.code == matcher
+        when Class
+          error.cause&.is_a?(matcher)
+        end
+      end
+    end
+
+    # Calculates the base wait time based on backoff strategy
+    #
+    #: (Integer) -> (Float | Integer)
+    def calculate_base_wait(attempt)
+      case @backoff
+      when :linear
+        @wait * attempt
+      when :exponential
+        @wait * (2**(attempt - 1))
+      else # :fixed or any other value
+        @wait
+      end
+    end
+
+    # Applies jitter to the wait time
+    #
+    #: ((Float | Integer)) -> Float
+    def apply_jitter(base)
+      return base.to_f if @jitter <= 0
+
+      jitter_amount = (rand * @jitter * base * 2) - (@jitter * base)
+      [base + jitter_amount, 0.0].max.to_f
+    end
+  end
+end

data/lib/senro_usecaser/retry_context.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Represents the context of a retry operation
+  #
+  # This class tracks the state of retry attempts including:
+  # - Current attempt number
+  # - Maximum attempts allowed
+  # - Elapsed time since first attempt
+  # - Whether a retry should occur
+  #
+  # @example Basic usage in on_failure hook
+  #   on_failure do |input, result, context|
+  #     if context.attempt < 3
+  #       context.retry!(wait: 1.0)
+  #     end
+  #   end
+  #
+  # @example With modified input
+  #   on_failure do |input, result, context|
+  #     if result.errors.first&.code == :rate_limited
+  #       context.retry!(input: input.with_reduced_batch_size, wait: 5.0)
+  #     end
+  #   end
+  class RetryContext
+    # Returns the current attempt number (1-indexed)
+    #: () -> Integer
+    attr_reader :attempt
+
+    # Returns the maximum number of attempts allowed
+    #: () -> Integer?
+    attr_reader :max_attempts
+
+    # Returns the time when the first attempt started
+    #: () -> Time
+    attr_reader :started_at
+
+    # Returns the error from the last failed attempt
+    #: () -> Error?
+    attr_reader :last_error
+
+    # Returns the input to use for the retry (nil means use original)
+    #: () -> untyped
+    attr_reader :retry_input
+
+    # Returns the wait time before retrying
+    #: () -> (Float | Integer)?
+    attr_reader :retry_wait
+
+    # Initializes a new retry context
+    #
+    #: (?max_attempts: Integer?) -> void
+    def initialize(max_attempts: nil)
+      @attempt = 1
+      @max_attempts = max_attempts
+      @started_at = Time.now
+      @last_error = nil
+      @should_retry = false
+      @retry_input = nil
+      @retry_wait = nil
+    end
+
+    # Returns true if this is a retry (attempt > 1)
+    #
+    #: () -> bool
+    def retried?
+      @attempt > 1
+    end
+
+    # Returns the elapsed time since the first attempt
+    #
+    #: () -> Float
+    def elapsed_time
+      Time.now - @started_at
+    end
+
+    # Returns true if max_attempts has been reached
+    #
+    #: () -> bool
+    def exhausted?
+      return false unless @max_attempts
+
+      @attempt >= @max_attempts
+    end
+
+    # Returns true if a retry has been requested
+    #
+    #: () -> bool
+    def should_retry?
+      @should_retry
+    end
+
+    # Requests a retry with optional modified input and wait time
+    #
+    # @example Retry with default settings
+    #   context.retry!
+    #
+    # @example Retry with wait time
+    #   context.retry!(wait: 2.0)
+    #
+    # @example Retry with modified input
+    #   context.retry!(input: modified_input, wait: 1.0)
+    #
+    #: (?input: untyped, ?wait: (Float | Integer)?) -> void
+    def retry!(input: nil, wait: nil)
+      @should_retry = true
+      @retry_input = input
+      @retry_wait = wait
+    end
+
+    # Increments the attempt counter and resets retry state
+    # Called internally between retry attempts
+    #
+    #: (?last_error: Error?) -> void
+    def increment!(last_error: nil)
+      @attempt += 1
+      @last_error = last_error
+      reset_retry_state!
+    end
+
+    # Resets the retry request state
+    # Called internally after processing retry decision
+    #
+    #: () -> void
+    def reset_retry_state!
+      @should_retry = false
+      @retry_input = nil
+      @retry_wait = nil
+    end
+  end
+end

data/lib/senro_usecaser/version.rb

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

data/lib/senro_usecaser.rb

@@ -8,6 +8,9 @@ require_relative "senro_usecaser/result"
 require_relative "senro_usecaser/container"
 require_relative "senro_usecaser/configuration"
 require_relative "senro_usecaser/provider"
+require_relative "senro_usecaser/retry_context"
+require_relative "senro_usecaser/retry_configuration"
+require_relative "senro_usecaser/depends_on"
 require_relative "senro_usecaser/hook"
 require_relative "senro_usecaser/base"