simple_command_dispatcher 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78aeec50e25d248707c465097b003bf35eb4f6783c7405f68ea08264a1e655a3
-  data.tar.gz: 3d1333a439993ac0ad274c87d4244aadada69bcc7ddb5b064f34847b43396e46
+  metadata.gz: f29164d7bff98aa5d0b2aed2e12adf6f4408d06bfa789a142b0cf234f656a95a
+  data.tar.gz: ce2ba1f720a44a1a9ced023a7b2769d2a2702d971a6c0a2643aa5926a2585df4
 SHA512:
-  metadata.gz: c8c0b2631ad96c502f878df531e41f04a11ef92d11f059303fc4be3ad18afcd7f927c50cc9978f4c63e14f3026e03b7fa78529025a18d99f4bf31e4919152a3f
-  data.tar.gz: fe7cb001f4315809acd6699f40e199b864e9e0c88da78ac84ba806f989309367a54e1af71ce7fa490c5cca946a391498bd1ef56e3c2f1a2af0374efa45dbf853
+  metadata.gz: 1a929a3e9025cfa05bab78e9ec0a33fe15d1b2ca0f1e5696bb3cc9a455cf01214f0b0a6cec737e026bc39ad95d356451fc2e25abaeadd38f72d3817d8431335f
+  data.tar.gz: 7f99ae544a0c2d31abfe8126a43d44766acb3eba9cd14298cc4f84fbe46ff3d5fcfda1a4734c4e2cac47b978bf56c8f6c288fbb031f5d5f61d6f4d3f31e0fad8

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # CHANGELOG
 
+## Version 4.2.0 - 2025-10-07
+
+- **New Feature: Configurable Logger with Debug Mode**:
+
+  - Added configurable logger with automatic Rails.logger detection
+  - Introduced debug mode for command execution debugging via `options: { debug: true }`
+  - Logger can be configured via `SimpleCommandDispatcher.configuration.logger`
+  - Added `OptionsService` for managing command execution options
+  - Enhanced `SimpleCommandDispatcher.call` with `options:` parameter to support debug logging
+  - When debug mode is enabled, detailed debug logging shows command execution flow
+
+- **Test Coverage Improvements**:
+
+  - Achieved 100% test coverage across all modules (243 examples, 0 failures)
+  - Added comprehensive tests for `CommandCallable::Errors` class (15 new tests)
+  - Added comprehensive tests for `CommandCallable::Utils.array_wrap` method (8 new tests)
+  - Added tests for Rails logger auto-detection in configuration
+  - Added tests for debug mode functionality in command execution
+  - Enhanced test coverage for `OptionsService` and logger integration
+
+- **Documentation Enhancements**:
+
+  - Updated API documentation for `SimpleCommandDispatcher.call` to include `options` parameter
+  - Added comprehensive documentation for `CommandCallable` module with usage examples
+  - Documented all public methods in `Errors` class with examples
+  - Added documentation for `OptionsService` class and debug mode
+  - Enhanced `Configuration` documentation to include logger attribute
+  - Fixed all YARD documentation to accurately reflect current implementation
+  - Added best practice guidance for private `initialize` in CommandCallable commands
+
+- **Dependency Updates**:
+
+  - Added `irb` and `reline` gems to development dependencies
+  - Addresses Ruby 3.5 deprecation warnings for extracted standard library gems
+  - Rails 8 compatibility confirmed (supports ActiveSupport 8.x)
+
 ## Version 4.1.0 - 2025-07-14
 
 - **New Feature: CommandCallable Module**:

data/Gemfile

@@ -10,7 +10,9 @@ gem 'colorize', '>= 0.8.1', '< 2.0'
 gem 'rake', '>= 13.0', '< 14.0'
 
 group :development do
+  gem 'irb', '>= 1.0'
   gem 'pry-byebug', '>= 3.9', '< 4.0'
+  gem 'reline', '>= 0.3'
   gem 'rubocop', '>= 1.62', '< 2.0'
   gem 'rubocop-performance', '>= 1.20', '< 2.0'
   gem 'rubocop-rake', '>= 0.6', '< 1.0'

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    simple_command_dispatcher (4.1.0)
+    simple_command_dispatcher (4.2.0)
       activesupport (>= 7.0.8, < 9.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.2.1)
+    activesupport (8.0.3)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -19,41 +19,61 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.4.1)
-    bigdecimal (3.2.2)
+    bigdecimal (3.3.0)
     byebug (12.0.0)
     coderay (1.1.3)
     colorize (1.1.0)
     concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
+    connection_pool (2.5.4)
+    date (3.4.1)
     diff-lcs (1.6.2)
     docile (1.4.1)
     drb (2.2.3)
+    erb (5.0.3)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    json (2.12.2)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.15.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
     minitest (5.25.5)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.5.1)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-byebug (3.11.0)
       byebug (~> 12.0)
       pry (>= 0.13, < 0.16)
+    psych (5.2.6)
+      date
+      stringio
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
-    regexp_parser (2.10.0)
+    rdoc (6.15.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.2)
+      io-console (~> 0.5)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -66,8 +86,8 @@ GEM
     rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.78.0)
+    rspec-support (3.13.6)
+    rubocop (1.81.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -75,20 +95,20 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.45.1, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.45.1)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-performance (1.25.0)
+    rubocop-performance (1.26.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.6.0)
+    rubocop-rspec (3.7.0)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
@@ -97,13 +117,16 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    stringio (3.1.7)
+    tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.4)
 
 PLATFORMS
   arm64-darwin-22
@@ -118,8 +141,10 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.5, >= 2.5.3)
   colorize (>= 0.8.1, < 2.0)
+  irb (>= 1.0)
   pry-byebug (>= 3.9, < 4.0)
   rake (>= 13.0, < 14.0)
+  reline (>= 0.3)
   rspec (>= 3.10, < 4.0)
   rubocop (>= 1.62, < 2.0)
   rubocop-performance (>= 1.20, < 2.0)

data/README.md

@@ -1,6 +1,6 @@
-[![Ruby](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml/badge.svg?refresh=7)](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml)
-[![GitHub version](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher.svg?refresh=7)](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
-[![Gem Version](https://badge.fury.io/rb/simple_command_dispatcher.svg?refresh=7)](https://badge.fury.io/rb/simple_command_dispatcher)
+[![Ruby](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml/badge.svg?refresh=8)](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml)
+[![GitHub version](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher.svg?refresh=8)](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
+[![Gem Version](https://badge.fury.io/rb/simple_command_dispatcher.svg?refresh=8)](https://badge.fury.io/rb/simple_command_dispatcher)
 [![](https://ruby-gem-downloads-badge.herokuapp.com/simple_command_dispatcher?type=total)](http://www.rubydoc.info/gems/simple_command_dispatcher/)
 [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/simple_command_dispatcher/)
 [![Report Issues](https://img.shields.io/badge/report-issues-red.svg)](https://github.com/gangelo/simple_command_dispatcher/issues)
@@ -44,20 +44,96 @@ Or install it yourself as:
 
 - Ruby >= 3.3.0
 - Rails (optional, but optimized for Rails applications)
+- Rails 8 compatible (tested with ActiveSupport 8.x)
+
+## Quick Start
+
+Here's a complete minimal example showing how to use the gem in a Rails controller:
+
+```ruby
+# 1. Configure the gem (optional - uses Rails.logger by default)
+# config/initializers/simple_command_dispatcher.rb
+SimpleCommandDispatcher.configure do |config|
+  config.logger = Rails.logger
+end
+
+# 2. Create a command
+# app/commands/api/v1/authenticate_user.rb
+module Api
+  module V1
+    class AuthenticateUser
+      prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+      def call
+        user = User.find_by(email: email)
+        return nil unless user&.authenticate(password)
+
+        user
+      end
+
+      private
+
+      def initialize(params = {})
+        @email = params[:email]
+        @password = params[:password]
+      end
+
+      attr_reader :email, :password
+    end
+  end
+end
+
+# 3. Call the command from your controller
+# app/controllers/api/v1/sessions_controller.rb
+class Api::V1::SessionsController < ApplicationController
+  def create
+    command = SimpleCommandDispatcher.call(
+      command: request.path,           # "/api/v1/authenticate_user"
+      request_params: params
+    )
+
+    if command.success?
+      render json: { user: command.result }, status: :ok
+    else
+      render json: { errors: command.errors }, status: :unauthorized
+    end
+  end
+end
+```
 
 ## Basic Usage
 
 ### Simple Command Dispatch
 
 ```ruby
-# Basic command call
+# Basic command calls - all equivalent
+
+command = SimpleCommandDispatcher.call(
+  command: '/api/v1/authenticate_user',
+  # No `command_namespace:` param
+  request_params: { email: 'user@example.com', password: 'secret' }
+)
+
+command = SimpleCommandDispatcher.call(
+  command: :authenticate_user,
+  command_namespace: '/api/v1',
+  request_params: { email: 'user@example.com', password: 'secret' }
+)
+
 command = SimpleCommandDispatcher.call(
   command: 'AuthenticateUser',
-  command_namespace: 'Api::V1',
+  command_namespace: %w[api v1],
   request_params: { email: 'user@example.com', password: 'secret' }
 )
 
-# This executes: Api::V1::AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+# With debug logging enabled
+command = SimpleCommandDispatcher.call(
+  command: '/api/v1/authenticate_user',
+  request_params: { email: 'user@example.com', password: 'secret' },
+  options: { debug: true }  # Enables detailed debug logging
+)
+
+# All the above will execute: Api::V1::AuthenticateUser.call(email: 'user@example.com', password: 'secret')
 ```
 
 ## Command Standardization with CommandCallable
@@ -73,7 +149,7 @@ Here's how it works with a real controller example:
 ```ruby
 # app/controllers/api/mechs_controller.rb
 class Api::MechsController < ApplicationController
-  before_action :route_request, except: [:index]
+  before_action :route_request, except: [:destroy, :index]
 
   def index
     render json: { mechs: Mech.all }
@@ -88,7 +164,8 @@ class Api::MechsController < ApplicationController
   def route_request
     command = SimpleCommandDispatcher.call(
       command: request.path,        # "/api/v1/mechs/search"
-      command_namespace: nil,       # nil since the command namespace can be gleaned directly from `command: request.path`
+      # No need to use the `command_namespace` param, since the command namespace
+      # can be gleaned directly from `command: request.path`.
       request_params: params        # Full Rails params hash
     )
 
@@ -101,17 +178,29 @@ class Api::MechsController < ApplicationController
 end
 ```
 
-**The Convention:** Request path `/api/v1/mechs/search` automatically maps to command class `Api::V1::Mechs::Search`
+**The Convention:** Request path `/api/v1/mechs/search` automatically maps to command class `Api::V1::Mechs::Search`.
 
-**Alternative approach** if you need more control over command name and namespace:
+**Alternative approach** for handling nested resource routes with dynamic actions:
 
 ```ruby
-# Split the path manually
+# Handle routes like: /api/v1/mechs/123/variants/456/update
+# Extract resource action and build namespace from nested resources
+path_parts = request.path.split("/")
+action = path_parts.last                    # "update"
+resource_path = path_parts[0...-1]          # ["/api", "v1", "mechs", "123", "variants", "456"]
+
+# Build namespace from resource path, filtering out IDs
+namespace_parts = resource_path.select { |part| !part.match?(/^\d+$/) }
+
 command = SimpleCommandDispatcher.call(
-  command: request.path.split("/").last,           # "search"
-  command_namespace: request.path.split("/")[0..2], # "/api/v1/mechs"
-  request_params: params
+  command: action,                          # "update"
+  command_namespace: namespace_parts,       # ["/api", "v1", "mechs", "variants"]
+  request_params: params.merge(
+    mech_id: path_parts[4],                 # "123"
+    variant_id: path_parts[6]               # "456"
+  )
 )
+# Calls: Api::V1::Mechs::Variants::Update.call(mech_id: "123", variant_id: "456", ...)
 ```
 
 ### Versioned Command Examples
@@ -121,10 +210,6 @@ command = SimpleCommandDispatcher.call(
 class Api::V1::Mechs::Search
   prepend SimpleCommandDispatcher::Commands::CommandCallable
 
-  def initialize(params = {})
-    @name = params[:name]
-  end
-
   def call
     # V1 search logic - simple name search
     name.present? ? Mech.where("mech_name ILIKE ?", "%#{name}%") : Mech.none
@@ -132,6 +217,10 @@ class Api::V1::Mechs::Search
 
   private
 
+  def initialize(params = {})
+    @name = params[:name]
+  end
+
   attr_reader :name
 end
 
@@ -139,14 +228,6 @@ end
 class Api::V2::Mechs::Search
   prepend SimpleCommandDispatcher::Commands::CommandCallable
 
-  def initialize(params = {})
-    @cost = params[:cost]
-    @introduction_year = params[:introduction_year]
-    @mech_name = params[:mech_name]
-    @tonnage = params[:tonnage]
-    @variant = params[:variant]
-  end
-
   def call
     # V2 search logic - comprehensive search using scopes
     Mech.by_cost(cost)
@@ -158,6 +239,14 @@ class Api::V2::Mechs::Search
 
   private
 
+  def initialize(params = {})
+    @cost = params[:cost]
+    @introduction_year = params[:introduction_year]
+    @mech_name = params[:mech_name]
+    @tonnage = params[:tonnage]
+    @variant = params[:variant]
+  end
+
   attr_reader :cost, :introduction_year, :mech_name, :tonnage, :variant
 end
 
@@ -200,6 +289,39 @@ When you prepend `CommandCallable` to your command class, you automatically get:
 4. **Error Handling**: Built-in `errors` object for consistent error management
 5. **Call Tracking**: Internal tracking to ensure methods work correctly
 
+**Important:** The `.call` class method returns the command instance itself (not the raw result). Access the actual return value via `.result`:
+
+```ruby
+command = AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+command.success?  # => true/false
+command.result    # => the actual User object (or whatever your call method returned)
+command.errors    # => errors collection if any
+```
+
+**Best Practice:** Make `initialize` private when using `CommandCallable`. This enforces the use of the `.call` class method and ensures proper success/failure tracking. Making `initialize` private prevents direct instantiation that would bypass CommandCallable's functionality:
+
+```ruby
+class YourCommand
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+  def call
+    # Your logic here
+  end
+
+  private  # <- initialize should be private
+
+  def initialize(params = {})
+    @params = params
+  end
+end
+
+# This works (correct pattern):
+YourCommand.call(foo: 'bar')
+
+# This raises NoMethodError (prevents bypassing CommandCallable):
+YourCommand.new(foo: 'bar')
+```
+
 ### Convention Over Configuration: Route-to-Command Mapping
 
 The gem automatically transforms route paths into Ruby class constants using intelligent camelization, allowing flexible input formats:
@@ -274,12 +396,6 @@ request_params: 'single_value'
 class Api::V1::Payments::Process
   prepend SimpleCommandDispatcher::Commands::CommandCallable
 
-  def initialize(params = {})
-    @amount = params[:amount]
-    @card_token = params[:card_token]
-    @user_id = params[:user_id]
-  end
-
   def call
     validate_payment_data
     return nil if errors.any?
@@ -292,6 +408,12 @@ class Api::V1::Payments::Process
 
   private
 
+  def initialize(params = {})
+    @amount = params[:amount]
+    @card_token = params[:card_token]
+    @user_id = params[:user_id]
+  end
+
   attr_reader :amount, :card_token, :user_id
 
   def validate_payment_data
@@ -345,7 +467,97 @@ The gem can be configured in an initializer:
 ```ruby
 # config/initializers/simple_command_dispatcher.rb
 SimpleCommandDispatcher.configure do |config|
-  # Configuration options will be added in future versions
+  # Configure the logger (defaults to Rails.logger in Rails apps, or Logger.new($stdout) otherwise)
+  config.logger = Rails.logger
+
+  # Or use a custom logger
+  # config.logger = Logger.new('log/commands.log')
+end
+```
+
+### Using Configuration in Commands
+
+You can access the configured logger within your commands to add custom logging:
+
+```ruby
+class Api::V1::Payments::Process
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+  def call
+    logger.info("Processing payment for user #{user_id}")
+
+    validate_payment_data
+    return nil if errors.any?
+
+    result = charge_card
+    logger.info("Payment successful: #{result.inspect}")
+    result
+  rescue StandardError => e
+    logger.error("Payment failed: #{e.message}")
+    errors.add(:payment, e.message)
+    nil
+  end
+
+  private
+
+  def initialize(params = {})
+    @amount = params[:amount]
+    @card_token = params[:card_token]
+    @user_id = params[:user_id]
+  end
+
+  attr_reader :amount, :card_token, :user_id
+
+  def logger
+    SimpleCommandDispatcher.configuration.logger
+  end
+
+  def validate_payment_data
+    errors.add(:amount, 'must be positive') if amount.to_i <= 0
+    errors.add(:card_token, 'is required') if card_token.blank?
+    errors.add(:user_id, 'is required') if user_id.blank?
+  end
+
+  def charge_card
+    PaymentProcessor.charge(
+      amount: amount,
+      card_token: card_token,
+      user_id: user_id
+    )
+  end
+end
+```
+
+### Debug Logging
+
+The gem includes built-in debug logging that can be enabled using the `debug` option. This is useful for debugging command execution flow:
+
+```ruby
+# Enable debug logging for a single command
+command = SimpleCommandDispatcher.call(
+  command: :authenticate_user,
+  command_namespace: '/api/v1',
+  request_params: { email: 'user@example.com', password: 'secret' },
+  options: { debug: true }
+)
+
+# Debug logging outputs:
+# - Begin dispatching command (with command and namespace details)
+# - Command to execute (the fully qualified class name)
+# - Constantized command (the actual class constant)
+# - End dispatching command
+```
+
+**Important:** Debug logging mode **does not** skip execution—it still runs your command and returns real results, but with detailed debug output to help you understand what's happening internally.
+
+**Configure logging level:**
+
+```ruby
+# In your Rails initializer or application setup
+SimpleCommandDispatcher.configure do |config|
+  logger = Logger.new($stdout)
+  logger.level = Logger::DEBUG  # Set appropriate level
+  config.logger = logger
 end
 ```
 

data/lib/simple_command_dispatcher/commands/command_callable.rb

@@ -4,11 +4,45 @@ require_relative 'errors'
 
 module SimpleCommandDispatcher
   module Commands
+    # CommandCallable provides a standardized interface for command objects with built-in
+    # success/failure tracking and error handling.
+    #
+    # When prepended to a command class, it:
+    # - Adds a class-level `.call` method that instantiates and executes the command
+    # - Tracks command execution with `success?` and `failure?` methods
+    # - Provides error collection via the `errors` object
+    # - Stores the command's return value in `result`
+    #
+    # @example Basic usage
+    #   class AuthenticateUser
+    #     prepend SimpleCommandDispatcher::Commands::CommandCallable
+    #
+    #     def initialize(email:, password:)
+    #       @email = email
+    #       @password = password
+    #     end
+    #
+    #     def call
+    #       return nil unless user = User.find_by(email: @email)
+    #       return nil unless user.authenticate(@password)
+    #
+    #       user
+    #     end
+    #   end
+    #
+    #   command = AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+    #   command.success? # => true if user found and authenticated
+    #   command.result   # => User object or nil
     module CommandCallable
+      # @return [Object] the return value from the command's call method
       attr_reader :result
 
       module ClassMethods
-        # Accept everything, essentially: `call(*args, **kwargs)``
+        # Creates a new instance of the command and calls it, passing all arguments through.
+        #
+        # @param args [Array] positional arguments passed to initialize
+        # @param kwargs [Hash] keyword arguments passed to initialize
+        # @return [Object] the command instance (not the result - use .result to get the return value)
         def call(...)
           new(...).call
         end
@@ -18,6 +52,11 @@ module SimpleCommandDispatcher
         base.extend ClassMethods
       end
 
+      # Executes the command by calling super (your command's implementation).
+      # Tracks execution state and stores the result.
+      #
+      # @return [self] the command instance for method chaining
+      # @raise [NotImplementedError] if the including class doesn't define a call method
       def call
         raise NotImplementedError unless defined?(super)
 
@@ -27,15 +66,25 @@ module SimpleCommandDispatcher
         self
       end
 
+      # Returns true if the command was called successfully (no errors).
+      #
+      # @return [Boolean] true if called and no errors present
       def success?
         called? && !failure?
       end
       alias successful? success?
 
+      # Returns true if the command was called but has errors.
+      #
+      # @return [Boolean] true if called and errors are present
       def failure?
         called? && errors.any?
       end
 
+      # Returns the errors collection for this command.
+      # If the command class defines its own errors method, that will be used instead.
+      #
+      # @return [Errors] the errors collection
       def errors
         return super if defined?(super)
 
@@ -44,6 +93,9 @@ module SimpleCommandDispatcher
 
       private
 
+      # Returns true if the command's call method has been invoked.
+      #
+      # @return [Boolean] true if call has been invoked
       def called?
         @called ||= false
       end

data/lib/simple_command_dispatcher/commands/errors.rb

@@ -5,27 +5,66 @@ require_relative 'utils'
 module SimpleCommandDispatcher
   module Commands
     module CommandCallable
+      # Raised when a command's call method is not implemented
       class NotImplementedError < ::StandardError; end
 
+      # Error collection for CommandCallable commands.
+      # Stores validation errors as a hash where keys are field names and values are arrays of error messages.
       class Errors < Hash
+        # Adds an error message to the specified field.
+        # Automatically prevents duplicate messages for the same field.
+        #
+        # @param key [Symbol, String] the field name
+        # @param value [String] the error message
+        # @param _opts [Hash] reserved for future use
+        # @return [Array] the updated array of error messages for this field
+        #
+        # @example
+        #   errors.add(:email, 'is required')
+        #   errors.add(:email, 'is invalid')
+        #   errors[:email] # => ['is required', 'is invalid']
         def add(key, value, _opts = {})
           self[key] ||= []
           self[key] << value
           self[key].uniq!
         end
 
+        # Adds multiple errors from a hash.
+        # Values can be single messages or arrays of messages.
+        #
+        # @param errors_hash [Hash] hash of field names to error message(s)
+        #
+        # @example
+        #   errors.add_multiple_errors(email: 'is required', password: ['is too short', 'is too weak'])
         def add_multiple_errors(errors_hash)
           errors_hash.each do |key, values|
             CommandCallable::Utils.array_wrap(values).each { |value| add key, value }
           end
         end
 
+        # Iterates over each field and message pair.
+        # If a field has multiple messages, yields once for each message.
+        #
+        # @yieldparam field [Symbol] the field name
+        # @yieldparam message [String] the error message
+        #
+        # @example
+        #   errors.each { |field, message| puts "#{field}: #{message}" }
         def each
           each_key do |field|
             self[field].each { |message| yield field, message }
           end
         end
 
+        # Returns an array of formatted error messages.
+        # Messages are prefixed with the capitalized field name, except for :base.
+        #
+        # @return [Array<String>] formatted error messages
+        #
+        # @example
+        #   errors.add(:email, 'is required')
+        #   errors.add(:base, 'Something went wrong')
+        #   errors.full_messages # => ['Email is required', 'Something went wrong']
         def full_messages
           map { |attribute, message| full_message(attribute, message) }
         end

data/lib/simple_command_dispatcher/configuration.rb

@@ -3,8 +3,6 @@
 # This is the configuration for SimpleCommandDispatcher.
 module SimpleCommandDispatcher
   class << self
-    attr_reader :configuration
-
     # Configures SimpleCommandDispatcher by yielding the configuration object to the block.
     #
     # @yield [Configuration] yields the configuration object to the block
@@ -13,7 +11,7 @@ module SimpleCommandDispatcher
     # @example
     #
     # SimpleCommandDispatcher.configure do |config|
-    #  config.some_option = 'some value'
+    #  config.logger = Rails.logger
     # end
     def configure
       self.configuration ||= Configuration.new
@@ -23,6 +21,13 @@ module SimpleCommandDispatcher
       configuration
     end
 
+    # Returns the configuration object, initializing it if necessary
+    #
+    # @return [Configuration] the configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
     private
 
     attr_writer :configuration
@@ -31,16 +36,30 @@ module SimpleCommandDispatcher
   # 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
+    # @return [Logger] the logger instance used for debug output.
+    #   Defaults to Rails.logger in Rails applications, or Logger.new($stdout) otherwise.
+    attr_accessor :logger
 
     # Initializes a new Configuration instance with default values
     def initialize
       reset
     end
 
-    # Resets all configuration attributes to their default values
+    # Resets all configuration attributes to their default values.
+    # Sets logger to Rails.logger if Rails is defined, otherwise creates a new Logger writing to $stdout.
     def reset
-      # TODO: Reset our attributes here e.g. @attr = nil
+      @logger = default_logger
+    end
+
+    private
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger
+      else
+        require 'logger'
+        ::Logger.new($stdout)
+      end
     end
   end
 end

data/lib/simple_command_dispatcher/helpers/camelize.rb

@@ -25,7 +25,7 @@ module SimpleCommandDispatcher
         # 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 /
+          .gsub(%r{[/\-.\s:]+}, '/') # Normalize separators to /
           .split('/')                                    # Split into path segments
           .reject(&:empty?)                              # Remove empty segments
           .map { |segment| segment.underscore.camelize } # Rails camelization

data/lib/simple_command_dispatcher/logger.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  # Provides logging functionality for SimpleCommandDispatcher.
+  # Supports configuration to use Rails logger or custom loggers.
+  module Logger
+    private
+
+    def log_debug(string)
+      logger.debug(string) if logger.respond_to?(:debug)
+    end
+
+    def log_error(string)
+      logger.error(string) if logger.respond_to?(:error)
+    end
+
+    def logger
+      SimpleCommandDispatcher.configuration.logger
+    end
+  end
+end

data/lib/simple_command_dispatcher/services/command_service.rb

@@ -2,6 +2,7 @@
 
 require_relative '../errors'
 require_relative '../helpers/camelize'
+require_relative '../logger'
 require_relative 'command_namespace_service'
 
 module SimpleCommandDispatcher
@@ -9,8 +10,10 @@ module SimpleCommandDispatcher
     # Handles class and module transformations and instantiation.
     class CommandService
       include Helpers::Camelize
+      include Logger
 
-      def initialize(command:, command_namespace: {})
+      def initialize(command:, command_namespace: {}, options: {})
+        @options = options
         @command = validate_command(command:)
         @command_namespace = validate_command_namespace(command_namespace:)
       end
@@ -25,15 +28,24 @@ module SimpleCommandDispatcher
       #
       # @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 })
+      #   CommandService.new(command: "Authenticate", command_namespace: "Api").to_class
+      #     # => Api::Authenticate
+      #   CommandService.new(command: :Authenticate, command_namespace: [:Api, :AppName, :V1]).to_class
+      #     # => Api::AppName::V1::Authenticate
+      #   CommandService.new(command: :Authenticate,
+      #                      command_namespace: { api: :Api, app_name: :AppName, api_version: :V2 }).to_class
       #     # => 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
+      #   CommandService.new(command: "authenticate", command_namespace: "api::app_name::v1").to_class
+      #     # => Api::AppName::V1::Authenticate
       #
       def to_class
-        qualified_class_string = to_qualified_class_string(command, command_namespace)
+        qualified_class_string = to_qualified_class_string
+
+        if options.debug?
+          log_debug <<~DEBUG
+            Command to execute: #{qualified_class_string.inspect}
+          DEBUG
+        end
 
         begin
           qualified_class_string.constantize
@@ -44,24 +56,13 @@ module SimpleCommandDispatcher
 
       private
 
-      attr_accessor :command, :command_namespace
+      attr_reader :options, :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)
+      def to_qualified_class_string
         class_modules_string = CommandNamespaceService.new(command_namespace:).to_class_modules_string
         class_string = to_class_string(command:)
         "#{class_modules_string}#{class_string}"
@@ -87,19 +88,18 @@ module SimpleCommandDispatcher
 
       # @!visibility public
       #
-      # Validates command and returns command as a string after all blanks have been removed using
-      # command.gsub(/\s+/, "").
+      # Validates command and returns command as a string after leading and trailing whitespace is stripped.
       #
-      # @param [Symbol or String] command the class name to be validated. command cannot be empty?
+      # @param command [Symbol, String] the class name to be validated. command cannot be empty after stripping.
       #
-      # @return [String] the validated class as a string with blanks removed.
+      # @return [String] the validated class as a string with leading/trailing whitespace 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"
+      #   validate_command(command: " MyClass ") # => "MyClass"
+      #   validate_command(command: :MyClass) # => "MyClass"
       #
       def validate_command(command:)
         unless command.is_a?(Symbol) || command.is_a?(String)
@@ -119,17 +119,17 @@ module SimpleCommandDispatcher
       #
       # Validates and returns command_namespace.
       #
-      # @param [Hash, Array or String] command_namespace the module(s) to be validated.
+      # @param command_namespace [Hash, Array, String] the module(s) to be validated.
       #
-      # @return [Hash, Array or String] the validated module(s).
+      # @return [Hash, Array, String] the validated module(s), or {} if blank.
       #
       # @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"
+      #   validate_command_namespace(command_namespace: "Api::V1") # => "Api::V1"
+      #   validate_command_namespace(command_namespace: [:Api, :V1]) # => [:Api, :V1]
+      #   validate_command_namespace(command_namespace: { api: :Api, version: :V1 }) # => { api: :Api, version: :V1 }
       #
       def validate_command_namespace(command_namespace:)
         return {} if command_namespace.blank?

data/lib/simple_command_dispatcher/services/options_service.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SimpleCommandDispatcher
+  module Services
+    # Handles options for command execution and ensures proper initialization.
+    #
+    # @example
+    #   options = OptionsService.new(options: { debug: true })
+    #   options.debug? # => true
+    class OptionsService
+      # Default options for command execution
+      DEFAULT_OPTIONS = {
+        debug: false
+      }.freeze
+
+      # Initializes the options service with the provided options merged with defaults.
+      #
+      # @param options [Hash] custom options
+      # @option options [Boolean] :debug (false) enables debug logging when true
+      def initialize(options: {})
+        @options = DEFAULT_OPTIONS.merge(options)
+      end
+
+      # Returns true if debug mode is enabled.
+      # When enabled, debug logging will show command execution flow.
+      #
+      # @return [Boolean] true if debug mode is enabled
+      def debug?
+        options[:debug]
+      end
+
+      private
+
+      attr_reader :options
+    end
+  end
+end

data/lib/simple_command_dispatcher/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleCommandDispatcher
-  VERSION = '4.1.0'
+  VERSION = '4.2.0'
 end

data/lib/simple_command_dispatcher.rb

@@ -6,10 +6,14 @@ require 'core_ext/kernel'
 require 'simple_command_dispatcher/commands/command_callable'
 require 'simple_command_dispatcher/configuration'
 require 'simple_command_dispatcher/errors'
+require 'simple_command_dispatcher/logger'
 require 'simple_command_dispatcher/services/command_service'
+require 'simple_command_dispatcher/services/options_service'
 require 'simple_command_dispatcher/version'
 
 module SimpleCommandDispatcher
+  extend Logger
+
   # Provides a way to call your custom commands dynamically.
   #
   class << self
@@ -18,10 +22,10 @@ module SimpleCommandDispatcher
     #
     # @param command [Symbol, String] the name of the Command to call.
     #
-    # @param command_namespace [Hash, Array] the ruby modules that qualify the Command to call.
+    # @param command_namespace [Hash, Array, String] the ruby modules that qualify the Command to call.
     #    When passing a Hash, the Hash keys serve as documentation only.
-    #    For example, ['Api', 'AppName', 'V1'] and { :api :Api, app_name: :AppName, api_version: :V1 }
-    #    will both produce 'Api::AppName::V1', this string will be prepended to the command to form the Command
+    #    For example, ['Api', 'AppName', 'V1'], 'Api::AppName::V1', and { :api :Api, app_name: :AppName, api_version: :V1 }
+    #    will all produce 'Api::AppName::V1', this string will be prepended to the command to form the Command
     #    to call (e.g. 'Api::AppName::V1::MySimpleCommand' = Api::AppName::V1::MySimpleCommand.call(*request_params)).
     #
     # @param request_params [Hash, Array, Object] the parameters to pass to the call method of the Command. This
@@ -29,6 +33,10 @@ module SimpleCommandDispatcher
     #    keyword arguments, Array parameters are passed as positional arguments, and other objects are passed
     #    as a single argument.
     #
+    # @param options [Hash] optional configuration for command execution.
+    #    Supported options:
+    #    - :debug [Boolean] when true, enables debug logging of command execution flow
+    #
     # @return [Object] the Object returned as a result of calling the Command#call method.
     #
     # @example
@@ -50,20 +58,43 @@ module SimpleCommandDispatcher
     #     command_namespace: ['Api::Auth::JazzMeUp', :V1],
     #     request_params: ['jazz_me@gmail.com', 'JazzM3!']) # => Command result
     #
-    def call(command:, command_namespace: {}, request_params: nil)
+    def call(command:, command_namespace: {}, request_params: nil, options: {})
+      @options = Services::OptionsService.new(options:)
+
+      if @options.debug?
+        log_debug <<~DEBUG
+          Begin dispatching command
+            command: #{command.inspect}
+            command_namespace: #{command_namespace.inspect}
+        DEBUG
+      end
+
       # Create a constantized class from our command and command_namespace...
-      constantized_class_object = Services::CommandService.new(command:, command_namespace:).to_class
+      constantized_class_object = Services::CommandService.new(command:, command_namespace:, options: @options).to_class
+
+      if @options.debug?
+        log_debug <<~DEBUG
+          Constantized command: #{constantized_class_object.inspect}
+        DEBUG
+      end
+
       validate_command!(constantized_class_object)
 
       # We know we have a valid command class object if we get here. All we need to do is call the .call
       # class method, pass the request_params arguments depending on the request_params data type, and
       # return the results.
 
-      call_command(constantized_class_object:, request_params:)
+      command_object = call_command(constantized_class_object:, request_params:)
+
+      log_debug 'End dispatching command' if @options.debug?
+
+      command_object
     end
 
     private
 
+    attr_reader :options
+
     def call_command(constantized_class_object:, request_params:)
       if request_params.is_a?(Hash)
         constantized_class_object.call(**request_params)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: simple_command_dispatcher
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -71,8 +71,10 @@ files:
 - lib/simple_command_dispatcher/errors/required_class_method_missing_error.rb
 - lib/simple_command_dispatcher/helpers/camelize.rb
 - lib/simple_command_dispatcher/helpers/trim_all.rb
+- lib/simple_command_dispatcher/logger.rb
 - lib/simple_command_dispatcher/services/command_namespace_service.rb
 - lib/simple_command_dispatcher/services/command_service.rb
+- lib/simple_command_dispatcher/services/options_service.rb
 - lib/simple_command_dispatcher/version.rb
 - simple_command_dispatcher.gemspec
 homepage: https://github.com/gangelo/simple_command_dispatcher
@@ -96,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Dynamic command execution for Rails applications using convention over configuration
   - automatically maps request routes to command classes.