simple_command_dispatcher 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0144dd27d6c3f36427f08f5c44d12960a2a3d3807b08cad71ea1599ea13e8c32
-  data.tar.gz: 7c8505c9dda676c57695c1860972b5bbe3ad693b14e3c69e0468fda3292b7a62
+  metadata.gz: 78aeec50e25d248707c465097b003bf35eb4f6783c7405f68ea08264a1e655a3
+  data.tar.gz: 3d1333a439993ac0ad274c87d4244aadada69bcc7ddb5b064f34847b43396e46
 SHA512:
-  metadata.gz: afaa936a89c964a9463652cdfc46c50e0c040ce6f57cf2c4b30ffe08f500ebc00ebf7947162c65894301e008776d8c10508353a684e1d6dc060c3dfdc4ef15ed
-  data.tar.gz: d9497737a1f54a2b43d2dbd54809c8af707da645ba7ef2aace3dc9706a31db051bbe002df484a79525d940c97be3a00bc609f6879434205ef46bf7763b74874c
+  metadata.gz: c8c0b2631ad96c502f878df531e41f04a11ef92d11f059303fc4be3ad18afcd7f927c50cc9978f4c63e14f3026e03b7fa78529025a18d99f4bf31e4919152a3f
+  data.tar.gz: fe7cb001f4315809acd6699f40e199b864e9e0c88da78ac84ba806f989309367a54e1af71ce7fa490c5cca946a391498bd1ef56e3c2f1a2af0374efa45dbf853

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # CHANGELOG
 
+## Version 4.1.0 - 2025-07-14
+
+- **New Feature: CommandCallable Module**:
+  
+  - Introduced `SimpleCommandDispatcher::Commands::CommandCallable` module for standardizing command classes
+  - Provides automatic `.call` class method generation that instantiates and calls your command
+  - Built-in success/failure tracking with `success?` and `failure?` methods based on error state
+  - Automatic result tracking - command return values stored in `command.result`
+  - Consistent error handling with built-in `errors` object for error collection and management
+  - Call tracking to ensure methods work correctly and commands are properly executed
+  - Completely optional but recommended for building robust, maintainable commands
+
+- **Enhanced Documentation**:
+
+  - Major README.md overhaul with real-world examples showcasing dynamic command execution
+  - Added comprehensive examples demonstrating convention over configuration approach
+  - Included versioned API command examples (V1 vs V2) showing practical usage patterns
+  - Added controller examples showing how to use `request.path` and `params` for dynamic routing
+  - Enhanced payment processing example with proper error handling and rescue patterns
+  - Added efficient database query examples using ActiveRecord scopes
+  - Improved parameter handling documentation showing kwargs vs single hash approaches
+  - Added alternative command splitting approach for more granular control
+  - Updated all examples to use `command` variable instead of `result` for clarity
+  - Added custom command guidance for users who prefer to roll their own implementations
+
 ## Version 4.0.0 - 2025-07-12
 
 - **Documentation Overhaul**:

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    simple_command_dispatcher (4.0.0)
-      activesupport (>= 7.0.8, < 8.0)
+    simple_command_dispatcher (4.1.0)
+      activesupport (>= 7.0.8, < 9.0)
 
 GEM
   remote: https://rubygems.org/

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=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)
 [![](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,7 +42,7 @@ Or install it yourself as:
 
 ## Requirements
 
-- Ruby >= 3.1.0
+- Ruby >= 3.3.0
 - Rails (optional, but optimized for Rails applications)
 
 ## Basic Usage
@@ -49,31 +51,171 @@ Or install it yourself as:
 
 ```ruby
 # Basic command call
-result = SimpleCommandDispatcher.call(
+command = SimpleCommandDispatcher.call(
   command: 'AuthenticateUser',
   command_namespace: 'Api::V1',
   request_params: { email: 'user@example.com', password: 'secret' }
 )
 
-# This calls: Api::V1::AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+# This executes: 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: [: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"
+      command_namespace: nil,       # nil 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** if you need more control over command name and namespace:
+
+```ruby
+# Split the path manually
+command = SimpleCommandDispatcher.call(
+  command: request.path.split("/").last,           # "search"
+  command_namespace: request.path.split("/")[0..2], # "/api/v1/mechs"
+  request_params: params
+)
+```
+
+### Versioned Command Examples
+
+```ruby
+# app/commands/api/v1/mechs/search.rb
+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
+  end
+
+  private
+
+  attr_reader :name
+end
+
+# app/commands/api/v2/mechs/search.rb
+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)
+        .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
+
+  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
 ```
 
-### Automatic Camelization
+**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:
 
-Command names and namespaces are automatically camelized using optimized RESTful route conversion, allowing flexible input formats:
+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
+
+### Convention Over Configuration: Route-to-Command Mapping
+
+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 +232,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 +243,78 @@ SimpleCommandDispatcher.call(
 # Calls: Api::Café::V1::CaféCommand.call
 ```
 
-### Parameter Handling
-
-The dispatcher supports multiple parameter formats:
-
-```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')
-
-# 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')
-
-# Single parameter
-SimpleCommandDispatcher.call(
-  command: 'SendEmail',
-  command_namespace: 'Mailers',
-  request_params: 'user@example.com'
-)
-# Calls: Mailers::SendEmail.call('user@example.com')
-
-# No parameters
-SimpleCommandDispatcher.call(
-  command: 'HealthCheck',
-  command_namespace: 'System'
-)
-# Calls: System::HealthCheck.call
-```
-
-## Rails Integration Example
+### Dynamic Parameter Handling
 
-Here's a comprehensive example showing how to integrate SCD with a Rails API application:
-
-### Application Controller
+The dispatcher intelligently handles different parameter types based on how your command initializer is coded:
 
 ```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('/')
-  end
+# Hash params → keyword arguments
+def initialize(name:, email:)  # kwargs
+  # Called with: YourCommand.call(name: 'John', email: 'john@example.com')
+end
 
-  private
+# Hash params → single hash argument
+def initialize(params = {})    # single hash
+  # Called with: YourCommand.call({name: 'John', email: 'john@example.com'})
+end
 
-  def authenticate_request
-    result = SimpleCommandDispatcher.call(
-      command: 'AuthenticateRequest',
-      command_namespace: get_command_namespace,
-      request_params: { headers: request.headers }
-    )
+# Array params → positional arguments
+request_params: ['arg1', 'arg2', 'arg3']
+# Called with: YourCommand.call('arg1', 'arg2', 'arg3')
 
-    if result.success?
-      @current_user = result.user
-    else
-      render json: { error: 'Not Authorized' }, status: 401
-    end
-  end
-end
+# Single param → single argument
+request_params: 'single_value'
+# Called with: YourCommand.call('single_value')
 ```
 
-### Controller Actions
+### Payment Processing Example
 
 ```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
+# app/commands/api/v1/payments/process.rb
+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 update
-    result = SimpleCommandDispatcher.call(
-      command: 'UpdateUser',
-      command_namespace: get_command_namespace,
-      request_params: { id: params[:id], **user_params }
-    )
+  def call
+    validate_payment_data
+    return nil if errors.any?
 
-    if result.success?
-      render json: result.user
-    else
-      render json: { errors: result.errors }, status: :unprocessable_entity
-    end
+    charge_card
+  rescue StandardError => e
+    errors.add(:payment, e.message)
+    nil
   end
 
   private
 
-  def user_params
-    params.require(:user).permit(:name, :email, :phone)
-  end
-end
-```
-
-### Command Classes
+  attr_reader :amount, :card_token, :user_id
 
-```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
+  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
-end
-```
 
-```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
+  def charge_card
+    PaymentProcessor.charge(
+      amount: amount,
+      card_token: card_token,
+      user_id: user_id
+    )
   end
 end
 ```
 
-### Autoloading Commands
+**Route:** `POST /api/v1/payments/process` automatically calls `Api::V1::Payments::Process.call(params)`
 
-To ensure your command classes are properly loaded:
+### Custom Commands
 
-```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 +322,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,73 +338,6 @@ rescue ArgumentError => e
 end
 ```
 
-## Advanced Usage
-
-### Route-Based Command Dispatch
-
-For RESTful APIs, you can map routes directly to commands:
-
-```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
-  )
-end
-```
-
-### Dynamic API Versioning
-
-```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
-
-# Usage
-result = call_versioned_command('authenticate_user', 'v2')
-```
-
-### Batch Command Execution
-
-```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]
-    )
-  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 }
-  end
-end
-```
-
 ## Configuration
 
 The gem can be configured in an initializer:

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/version.rb

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

data/lib/simple_command_dispatcher.rb

@@ -3,6 +3,7 @@
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/inflections'
 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/services/command_service'

data/simple_command_dispatcher.gemspec

@@ -10,12 +10,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Gene M. Angelo, Jr.']
   spec.email         = ['public.gma@gmail.com']
 
-  spec.summary       = 'Provides a way to dispatch simple_command (ruby gem) commands or your own custom commands (service objects) in a more dynamic manner
-                          within your service API. Ideal for rails-api.'
-  spec.description   = 'Within a services API (rails-api for instance), you may have a need to execute different simple_commands or your own custom commands (service objects)
-                          based on one or more factors: multiple application, API version, user type, user credentials, etc. For example,
-                          your service API may need to execute either Api::Auth::V1::AuthenticateCommand.call(...) or Api::Auth::V2::AuthenticateCommand.call(...)
-                          based on the API version. simple_command_dispatcher allows you to execute either command with one line of code dynamically.'.gsub(/\s+/, ' ')
+  spec.summary       = 'Dynamic command execution for Rails applications using convention over configuration - automatically maps request routes to command classes.'
+  spec.description   = 'A lightweight Ruby gem that enables Rails applications to dynamically execute command objects using convention over configuration. ' \
+                       'Automatically transforms request paths into Ruby class constants, allowing controllers to dispatch commands based on routes and parameters. ' \
+                       'Features the optional CommandCallable module for standardized command interfaces with built-in success/failure tracking and error handling. ' \
+                       'Perfect for clean, maintainable Rails APIs with RESTful route-to-command mapping. Only depends on ActiveSupport for reliable camelization.'
   spec.homepage      = 'https://github.com/gangelo/simple_command_dispatcher'
   spec.license       = 'MIT'
 
@@ -37,5 +36,5 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new('>= 3.3', '< 4.0')
 
-  spec.add_runtime_dependency 'activesupport', '>= 7.0.8', '< 8.0'
+  spec.add_runtime_dependency 'activesupport', '>= 7.0.8', '< 9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_command_dispatcher
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
@@ -18,7 +18,7 @@ dependencies:
         version: 7.0.8
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -28,13 +28,14 @@ dependencies:
         version: 7.0.8
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
-description: 'Within a services API (rails-api for instance), you may have a need
-  to execute different simple_commands or your own custom commands (service objects)
-  based on one or more factors: multiple application, API version, user type, user
-  credentials, etc. For example, your service API may need to execute either Api::Auth::V1::AuthenticateCommand.call(...)
-  or Api::Auth::V2::AuthenticateCommand.call(...) based on the API version. simple_command_dispatcher
-  allows you to execute either command with one line of code dynamically.'
+        version: '9.0'
+description: A lightweight Ruby gem that enables Rails applications to dynamically
+  execute command objects using convention over configuration. Automatically transforms
+  request paths into Ruby class constants, allowing controllers to dispatch commands
+  based on routes and parameters. Features the optional CommandCallable module for
+  standardized command interfaces with built-in success/failure tracking and error
+  handling. Perfect for clean, maintainable Rails APIs with RESTful route-to-command
+  mapping. Only depends on ActiveSupport for reliable camelization.
 email:
 - public.gma@gmail.com
 executables: []
@@ -61,6 +62,9 @@ files:
 - bin/setup
 - lib/core_ext/kernel.rb
 - lib/simple_command_dispatcher.rb
+- lib/simple_command_dispatcher/commands/command_callable.rb
+- lib/simple_command_dispatcher/commands/errors.rb
+- lib/simple_command_dispatcher/commands/utils.rb
 - lib/simple_command_dispatcher/configuration.rb
 - lib/simple_command_dispatcher/errors.rb
 - lib/simple_command_dispatcher/errors/invalid_class_constant_error.rb
@@ -94,7 +98,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.8
 specification_version: 4
-summary: Provides a way to dispatch simple_command (ruby gem) commands or your own
-  custom commands (service objects) in a more dynamic manner within your service API.
-  Ideal for rails-api.
+summary: Dynamic command execution for Rails applications using convention over configuration
+  - automatically maps request routes to command classes.
 test_files: []