simple_command_dispatcher 4.0.0 → 4.2.0

data/README.md

@@ -1,6 +1,6 @@
-[![Ruby](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml/badge.svg?refresh=6)](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml)
-[![GitHub version](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher.svg?refresh=6)](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
-[![Gem Version](https://badge.fury.io/rb/simple_command_dispatcher.svg?refresh=6)](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)
@@ -12,15 +12,17 @@
 
 **simple_command_dispatcher** (SCD) allows your Rails or Rails API application to _dynamically_ call backend command services from your Rails controller actions using a flexible, convention-over-configuration approach.
 
+📋 **See it in action:** Check out the [demo application](https://github.com/gangelo/simple_command_dispatcher_demo_app) - a Rails API app with tests that demonstrate how to use the gem and its capabilities.
+
 ## Features
 
-- 🚀 **Dynamic Command Dispatch**: Call command classes by name with flexible namespacing
-- 🔄 **Automatic Camelization**: Converts RESTful routes to Ruby constants automatically
-- 🌐 **Unicode Support**: Handles Unicode characters and whitespace properly
-- 🎯 **Multiple Input Formats**: Accepts strings, arrays, hashes for commands and namespaces
-- ⚡ **Performance Optimized**: Uses Rails' proven camelization methods for speed
-- 🔧 **Flexible Parameters**: Supports Hash, Array, and single object parameters
-- 📦 **No Dependencies**: Removed simple_command dependency for lighter footprint
+- 🛠️ **Convention Over Configuration**: Call commands dynamically from controller actions using action routes and parameters
+- 🎭 **Command Standardization**: Optional `CommandCallable` module for consistent command interfaces with built-in success/failure tracking
+- 🚀 **Dynamic Route-to-Command Mapping**: Automatically transforms request paths into Ruby class constants
+- 🔄 **Intelligent Parameter Handling**: Supports Hash, Array, and single object parameters with automatic detection
+- 🌐 **Flexible Input Formats**: Accepts strings, arrays, symbols with various separators and Unicode support
+- ⚡ **Performance Optimized**: Uses Rails' proven camelization methods for fast route-to-constant conversion
+- 📦 **Lightweight**: Minimal dependencies - only ActiveSupport for reliable camelization
 
 ## Installation
 
@@ -40,40 +42,302 @@ Or install it yourself as:
 
 ## Requirements
 
-- Ruby >= 3.1.0
+- 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
-result = SimpleCommandDispatcher.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 calls: 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
+
+The gem includes a powerful `CommandCallable` module that standardizes your command classes, providing automatic success/failure tracking, error handling, and a consistent interface. This module is completely optional but highly recommended for building robust, maintainable commands.
+
+### The Real Power: Dynamic Command Execution using convention over configuration
+
+Where this gem truly shines is its ability to **dynamically execute commands** using a **convention over configuration** approach. Command names and namespacing match controller action routes, making it possible to dynamically execute commands based on controller/action routes and pass arguments dynamically using params.
+
+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: [:destroy, :index]
+
+  def index
+    render json: { mechs: Mech.all }
+  end
+
+  def search
+    # Action intentionally left empty, routing handled by before_action
+  end
+
+  private
+
+  def route_request
+    command = SimpleCommandDispatcher.call(
+      command: request.path,        # "/api/v1/mechs/search"
+      # 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
+    )
+
+    if command.success?
+      render json: { mechs: command.result }, status: :ok
+    else
+      render json: { errors: command.errors }, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+**The Convention:** Request path `/api/v1/mechs/search` automatically maps to command class `Api::V1::Mechs::Search`.
+
+**Alternative approach** for handling nested resource routes with dynamic actions:
+
+```ruby
+# 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: 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
+
+```ruby
+# app/commands/api/v1/mechs/search.rb
+class Api::V1::Mechs::Search
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+  def call
+    # V1 search logic - simple name search
+    name.present? ? Mech.where("mech_name ILIKE ?", "%#{name}%") : Mech.none
+  end
+
+  private
+
+  def initialize(params = {})
+    @name = params[:name]
+  end
+
+  attr_reader :name
+end
+
+# app/commands/api/v2/mechs/search.rb
+class Api::V2::Mechs::Search
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+  def call
+    # V2 search logic - comprehensive search using scopes
+    Mech.by_cost(cost)
+        .or(Mech.by_introduction_year(introduction_year))
+        .or(Mech.by_mech_name(mech_name))
+        .or(Mech.by_tonnage(tonnage))
+        .or(Mech.by_variant(variant))
+  end
+
+  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
+
+# app/models/mech.rb (V2 scopes)
+class Mech < ApplicationRecord
+  scope :by_mech_name, ->(name) {
+    name.present? ? where("mech_name ILIKE ?", "%#{name}%") : none
+  }
+
+  scope :by_variant, ->(variant) {
+    variant.present? ? where("variant ILIKE ?", "%#{variant}%") : none
+  }
+
+  scope :by_tonnage, ->(tonnage) {
+    tonnage.present? ? where(tonnage: tonnage) : none
+  }
+
+  scope :by_cost, ->(cost) {
+    cost.present? ? where(cost: cost) : none
+  }
+
+  scope :by_introduction_year, ->(year) {
+    year.present? ? where(introduction_year: year) : none
+  }
+end
+```
+
+**The Magic:** By convention, routes automatically map to commands:
+
+- `/api/v1/mechs/search` → `Api::V1::Mechs::Search`
+- `/api/v2/mechs/search` → `Api::V2::Mechs::Search`
+
+### What CommandCallable Provides
+
+When you prepend `CommandCallable` to your command class, you automatically get:
+
+1. **Class Method Generation**: Automatic `.call` class method that instantiates and calls your command
+2. **Result Tracking**: Your command's return value is stored in `command.result`
+3. **Success/Failure Methods**: `success?` and `failure?` methods based on error state
+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')
 ```
 
-### Automatic Camelization
+### Convention Over Configuration: Route-to-Command Mapping
 
-Command names and namespaces are automatically camelized using optimized RESTful route conversion, allowing flexible input formats:
+The gem automatically transforms route paths into Ruby class constants using intelligent camelization, allowing flexible input formats:
 
 ```ruby
 # All of these are equivalent and call: Api::UserSessions::V1::CreateCommand.call
 
 # Lowercase strings with various separators
 SimpleCommandDispatcher.call(
-  command: 'create_command',
+  command: :create_command,
   command_namespace: 'api::user_sessions::v1'
 )
 
 # Mixed case array
 SimpleCommandDispatcher.call(
-  command: :CreateCommand,
+  command: 'CreateCommand',
   command_namespace: ['api', 'UserSessions', 'v1']
 )
 
@@ -90,7 +354,7 @@ SimpleCommandDispatcher.call(
 )
 ```
 
-The camelization handles Unicode characters and removes all whitespace (including Unicode whitespace):
+The transformation handles Unicode characters and removes all whitespace:
 
 ```ruby
 # Unicode support
@@ -101,219 +365,78 @@ SimpleCommandDispatcher.call(
 # Calls: Api::Café::V1::CaféCommand.call
 ```
 
-### Parameter Handling
+### Dynamic Parameter Handling
 
-The dispatcher supports multiple parameter formats:
+The dispatcher intelligently handles different parameter types based on how your command initializer is coded:
 
 ```ruby
-# Hash parameters (passed as keyword arguments)
-SimpleCommandDispatcher.call(
-  command: 'CreateUser',
-  command_namespace: 'Api::V1',
-  request_params: { name: 'John', email: 'john@example.com' }
-)
-# Calls: Api::V1::CreateUser.call(name: 'John', email: 'john@example.com')
+# Hash params → keyword arguments
+def initialize(name:, email:)  # kwargs
+  # Called with: YourCommand.call(name: 'John', email: 'john@example.com')
+end
 
-# Array parameters (passed as positional arguments)
-SimpleCommandDispatcher.call(
-  command: 'ProcessData',
-  command_namespace: 'Services',
-  request_params: ['data1', 'data2', 'data3']
-)
-# Calls: Services::ProcessData.call('data1', 'data2', 'data3')
+# Hash params → single hash argument
+def initialize(params = {})    # single hash
+  # Called with: YourCommand.call({name: 'John', email: 'john@example.com'})
+end
 
-# Single parameter
-SimpleCommandDispatcher.call(
-  command: 'SendEmail',
-  command_namespace: 'Mailers',
-  request_params: 'user@example.com'
-)
-# Calls: Mailers::SendEmail.call('user@example.com')
+# Array params → positional arguments
+request_params: ['arg1', 'arg2', 'arg3']
+# Called with: YourCommand.call('arg1', 'arg2', 'arg3')
 
-# No parameters
-SimpleCommandDispatcher.call(
-  command: 'HealthCheck',
-  command_namespace: 'System'
-)
-# Calls: System::HealthCheck.call
+# Single param → single argument
+request_params: 'single_value'
+# Called with: YourCommand.call('single_value')
 ```
 
-## Rails Integration Example
-
-Here's a comprehensive example showing how to integrate SCD with a Rails API application:
-
-### Application Controller
+### Payment Processing Example
 
 ```ruby
-# app/controllers/application_controller.rb
-require 'simple_command_dispatcher'
-
-class ApplicationController < ActionController::API
-  before_action :authenticate_request
-  attr_reader :current_user
-
-  protected
-
-  def get_command_namespace
-    # Extract namespace from request path: "/api/my_app/v1/users" → "api/my_app/v1"
-    path_segments = request.path.split('/').reject(&:empty?)
-    path_segments.take(3).join('/')
+# app/commands/api/v1/payments/process.rb
+class Api::V1::Payments::Process
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
+
+  def call
+    validate_payment_data
+    return nil if errors.any?
+
+    charge_card
+  rescue StandardError => e
+    errors.add(:payment, e.message)
+    nil
   end
 
   private
 
-  def authenticate_request
-    result = SimpleCommandDispatcher.call(
-      command: 'AuthenticateRequest',
-      command_namespace: get_command_namespace,
-      request_params: { headers: request.headers }
-    )
-
-    if result.success?
-      @current_user = result.user
-    else
-      render json: { error: 'Not Authorized' }, status: 401
-    end
+  def initialize(params = {})
+    @amount = params[:amount]
+    @card_token = params[:card_token]
+    @user_id = params[:user_id]
   end
-end
-```
 
-### Controller Actions
+  attr_reader :amount, :card_token, :user_id
 
-```ruby
-# app/controllers/api/my_app/v1/users_controller.rb
-class Api::MyApp::V1::UsersController < ApplicationController
-  def create
-    result = SimpleCommandDispatcher.call(
-      command: 'CreateUser',
-      command_namespace: get_command_namespace,
-      request_params: user_params
-    )
-
-    if result.success?
-      render json: result.user, status: :ok
-    else
-      render json: { errors: result.errors }, status: :unprocessable_entity
-    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 update
-    result = SimpleCommandDispatcher.call(
-      command: 'UpdateUser',
-      command_namespace: get_command_namespace,
-      request_params: { id: params[:id], **user_params }
+  def charge_card
+    PaymentProcessor.charge(
+      amount: amount,
+      card_token: card_token,
+      user_id: user_id
     )
-
-    if result.success?
-      render json: result.user
-    else
-      render json: { errors: result.errors }, status: :unprocessable_entity
-    end
-  end
-
-  private
-
-  def user_params
-    params.require(:user).permit(:name, :email, :phone)
   end
 end
 ```
 
-### Command Classes
+**Route:** `POST /api/v1/payments/process` automatically calls `Api::V1::Payments::Process.call(params)`
 
-```ruby
-# app/commands/api/my_app/v1/authenticate_request.rb
-module Api
-  module MyApp
-    module V1
-      class AuthenticateRequest
-        def self.call(headers:)
-          new(headers: headers).call
-        end
-
-        def initialize(headers:)
-          @headers = headers
-        end
-
-        def call
-          user = authenticate_with_token
-          if user
-            OpenStruct.new(success?: true, user: user)
-          else
-            OpenStruct.new(success?: false, errors: ['Invalid token'])
-          end
-        end
-
-        private
-
-        attr_reader :headers
-
-        def authenticate_with_token
-          token = headers['Authorization']&.gsub('Bearer ', '')
-          return nil unless token
-
-          # Your authentication logic here
-          User.find_by(auth_token: token)
-        end
-      end
-    end
-  end
-end
-```
+### Custom Commands
 
-```ruby
-# app/commands/api/my_app/v1/create_user.rb
-module Api
-  module MyApp
-    module V1
-      class CreateUser
-        def self.call(**params)
-          new(**params).call
-        end
-
-        def initialize(name:, email:, phone: nil)
-          @name = name
-          @email = email
-          @phone = phone
-        end
-
-        def call
-          user = User.new(name: name, email: email, phone: phone)
-
-          if user.save
-            OpenStruct.new(success?: true, user: user)
-          else
-            OpenStruct.new(success?: false, errors: user.errors.full_messages)
-          end
-        end
-
-        private
-
-        attr_reader :name, :email, :phone
-      end
-    end
-  end
-end
-```
-
-### Autoloading Commands
-
-To ensure your command classes are properly loaded:
-
-```ruby
-# config/initializers/simple_command_dispatcher.rb
-
-# Autoload command classes
-Rails.application.config.to_prepare do
-  commands_path = Rails.root.join('app', 'commands')
-
-  if commands_path.exist?
-    Dir[commands_path.join('**', '*.rb')].each do |file|
-      require_dependency file
-    end
-  end
-end
-```
+You can create your own command classes without `CommandCallable`. Just ensure your command responds to the `.call` class method and returns whatever structure you need. The dispatcher will call your command and return the result - your convention, your rules.
 
 ## Error Handling
 
@@ -321,7 +444,7 @@ The dispatcher provides specific error classes for different failure scenarios:
 
 ```ruby
 begin
-  result = SimpleCommandDispatcher.call(
+  command = SimpleCommandDispatcher.call(
     command: 'NonExistentCommand',
     command_namespace: 'Api::V1'
   )
@@ -337,81 +460,104 @@ rescue ArgumentError => e
 end
 ```
 
-## Advanced Usage
-
-### Route-Based Command Dispatch
+## Configuration
 
-For RESTful APIs, you can map routes directly to commands:
+The gem can be configured in an initializer:
 
 ```ruby
-# Extract command from route
-def dispatch_from_route
-  # Route: "/api/my_app/v1/users/create"
-  path_segments = request.path.split('/').reject(&:empty?)
-
-  namespace = path_segments.take(3).join('/')     # "api/my_app/v1"
-  command = path_segments.last                    # "create"
-
-  SimpleCommandDispatcher.call(
-    command: "#{command}_#{controller_name.singularize}",  # "create_user"
-    command_namespace: namespace,
-    request_params: request_params
-  )
+# config/initializers/simple_command_dispatcher.rb
+SimpleCommandDispatcher.configure do |config|
+  # 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
 ```
 
-### Dynamic API Versioning
+### Using Configuration in Commands
+
+You can access the configured logger within your commands to add custom logging:
 
 ```ruby
-# Handle multiple API versions dynamically
-def call_versioned_command(command_name, version = 'v1')
-  SimpleCommandDispatcher.call(
-    command: command_name,
-    command_namespace: ['api', app_name, version],
-    request_params: request_params
-  )
-end
+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
 
-# Usage
-result = call_versioned_command('authenticate_user', 'v2')
-```
+  private
 
-### Batch Command Execution
+  def initialize(params = {})
+    @amount = params[:amount]
+    @card_token = params[:card_token]
+    @user_id = params[:user_id]
+  end
 
-```ruby
-# Execute multiple related commands
-def process_user_registration(user_data)
-  commands = [
-    { command: 'validate_user', params: user_data },
-    { command: 'create_user', params: user_data },
-    { command: 'send_welcome_email', params: { email: user_data[:email] } }
-  ]
-
-  results = commands.map do |cmd|
-    SimpleCommandDispatcher.call(
-      command: cmd[:command],
-      command_namespace: 'user_registration',
-      request_params: cmd[:params]
-    )
+  attr_reader :amount, :card_token, :user_id
+
+  def logger
+    SimpleCommandDispatcher.configuration.logger
   end
 
-  # Check if all commands succeeded
-  if results.all?(&:success?)
-    { success: true, user: results[1].user }
-  else
-    { success: false, errors: results.map(&:errors).flatten.compact }
+  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
 ```
 
-## Configuration
+### Debug Logging
 
-The gem can be configured in an initializer:
+The gem includes built-in debug logging that can be enabled using the `debug` option. This is useful for debugging command execution flow:
 
 ```ruby
-# config/initializers/simple_command_dispatcher.rb
+# 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|
-  # Configuration options will be added in future versions
+  logger = Logger.new($stdout)
+  logger.level = Logger::DEBUG  # Set appropriate level
+  config.logger = logger
 end
 ```