senro_usecaser 0.1.0

data/lib/senro_usecaser/provider.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Base class for dependency providers
+  #
+  # Providers allow organizing dependency registrations across multiple files.
+  # Each provider is responsible for registering a group of related dependencies.
+  #
+  # @example Basic provider
+  #   class UserProvider < SenroUsecaser::Provider
+  #     def register(container)
+  #       container.register(:user_repository, UserRepository.new)
+  #       container.register_singleton(:user_service) do |c|
+  #         UserService.new(repo: c.resolve(:user_repository))
+  #       end
+  #     end
+  #   end
+  #
+  # @example Provider with namespace
+  #   class AdminProvider < SenroUsecaser::Provider
+  #     namespace :admin
+  #
+  #     def register(container)
+  #       container.register(:user_repository, AdminUserRepository.new)
+  #     end
+  #   end
+  #
+  # @example Provider with dependencies
+  #   class PersistenceProvider < SenroUsecaser::Provider
+  #     depends_on CoreProvider
+  #
+  #     def register(container)
+  #       container.register(:database, Database.connect)
+  #     end
+  #   end
+  #
+  # @example Conditional provider
+  #   class DevelopmentProvider < SenroUsecaser::Provider
+  #     enabled_if { SenroUsecaser.env.development? }
+  #   end
+  #
+  class Provider
+    class << self
+      # Declares dependencies on other providers
+      #
+      # @example
+      #   class PersistenceProvider < SenroUsecaser::Provider
+      #     depends_on CoreProvider
+      #     depends_on ConfigProvider
+      #   end
+      #
+      #: (*singleton(Provider)) -> void
+      def depends_on(*provider_classes)
+        provider_classes.each do |klass|
+          provider_dependencies << klass unless provider_dependencies.include?(klass)
+        end
+      end
+
+      # Returns the list of provider dependencies
+      #
+      #: () -> Array[singleton(Provider)]
+      def provider_dependencies
+        @provider_dependencies ||= [] #: Array[singleton(Provider)]
+      end
+
+      # Sets a condition for enabling this provider
+      #
+      # @example
+      #   class DevelopmentProvider < SenroUsecaser::Provider
+      #     enabled_if { Rails.env.development? }
+      #   end
+      #
+      #: () { () -> bool } -> void
+      def enabled_if(&block)
+        @enabled_condition = block
+      end
+
+      # Returns whether this provider is enabled
+      #
+      #: () -> bool
+      def enabled?
+        return true unless @enabled_condition
+
+        @enabled_condition.call
+      end
+
+      # Sets the namespace for this provider's registrations
+      #
+      # @example
+      #   class AdminProvider < SenroUsecaser::Provider
+      #     namespace :admin
+      #   end
+      #
+      #: ((Symbol | String)) -> void
+      def namespace(name = nil)
+        if name
+          @provider_namespace = name
+        else
+          @provider_namespace
+        end
+      end
+
+      # @rbs!
+      #   def self.provider_namespace: () -> (Symbol | String)?
+      attr_reader :provider_namespace
+
+      # Registers this provider's dependencies to the given container
+      #
+      #: (Container) -> void
+      def call(container)
+        new.register_to(container)
+      end
+    end
+
+    # Registers dependencies to the container, wrapped in namespace if declared
+    #
+    #: (Container) -> void
+    def register_to(container)
+      before_register(container)
+
+      ns = effective_namespace
+      if ns
+        # Capture self to call provider's register method within namespace context
+        provider = self
+        container.namespace(ns) { provider.register(container) }
+      else
+        register(container)
+      end
+    end
+
+    # Returns the effective namespace for this provider
+    # Uses explicitly declared namespace, or infers from module structure if configured
+    #
+    #: () -> (Symbol | String)?
+    def effective_namespace
+      # Explicit namespace takes precedence
+      return self.class.provider_namespace if self.class.provider_namespace
+
+      # Infer from module structure if enabled
+      return nil unless SenroUsecaser.configuration.infer_namespace_from_module
+
+      infer_namespace_from_class
+    end
+
+    # Infers namespace from the class's module structure
+    #
+    # @example
+    #   Admin::UserProvider => "admin"
+    #   Admin::Reports::ReportProvider => "admin::reports"
+    #   CoreProvider => nil
+    #
+    #: () -> 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
+
+      # Remove the class name itself, keep only module parts
+      module_parts = parts[0...-1] || [] #: Array[String]
+      return nil if module_parts.empty?
+
+      # Convert to lowercase namespace format (Admin::Reports => "admin::reports")
+      module_parts.map { |part| part.gsub(/([a-z])([A-Z])/, '\1_\2').downcase }.join("::")
+    end
+
+    # Called before register. Override in subclasses.
+    #
+    # @example
+    #   def before_register(container)
+    #     # Setup work
+    #   end
+    #
+    #: (Container) -> void
+    def before_register(container); end
+
+    # Override this method to register dependencies
+    #
+    # @example
+    #   def register(container)
+    #     container.register(:logger, Logger.new)
+    #   end
+    #
+    #: (Container) -> void
+    def register(container)
+      raise NotImplementedError, "#{self.class.name}#register must be implemented"
+    end
+
+    # Called after all providers are registered. Override in subclasses.
+    #
+    # @example
+    #   def after_boot(container)
+    #     container.resolve(:database).verify_connection!
+    #   end
+    #
+    #: (Container) -> void
+    def after_boot(container); end
+
+    # Called on application shutdown. Override in subclasses.
+    #
+    # @example
+    #   def shutdown(container)
+    #     container.resolve(:database).disconnect
+    #   end
+    #
+    #: (Container) -> void
+    def shutdown(container); end
+  end
+end

data/lib/senro_usecaser/result.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  # Represents the result of a UseCase execution
+  #
+  # Result is a generic type that holds either a success value or an array of errors.
+  # Use {.success} and {.failure} class methods to create instances.
+  #
+  # @example Success case
+  #   result = SenroUsecaser::Result.success(user)
+  #   result.success? # => true
+  #   result.value    # => user
+  #
+  # @example Failure case
+  #   result = SenroUsecaser::Result.failure(
+  #     SenroUsecaser::Error.new(code: :not_found, message: "User not found")
+  #   )
+  #   result.failure? # => true
+  #   result.errors   # => [#<SenroUsecaser::Error ...>]
+  #
+  # @rbs generic T
+  class Result
+    # @rbs!
+    #   attr_reader value: T?
+    #   attr_reader errors: Array[Error]
+
+    # @rbs skip
+    attr_reader :value
+    # @rbs skip
+    attr_reader :errors
+
+    # Creates a success Result with the given value
+    #
+    #: [T] (T) -> Result[T]
+    def self.success(value)
+      new(value: value, errors: [])
+    end
+
+    # Creates a failure Result with the given errors
+    #
+    #: (*Error) -> Result[untyped]
+    def self.failure(*errors)
+      errors = errors.flatten
+      raise ArgumentError, "At least one error is required for failure" if errors.empty?
+
+      new(value: nil, errors: errors)
+    end
+
+    # Creates a failure Result from an exception
+    #
+    # @example
+    #   begin
+    #     # some code that raises
+    #   rescue => e
+    #     Result.from_exception(e)
+    #   end
+    #
+    #: (Exception, ?code: Symbol) -> Result[untyped]
+    def self.from_exception(exception, code: :exception)
+      error = Error.from_exception(exception, code: code)
+      failure(error)
+    end
+
+    # Executes a block and captures any exception as a failure Result
+    #
+    # @example
+    #   result = Result.capture { User.find(id) }
+    #   # If User.find raises, result is a failure with the exception
+    #   # If User.find succeeds, result is a success with the return value
+    #
+    # @example With specific exception classes
+    #   result = Result.capture(ActiveRecord::RecordNotFound, code: :not_found) do
+    #     User.find(id)
+    #   end
+    #
+    #: [T] (*Class, ?code: Symbol) { () -> T } -> Result[T]
+    def self.capture(*exception_classes, code: :exception, &block)
+      raise ArgumentError, "Block is required" unless block
+
+      exception_classes = [StandardError] if exception_classes.empty?
+      value = block.call
+      success(value)
+    rescue *exception_classes => e
+      from_exception(e, code: code)
+    end
+
+    #: (?value: T?, ?errors: Array[Error]) -> void
+    def initialize(value: nil, errors: [])
+      @value = value
+      @errors = errors.freeze
+      freeze
+    end
+
+    # Returns true if the result is a success
+    #
+    #: () -> bool
+    def success?
+      errors.empty?
+    end
+
+    # Returns true if the result is a failure
+    #
+    #: () -> bool
+    def failure?
+      !success?
+    end
+
+    # Returns the value if success, otherwise raises an error
+    #
+    #: () -> T
+    def value! # steep:ignore MethodBodyTypeMismatch
+      raise "Cannot unwrap value from a failure result" if failure?
+
+      @value
+    end
+
+    # Returns the value if success, otherwise returns the given default
+    #
+    #: [U] (U) -> (T | U)
+    def value_or(default) # steep:ignore MethodBodyTypeMismatch
+      if success?
+        @value
+      else
+        default
+      end
+    end
+
+    # Applies a block to the value if success, returns failure with same errors if failure
+    #
+    #: [U] () { (T) -> U } -> Result[U]
+    def map(&block)
+      return Result.new(value: nil, errors: errors) if failure?
+
+      # @type var v: untyped
+      v = @value
+      Result.success(block.call(v))
+    end
+
+    # Applies a block to the value if success, returns failure with same errors if failure
+    # The block should return a Result
+    #
+    #: [U] () { (T) -> Result[U] } -> Result[U]
+    def and_then(&block)
+      return Result.new(value: nil, errors: errors) if failure?
+
+      # @type var v: untyped
+      v = @value
+      block.call(v)
+    end
+
+    # Applies a block to the errors if failure, returns self if success
+    #
+    #: () { (Array[Error]) -> Result[T] } -> Result[T]
+    def or_else(&block)
+      return self if success?
+
+      block.call(errors)
+    end
+
+    #: (Result[untyped]) -> bool
+    def ==(other)
+      return false unless other.is_a?(Result)
+
+      # @type var v: untyped
+      v = @value
+      v == other.value && errors == other.errors
+    end
+
+    #: () -> String
+    def inspect
+      if success?
+        # @type var v: untyped
+        v = @value
+        "#<#{self.class.name} success value=#{v.inspect}>"
+      else
+        "#<#{self.class.name} failure errors=#{errors.inspect}>"
+      end
+    end
+  end
+end

data/lib/senro_usecaser/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module SenroUsecaser
+  #: String
+  VERSION = "0.1.0"
+end

data/lib/senro_usecaser.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "senro_usecaser/version"
+require_relative "senro_usecaser/error"
+require_relative "senro_usecaser/result"
+require_relative "senro_usecaser/container"
+require_relative "senro_usecaser/configuration"
+require_relative "senro_usecaser/provider"
+require_relative "senro_usecaser/base"
+
+# SenroUsecaser is a type-safe UseCase pattern implementation library for Ruby.
+#
+# It provides:
+# - Type-safe input/output with RBS Inline
+# - DI container with namespaces
+# - Flexible composition with organize/include/extend patterns
+#
+# @example Basic UseCase
+#   class CreateUserUseCase < SenroUsecaser::Base
+#     def call(name:, email:)
+#       user = User.create(name: name, email: email)
+#       success(user)
+#     end
+#   end
+#
+#   result = CreateUserUseCase.call(name: "Taro", email: "taro@example.com")
+#   if result.success?
+#     puts result.value.name
+#   end
+module SenroUsecaser
+  class << self
+    # Returns the global container instance
+    #
+    # @example
+    #   SenroUsecaser.container.register(:logger, Logger.new)
+    #
+    #: () -> Container
+    def container
+      @container ||= Container.new
+    end
+
+    # Sets the global container instance
+    #
+    # @example
+    #   SenroUsecaser.container = MyCustomContainer.new
+    #
+    #: (Container) -> Container
+    attr_writer :container
+
+    # Resets the global container (useful for testing)
+    #
+    #: () -> void
+    def reset_container!
+      @container = nil
+    end
+
+    # Registers a provider to the global container
+    #
+    # @example
+    #   SenroUsecaser.register_provider(UserProvider)
+    #
+    #: (singleton(Provider)) -> void
+    def register_provider(provider_class)
+      provider_class.call(container)
+    end
+
+    # Registers multiple providers to the global container
+    #
+    # @example
+    #   SenroUsecaser.register_providers(UserProvider, OrderProvider, PaymentProvider)
+    #
+    #: (*singleton(Provider)) -> void
+    def register_providers(*provider_classes)
+      provider_classes.each { |klass| register_provider(klass) }
+    end
+
+    # Returns the configuration instance
+    #
+    #: () -> Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures SenroUsecaser
+    #
+    # @example
+    #   SenroUsecaser.configure do |config|
+    #     config.providers = [CoreProvider, UserProvider]
+    #     config.infer_namespace_from_module = true
+    #   end
+    #
+    #: () { (Configuration) -> void } -> void
+    def configure
+      yield configuration
+    end
+
+    # Boots all configured providers in dependency order
+    #
+    # @example
+    #   SenroUsecaser.configure do |config|
+    #     config.providers = [CoreProvider, UserProvider]
+    #   end
+    #   SenroUsecaser.boot!
+    #
+    #: () -> void
+    def boot!
+      @booter = ProviderBooter.new(configuration.providers, container)
+      @booter.boot!
+    end
+
+    # Shuts down all booted providers
+    #
+    #: () -> void
+    def shutdown!
+      @booter&.shutdown!
+    end
+
+    # Returns the current environment
+    #
+    # @example
+    #   SenroUsecaser.env.development?
+    #   SenroUsecaser.env.production?
+    #
+    #: () -> Environment
+    def env
+      @env ||= Environment.new(detect_environment)
+    end
+
+    # Sets the environment
+    #
+    #: (String) -> void
+    def env=(name)
+      @env = Environment.new(name)
+    end
+
+    # Resets all state (useful for testing)
+    #
+    #: () -> void
+    def reset!
+      @container = nil
+      @configuration = nil
+      @booter = nil
+      @env = nil
+    end
+
+    private
+
+    #: () -> String
+    def detect_environment
+      ENV["SENRO_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+    end
+  end
+end