simple_command_dispatcher 3.0.4 → 4.1.0

data/lib/simple_command_dispatcher/commands/command_callable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module SimpleCommandDispatcher
+  module Commands
+    module CommandCallable
+      attr_reader :result
+
+      module ClassMethods
+        # Accept everything, essentially: `call(*args, **kwargs)``
+        def call(...)
+          new(...).call
+        end
+      end
+
+      def self.prepended(base)
+        base.extend ClassMethods
+      end
+
+      def call
+        raise NotImplementedError unless defined?(super)
+
+        @called = true
+        @result = super
+
+        self
+      end
+
+      def success?
+        called? && !failure?
+      end
+      alias successful? success?
+
+      def failure?
+        called? && errors.any?
+      end
+
+      def errors
+        return super if defined?(super)
+
+        @errors ||= Errors.new
+      end
+
+      private
+
+      def called?
+        @called ||= false
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/commands/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module SimpleCommandDispatcher
+  module Commands
+    module CommandCallable
+      class NotImplementedError < ::StandardError; end
+
+      class Errors < Hash
+        def add(key, value, _opts = {})
+          self[key] ||= []
+          self[key] << value
+          self[key].uniq!
+        end
+
+        def add_multiple_errors(errors_hash)
+          errors_hash.each do |key, values|
+            CommandCallable::Utils.array_wrap(values).each { |value| add key, value }
+          end
+        end
+
+        def each
+          each_key do |field|
+            self[field].each { |message| yield field, message }
+          end
+        end
+
+        def full_messages
+          map { |attribute, message| full_message(attribute, message) }
+        end
+
+        private
+
+        def full_message(attribute, message)
+          return message if attribute == :base
+
+          attr_name = attribute.to_s.tr('.', '_').capitalize
+          "#{attr_name} #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/commands/utils.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Commands
+    module CommandCallable
+      module Utils
+        # Borrowed from active_support/core_ext/array/wrap
+        def self.array_wrap(object)
+          if object.nil?
+            []
+          elsif object.respond_to?(:to_ary)
+            object.to_ary || [object]
+          else
+            [object]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/configuration.rb

@@ -1,44 +1,46 @@
 # frozen_string_literal: true
 
-module SimpleCommand
-  module Dispatcher
-    # Gem configuration settings class. Use this class to configure this gem.
+# This is the configuration for SimpleCommandDispatcher.
+module SimpleCommandDispatcher
+  class << self
+    attr_reader :configuration
+
+    # Configures SimpleCommandDispatcher by yielding the configuration object to the block.
     #
-    # To configure this gem in your application, simply add the following code in your application and set the
-    # appropriate configuration settings.
+    # @yield [Configuration] yields the configuration object to the block
+    # @return [Configuration] returns the configuration object
     #
     # @example
     #
-    #    SimpleCommand::Dispatcher.configure do |config|
-    #       config.allow_custom_commands = true
-    #    end
-    #
-    class Configuration
-      # Gets/sets the *allow_custom_commands* configuration setting (defaults to false).
-      # If this setting is set to *false*, only command classes that prepend the *SimpleCommand* module
-      # will be considered acceptable to run, all other command classes will fail to run. If this
-      # setting is set to *true*, any command class will be considered acceptable to run, regardless of
-      # whether or not the class prepends the *SimpleCommand* module.
-      #
-      # For information about the simple_command gem, visit {https://rubygems.org/gems/simple_command}
-      #
-      # @return [Boolean] the value.
-      #
-      attr_accessor :allow_custom_commands
-
-      def initialize
-        # The default is to use any command that exposes a ::call class method.
-        reset
-      end
-
-      # Resets the configuration to use the default values.
-      #
-      # @return [nil] returns nil.
-      #
-      def reset
-        @allow_custom_commands = false
-        nil
-      end
+    # SimpleCommandDispatcher.configure do |config|
+    #  config.some_option = 'some value'
+    # end
+    def configure
+      self.configuration ||= Configuration.new
+
+      yield(configuration) if block_given?
+
+      configuration
+    end
+
+    private
+
+    attr_writer :configuration
+  end
+
+  # This class encapsulates the configuration properties for this gem and
+  # provides methods and attributes that allow for management of the same.
+  class Configuration
+    # TODO: Add attr_xxx here
+
+    # Initializes a new Configuration instance with default values
+    def initialize
+      reset
+    end
+
+    # Resets all configuration attributes to their default values
+    def reset
+      # TODO: Reset our attributes here e.g. @attr = nil
     end
   end
 end

data/lib/simple_command_dispatcher/errors/invalid_class_constant_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Errors
+    # This error is raised when a command class constant is not found or invalid.
+    class InvalidClassConstantError < StandardError
+      # Initializes a new InvalidClassConstantError
+      #
+      # @param constantized_class_string [String] the class string that failed to constantize
+      # @param error_message [String] the underlying error message
+      def initialize(constantized_class_string, error_message)
+        super("\"#{constantized_class_string}\" is not a valid class constant. Error message: \"#{error_message}\".")
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/errors/required_class_method_missing_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Errors
+    # This error is raised when a required class method is missing on the command class.
+    class RequiredClassMethodMissingError < StandardError
+      # Initializes a new RequiredClassMethodMissingError
+      #
+      # @param command_class_constant [Class] the command class that is missing the required method
+      def initialize(command_class_constant)
+        super("Class \"#{command_class_constant}\" does not respond_to? class method \"call\".")
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/errors.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'errors/invalid_class_constant_error'
+require_relative 'errors/required_class_method_missing_error'

data/lib/simple_command_dispatcher/helpers/camelize.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'trim_all'
+
+module SimpleCommandDispatcher
+  module Helpers
+    module Camelize
+      include TrimAll
+
+      # Transforms a RESTful route into a Ruby constant string for instantiation
+      #
+      # @param token [String] the route path to be camelized
+      # @return [String] the camelized constant name
+      #
+      # @example
+      #
+      #   camelize("/api/users/v1") # => "Api::Users::V1"
+      #   # Then: Api::Users::V1.new.call
+      #
+      def camelize(token)
+        raise ArgumentError, 'Token is not a String' unless token.instance_of? String
+
+        return if token.empty?
+
+        # For RESTful paths → Ruby constants, use Rails' proven methods
+        # They're fast, reliable, and handle edge cases that matter for constants
+        result = trim_all(token)
+          .gsub(%r{[/\-\.\s:]+}, '/')                    # Normalize separators to /
+          .split('/')                                    # Split into path segments
+          .reject(&:empty?)                              # Remove empty segments
+          .map { |segment| segment.underscore.camelize } # Rails camelization
+          .join('::')                                    # Join as Ruby namespace
+
+        result.empty? ? '' : result
+      end
+    end
+  end
+end
+
+# Usage example:
+# "/api/user_sessions/v1" → "Api::UserSessions::V1"
+#
+# Then in your dispatcher:
+# constant_name = camelize(request.path)
+# command_class = Object.const_get(constant_name)
+# command_class.new.call

data/lib/simple_command_dispatcher/helpers/trim_all.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Helpers
+    module TrimAll
+      # Removes all whitespace from the given string, including Unicode whitespace
+      #
+      # @param string [String] the string to remove whitespace from
+      # @return [String] the string with all whitespace removed
+      def trim_all(string)
+        # Using Unicode property \p{Space} to match all Unicode whitespace characters
+        string.gsub(/\p{Space}+/, '')
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/services/command_namespace_service.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/camelize'
+require_relative '../helpers/trim_all'
+
+module SimpleCommandDispatcher
+  module Services
+    # Returns a string of modules that can be subsequently prepended to a class, to create a fully qualified,
+    # constantized class.
+    #
+    # The command_namespace is provided during initialization and can be a Hash, Array, or String.
+    #
+    # @return [String] a string of modules that can be subsequently prepended to a class, to create a
+    #    constantized class.
+    #
+    # @raise [ArgumentError] if the command_namespace is not of type String, Hash or Array.
+    #
+    # @example
+    #
+    #   to_class_modules_string("Api") # => "Api::"
+    #   to_class_modules_string([:Api, :AppName, :V1]) # => "Api::AppName::V1::"
+    #   to_class_modules_string({ api: :Api, app_name: :AppName, api_version: :V1 }) # => "Api::AppName::V1::"
+    #   to_class_modules_string({ api: :api, app_name: :app_name, api_version: :v1 }, { titleize_module: true })
+    #      # => "Api::AppName::V1::"
+    #
+    class CommandNamespaceService
+      include Helpers::Camelize
+      include Helpers::TrimAll
+
+      def initialize(command_namespace:)
+        @command_namespace = command_namespace
+      end
+
+      # Handles command module transformations from String, Hash or Array into
+      # a fully qualified class modules string (e.g. "A::B::C::").
+      def to_class_modules_string
+        return '' if command_namespace.blank?
+
+        class_modules_string = join_class_modules_if(command_namespace:)
+        class_modules_string = trim_all(camelize(class_modules_string))
+        "#{class_modules_string}::"
+      end
+
+      private
+
+      attr_reader :command_namespace
+
+      def join_class_modules_if(command_namespace:)
+        case command_namespace
+        when String
+          command_namespace
+        when Array
+          command_namespace.join('::')
+        when Hash
+          command_namespace.values.join('::')
+        end
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/services/command_service.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../helpers/camelize'
+require_relative 'command_namespace_service'
+
+module SimpleCommandDispatcher
+  module Services
+    # Handles class and module transformations and instantiation.
+    class CommandService
+      include Helpers::Camelize
+
+      def initialize(command:, command_namespace: {})
+        @command = validate_command(command:)
+        @command_namespace = validate_command_namespace(command_namespace:)
+      end
+
+      # Returns a constantized class (as a Class constant), given the command and command_namespace
+      # that were provided during initialization.
+      #
+      # @return [Class] the class constant.
+      #
+      # @raise [Errors::InvalidClassConstantError] if the constantized class string cannot be constantized; that is,
+      #    if it is not a valid class constant.
+      #
+      # @example
+      #
+      #   to_class("Authenticate", "Api") # => Api::Authenticate
+      #   to_class(:Authenticate, [:Api, :AppName, :V1]) # => Api::AppName::V1::Authenticate
+      #   to_class(:Authenticate, { :api :Api, app_name: :AppName, api_version: :V2 })
+      #     # => Api::AppName::V2::Authenticate
+      #   to_class("authenticate", { :api :api, app_name: :app_name, api_version: :v1 },
+      #     { titleize_class: true, titleize_module: true }) # => Api::AppName::V1::Authenticate
+      #
+      def to_class
+        qualified_class_string = to_qualified_class_string(command, command_namespace)
+
+        begin
+          qualified_class_string.constantize
+        rescue StandardError => e
+          raise Errors::InvalidClassConstantError.new(qualified_class_string, e.message)
+        end
+      end
+
+      private
+
+      attr_accessor :command, :command_namespace
+
+      # Returns a fully-qualified constantized class (as a string), given the command and command_namespace.
+      # Both parameters are automatically camelized/titleized during processing.
+      #
+      # @param command [Symbol, String] the class name.
+      # @param command_namespace [Hash, Array, String] the modules command belongs to.
+      #
+      # @return [String] the fully qualified class, which includes module(s) and class name.
+      #
+      # @example
+      #
+      #   to_qualified_class_string("authenticate", "api") # => "Api::Authenticate"
+      #   to_qualified_class_string(:Authenticate, [:Api, :AppName, :V1]) # => "Api::AppName::V1::Authenticate"
+      #   to_qualified_class_string(:authenticate, { api: :api, app_name: :app_name, api_version: :v1 })
+      #      # => "Api::AppName::V1::Authenticate"
+      #
+      def to_qualified_class_string(command, command_namespace)
+        class_modules_string = CommandNamespaceService.new(command_namespace:).to_class_modules_string
+        class_string = to_class_string(command:)
+        "#{class_modules_string}#{class_string}"
+      end
+
+      # Returns the command as a string after transformations have been applied.
+      # The command is automatically camelized/titleized during processing.
+      #
+      # @param command [Symbol, String] the class name to be transformed.
+      #
+      # @return [String] the transformed class as a string.
+      #
+      # @example
+      #
+      #   to_class_string(command: "MyClass") # => "MyClass"
+      #   to_class_string(command: "my_class") # => "MyClass"
+      #   to_class_string(command: :MyClass) # => "MyClass"
+      #   to_class_string(command: :my_class) # => "MyClass"
+      #
+      def to_class_string(command:)
+        camelize(command)
+      end
+
+      # @!visibility public
+      #
+      # Validates command and returns command as a string after all blanks have been removed using
+      # command.gsub(/\s+/, "").
+      #
+      # @param [Symbol or String] command the class name to be validated. command cannot be empty?
+      #
+      # @return [String] the validated class as a string with blanks removed.
+      #
+      # @raise [ArgumentError] if the command is empty? or not of type String or Symbol.
+      #
+      # @example
+      #
+      #   validate_command(" My Class ") # => "MyClass"
+      #   validate_command(:MyClass) # => "MyClass"
+      #
+      def validate_command(command:)
+        unless command.is_a?(Symbol) || command.is_a?(String)
+          raise ArgumentError,
+            'command is not a String or Symbol. command must equal the class name of the ' \
+            'command to call in the form of a String or Symbol.'
+        end
+
+        command = command.to_s.strip
+
+        raise ArgumentError, 'command is empty?' if command.empty?
+
+        command
+      end
+
+      # @!visibility public
+      #
+      # Validates and returns command_namespace.
+      #
+      # @param [Hash, Array or String] command_namespace the module(s) to be validated.
+      #
+      # @return [Hash, Array or String] the validated module(s).
+      #
+      # @raise [ArgumentError] if the command_namespace is not of type String, Hash or Array.
+      #
+      # @example
+      #
+      #   validate_command_namespace(" Module ") # => " Module "
+      #   validate_command_namespace(:Module) # => :Module
+      #   validate_command_namespace("ModuleA::ModuleB") # => "ModuleA::ModuleB"
+      #
+      def validate_command_namespace(command_namespace:)
+        return {} if command_namespace.blank?
+
+        unless valid_command_namespace_type?(command_namespace:)
+          raise ArgumentError,
+            'Argument command_namespace is not a String, Hash or Array.'
+        end
+
+        command_namespace
+      end
+
+      def valid_command_namespace_type?(command_namespace:)
+        command_namespace.instance_of?(String) ||
+          command_namespace.instance_of?(Hash) ||
+          command_namespace.instance_of?(Array)
+      end
+    end
+  end
+end

data/lib/simple_command_dispatcher/version.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-module SimpleCommand
-  module Dispatcher
-    VERSION = '3.0.4'
-  end
+module SimpleCommandDispatcher
+  VERSION = '4.1.0'
 end