simple_command_dispatcher 3.0.4 → 4.1.0

data/README.md

@@ -1,308 +1,396 @@
-[![Ruby](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml/badge.svg?refresh=2)](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml)
-[![GitHub version](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher.svg?refresh=5)](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
-[![Gem Version](https://badge.fury.io/rb/simple_command_dispatcher.svg?refresh=5)](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)
 [![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
 
-# Q. simple_command_dispatcher - what is it?
-# A. It's a Ruby gem!!!
+# simple_command_dispatcher
 
 ## Overview
-__simple_command_dispatcher__ (SCD) allows you to execute __simple_command__ commands (and now _custom commands_ as of version 1.2.1) in a more dynamic way. If you are not familiar with the _simple_command_ gem, check it out [here][simple-command]. SCD was written specifically with the [rails-api][rails-api] in mind; however, you can use SDC wherever you would use simple_command commands.
 
-## Update as of Version 1.2.1
-### Custom Commands
-SCD now allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true` (see the __Custom Commands__ section below for details).
+**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.
 
-## Example
-The below example is from a `rails-api` API that uses token-based authentication and services two mobile applications, identified as *__my_app1__* and *__my_app2__*, in this example.
+📋 **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.
 
-This example assumes the following:
+## Features
 
-* `application_controller` is a base class, inherited by all other controllers. The `#authenticate_request` method is called for every request in order to make sure the request is authorized (`before_action :authenticate_request`).
-* `request.headers` will contain the authorization token to authorize all requests (`request.headers["Authorization"]`)
-* This application uses the following folder structure to manage its _simple_command_ commands:
+- 🛠️ **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
 
-![N|Solid](https://cldup.com/1UeyWzOLic.png)
+## Installation
 
-Command classes (and the modules they reside under) are named *__according to their file name and respective location within the above folder structure__*; for example, the command class defined in the `/api/my_app1/v1/authenticate_request.rb` file would be defined in this manner:
+Add this line to your application's Gemfile:
 
 ```ruby
-# /api/my_app1/v1/authenticate_request.rb
-
-module Api
-   module MyApp1
-      module V1
-         class AuthenticateRequest
-         end
-     end
-   end
-end
+gem 'simple_command_dispatcher'
 ```
 
-Likewise, the command class defined in the `/api/my_app2/v2/update_user.rb` file would be defined in this manner, and so on:
+And then execute:
 
-```ruby
-# /api/my_app2/v2/update_user.rb
-
-module Api
-   module MyApp2
-      module V2
-         class UpdateUser
-         end
-     end
-   end
-end
-```
+    $ bundle
+
+Or install it yourself as:
 
-The __routes used in this example__, conform to the following format: `"/api/[app_name]/[app_version]/[controller]"` where `[app_name]` = the _application name_,`[app_version]` = the _application version_, and `[controller]` = the _controller_; therefore, running `$ rake routes` for this example would output the following sample route information:
+    $ gem install simple_command_dispatcher
 
+## Requirements
 
-| Prefix        | Verb | URI Pattern | Controller#Action |
-|-------------:|:-------------|:------------------|:------------------|
-| api_my_app1_v1_user_authenticate | POST  | /api/my_app1/v1/user/authenticate(.:format) | api/my_app1/v1/authentication#create |
-| api_my_app1_v2_user_authenticate | POST  | /api/my_app1/v2/user/authenticate(.:format) | api/my_app1/v2/authentication#create |
-| api_my_app2_v1_user_authenticate | POST  | /api/my_app2/v1/user/authenticate(.:format) | api/my_app2/v1/authentication#create |
-| api_my_app2_v2_user              | PATCH | /api/my_app2/v2/users/:id(.:format)         | api/my_app2/v2/users#update |
-|                                  | PUT   | /api/my_app2/v2/users/:id(.:format)         | api/my_app2/v2/users#update |
+- Ruby >= 3.3.0
+- Rails (optional, but optimized for Rails applications)
 
+## Basic Usage
 
-### Request Authentication Code Snippet
+### Simple Command Dispatch
 
 ```ruby
-# /config/initializers/simple_command_dispatcher.rb
-
-# See: http://pothibo.com/2013/07/namespace-stuff-in-your-app-folder/
-
-=begin
-# Uncomment this code if you want to namespace your commands in the following manner, for example:
-#
-#   class Api::MyApp1::V1::AuthenticateRequest; end
-#
-# As opposed to this:
-#
-#   module Api
-#      module MyApp1
-#         module V1
-#            class AuthenticateRequest
-#            end
-#         end
-#     end
-#   end
-#
-module Helpers
-   def self.ensure_namespace(namespace, scope = "::")
-      namespace_parts = namespace.split("::")
-
-      namespace_chain = ""
-
-      namespace_parts.each { | part |
-         namespace_chain = (namespace_chain.empty?) ? part : "#{namespace_chain}::#{part}"
-         eval("module #{scope}#{namespace_chain}; end")
-      }
-   end
-end
+# Basic command call
+command = SimpleCommandDispatcher.call(
+  command: 'AuthenticateUser',
+  command_namespace: 'Api::V1',
+  request_params: { email: 'user@example.com', password: 'secret' }
+)
+
+# This executes: Api::V1::AuthenticateUser.call(email: 'user@example.com', password: 'secret')
+```
 
-Helpers.ensure_namespace("Api::MyApp1::V1")
-Helpers.ensure_namespace("Api::MyApp1::V2")
-Helpers.ensure_namespace("Api::MyApp2::V1")
-Helpers.ensure_namespace("Api::MyApp2::V2")
-=end
-
-# simple_command_dispatcher creates commands dynamically; therefore we need
-# to make sure the namespaces and command classes are loaded before we construct and
-# call them. The below code traverses the 'app/api' and all subfolders, and
-# autoloads them so that we do not get any NameError exceptions due to
-# uninitialized constants.
-Rails.application.config.to_prepare do
-   path = Rails.root + "app/api"
-   ActiveSupport::Dependencies.autoload_paths -= [path.to_s]
-
-   reloader = ActiveSupport::FileUpdateChecker.new [], path.to_s => [:rb] do
-      ActiveSupport::DescendantsTracker.clear
-      ActiveSupport::Dependencies.clear
-
-      Dir[path + "**/*.rb"].each do |file|
-         ActiveSupport.require_or_load file
-      end
-   end
-
-   Rails.application.reloaders << reloader
-   ActionDispatch::Reloader.to_prepare { reloader.execute_if_updated }
-   reloader.execute
-end
+## Command Standardization with CommandCallable
 
-# Optionally set our configuration setting to allow
-# for custom command execution.
-SimpleCommand::Dispatcher.configure do |config|
-   config.allow_custom_commands = true
-end
-```
+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/application_controller.rb
-
-require 'simple_command_dispatcher'
-
-class ApplicationController < ActionController::API
-   before_action :authenticate_request
-   attr_reader :current_user
-
-   protected
-
-   def get_command_path
-      # request.env['PATH_INFO'] could return any number of paths. The important
-      # thing (in the case of our example), is that we get the portion of the
-      # path that uniquely identifies the SimpleCommand we need to call; this
-      # would include the application, the API version and the SimpleCommand
-      # name itself.
-      command_path = request.env['PATH_INFO'] # => "/api/[app name]/v1/[action]”
-      command_path = command_path.split('/').slice(0,4).join('/') # => "/api/[app name]/v1/"
-   end
-
-   private
-
-   def authenticate_request
-      # The parameters and options we are passing to the dispatcher, wind up equating
-      # to the following: Api::MyApp1::V1::AuthenticateRequest.call(request.headers).
-      # Explaination: @param command_modules (e.g. path, "/api/my_app1/v1/"), in concert with @param
-      # options { camelize: true }, is transformed into "Api::MyApp1::V1" and prepended to the
-      # @param command, which becomes "Api::MyApp1::V1::AuthenticateRequest." This string is then
-      # simply constantized; #call is then executed, passing the @param command_parameters
-      # (e.g. request.headers, which contains ["Authorization"], out authorization token).
-      # Consequently, the correlation between our routes and command class module structure
-      # was no coincidence.
-      command = SimpleCommand::Dispatcher.call(:AuthenticateRequest, get_command_path, { camelize: true}, request.headers)
-      if command.success?
-         @current_user = command.result
-      else
-         render json: { error: 'Not Authorized' }, status: 401
-      end
+# 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
 ```
 
-## Custom Commands
+**The Convention:** Request path `/api/v1/mechs/search` automatically maps to command class `Api::V1::Mechs::Search`
 
-As of __Version 1.2.1__ simple_command_dispatcher (SCD) allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true`.
+**Alternative approach** if you need more control over command name and namespace:
 
-In order to execute _custom commands_, there are three (3) requirements:
-   1. Create a _custom command_. Your _custom command_ class must expose a public `::call` class method.
-   2. Set the `Configuration#allow_custom_commands` property to `true`.
-   3. Execute your _custom command_ by calling the `::call` class method.
+```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
+)
+```
 
-### Custom Command Example
+### Versioned Command Examples
 
-#### 1. Create a Custom Command
 ```ruby
-# /api/my_app/v1/custom_command.rb
+# app/commands/api/v1/mechs/search.rb
+class Api::V1::Mechs::Search
+  prepend SimpleCommandDispatcher::Commands::CommandCallable
 
-module Api
-   module MyApp
-         module V1
+  def initialize(params = {})
+    @name = params[:name]
+  end
 
-            # This is a custom command that does not prepend SimpleCommand.
-            class CustomCommand
+  def call
+    # V1 search logic - simple name search
+    name.present? ? Mech.where("mech_name ILIKE ?", "%#{name}%") : Mech.none
+  end
 
-               def self.call(*args)
-                  command = self.new(*args)
-                  if command
-                     command.send(:execute)
-                  else
-                     false
-                  end
-               end
+  private
 
-               private
+  attr_reader :name
+end
 
-               def initialize(params = {})
-                  @param1 = params[:param1]
-               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
 
-               private
+# app/models/mech.rb (V2 scopes)
+class Mech < ApplicationRecord
+  scope :by_mech_name, ->(name) {
+    name.present? ? where("mech_name ILIKE ?", "%#{name}%") : none
+  }
 
-               attr_accessor :param1
+  scope :by_variant, ->(variant) {
+    variant.present? ? where("variant ILIKE ?", "%#{variant}%") : none
+  }
 
-               def execute
-                  if (param1 == :param1)
-                     return true
-                  end
+  scope :by_tonnage, ->(tonnage) {
+    tonnage.present? ? where(tonnage: tonnage) : none
+  }
 
-                  return false
-               end
-            end
+  scope :by_cost, ->(cost) {
+    cost.present? ? where(cost: cost) : none
+  }
 
-      end
-   end
+  scope :by_introduction_year, ->(year) {
+    year.present? ? where(introduction_year: year) : none
+  }
 end
 ```
-#### 2. Set the `Configuration#allow_custom_commands` property to `true`
+
+**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
+
+### 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_namespace: 'api::user_sessions::v1'
+)
+
+# Mixed case array
+SimpleCommandDispatcher.call(
+  command: 'CreateCommand',
+  command_namespace: ['api', 'UserSessions', 'v1']
+)
+
+# Route-like strings (optimized for Rails controllers)
+SimpleCommandDispatcher.call(
+  command: '/create_command',
+  command_namespace: '/api/user_sessions/v1'
+)
+
+# Mixed separators (hyphens, dots, spaces)
+SimpleCommandDispatcher.call(
+  command: 'create-command',
+  command_namespace: 'api.user-sessions/v1'
+)
+```
+
+The transformation handles Unicode characters and removes all whitespace:
+
 ```ruby
-# In your rails, rails-api app, etc...
-# /config/initializers/simple_command_dispatcher.rb
+# Unicode support
+SimpleCommandDispatcher.call(
+  command: 'café_command',
+  command_namespace: 'api :: café :: v1'  # Spaces are removed
+)
+# Calls: Api::Café::V1::CaféCommand.call
+```
 
-SimpleCommand::Dispatcher.configure do |config|
-    config.allow_custom_commands = true
+### Dynamic Parameter Handling
+
+The dispatcher intelligently handles different parameter types based on how your command initializer is coded:
+
+```ruby
+# Hash params → keyword arguments
+def initialize(name:, email:)  # kwargs
+  # Called with: YourCommand.call(name: 'John', email: 'john@example.com')
 end
+
+# Hash params → single hash argument
+def initialize(params = {})    # single hash
+  # Called with: YourCommand.call({name: 'John', email: 'john@example.com'})
+end
+
+# Array params → positional arguments
+request_params: ['arg1', 'arg2', 'arg3']
+# Called with: YourCommand.call('arg1', 'arg2', 'arg3')
+
+# Single param → single argument
+request_params: 'single_value'
+# Called with: YourCommand.call('single_value')
 ```
 
-#### 3. Execute your _Custom Command_
-Executing your _custom command_ is no different than executing a __SimpleCommand__ command with the exception that you must properly handle the return object that results from calling your _custom command_; being a _custom command_, there is no guarantee that the return object will be the command object as is the case when calling a SimpleCommand command.
+### Payment Processing Example
+
 ```ruby
-# /app/controllers/some_controller.rb
+# 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 call
+    validate_payment_data
+    return nil if errors.any?
+
+    charge_card
+  rescue StandardError => e
+    errors.add(:payment, e.message)
+    nil
+  end
+
+  private
+
+  attr_reader :amount, :card_token, :user_id
+
+  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
+```
 
-require 'simple_command_dispatcher'
+**Route:** `POST /api/v1/payments/process` automatically calls `Api::V1::Payments::Process.call(params)`
 
-class SomeController < ApplicationController::API
-   public
+### Custom Commands
 
-   def some_api
-      success = SimpleCommand::Dispatcher.call(:CustomCommand, get_command_path, { camelize: true}, request.headers)
-      if success
-         # Do something...
-      else
-         # Do something else...
-      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
+
+The dispatcher provides specific error classes for different failure scenarios:
+
+```ruby
+begin
+  command = SimpleCommandDispatcher.call(
+    command: 'NonExistentCommand',
+    command_namespace: 'Api::V1'
+  )
+rescue SimpleCommandDispatcher::Errors::InvalidClassConstantError => e
+  # Command class doesn't exist
+  puts "Command not found: #{e.message}"
+rescue SimpleCommandDispatcher::Errors::RequiredClassMethodMissingError => e
+  # Command class exists but doesn't have a .call method
+  puts "Invalid command: #{e.message}"
+rescue ArgumentError => e
+  # Invalid arguments (empty command, wrong parameter types, etc.)
+  puts "Invalid arguments: #{e.message}"
 end
 ```
 
-## Installation
+## Configuration
 
-Add this line to your application's Gemfile:
+The gem can be configured in an initializer:
 
 ```ruby
-gem 'simple_command_dispatcher'
+# config/initializers/simple_command_dispatcher.rb
+SimpleCommandDispatcher.configure do |config|
+  # Configuration options will be added in future versions
+end
 ```
 
-And then execute:
+## Migration from v3.x
 
-    $ bundle
+If you're upgrading from v3.x, here are the key changes:
 
-Or install it yourself as:
+### Breaking Changes
 
-    $ gem install simple_command_dispatcher
+1. **Method signature changed to keyword arguments:**
 
-## Usage
+   ```ruby
+   # v3.x (old)
+   SimpleCommandDispatcher.call(:CreateUser, 'Api::V1', { options }, params)
 
-See the example above.
+   # v4.x (new)
+   SimpleCommandDispatcher.call(
+     command: :CreateUser,
+     command_namespace: 'Api::V1',
+     request_params: params
+   )
+   ```
 
-## Development
+2. **Removed simple_command dependency:**
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+   - Commands no longer need to include SimpleCommand
+   - Commands must implement a `.call` class method
+   - Return value is whatever your command returns (no automatic Result object)
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+3. **Removed configuration options:**
+
+   - `allow_custom_commands` option removed (all commands are "custom" now)
+   - Camelization options removed (always enabled)
+
+4. **Namespace changes:**
+   - Error classes: `SimpleCommand::Dispatcher::Errors::*` → `SimpleCommandDispatcher::Errors::*`
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/gangelo/simple_command_dispatcher. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
-   [simple-command]: <https://rubygems.org/gems/simple_command>
-   [rails-api]: <https://rubygems.org/gems/rails-api>
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

data/Rakefile

@@ -2,19 +2,11 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
-require 'yard'
 
 # Rspec
 RSpec::Core::RakeTask.new(:spec)
 #task default: :spec
 
-# Yard
-YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb']
-  t.options = ['--no-cache', '--protected', '--private']
-  t.stats_options = ['--list-undoc']
-end
-
 # Load our custom rake tasks.
 Gem.find_files('tasks/**/*.rake').each { |path| import path }
 

data/lib/core_ext/kernel.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kernel
+  # Returns the eigenclass (singleton class) of the current object.
+  # This allows classes to reference their own class-level methods and variables.
+  #
+  # @return [Class] the eigenclass of the current object
+  #
+  # @example
+  #   class MyClass
+  #     def self.test
+  #       eigenclass
+  #     end
+  #   end
+  #   MyClass.test # => #<Class:MyClass>
+  #
+  def eigenclass
+    class << self
+      self
+    end
+  end
+end