cmdx 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2d77bd913e65961bafa2851e2148df1daed63bd7047f512f53f10b9ec07b700
-  data.tar.gz: 7d86f82f6334bb4538fdbbaeafa60185de6cd55535e192832ccb8c40164996dd
+  metadata.gz: 3bd1613d4572cca134192d5c80bf3016b278b42a9a002d13fba66d2871da92fb
+  data.tar.gz: 1a174bc8b62bf3402e1e464b8252cdcd589731f8e81141723b8dbf3cf97f9f1b
 SHA512:
-  metadata.gz: 4802141926139cf972a9869884fe59cddfca218a6ac8a54791e4a575ecef9f9b59039a71147097e5758e6171ef600c2d005110fc84bc27e5dd26f4930541b32d
-  data.tar.gz: b9eb23fd437ffc81ea9441273bf5602220167368af96d2190e9f2623d33eee7cf48af8c9fbfa947f802db0d378eb93f9661de04d8477759f312bf7bb0c9c1054
+  metadata.gz: df70552dbf814fddff62cb3e1d593edf6bf5c33087d84154f36c794d430ee156b986998651383fa15b3b08e4d14d198d69020bb0dec7a13ffab43c75b1c57b02
+  data.tar.gz: 03ad35b1f6007e1afa3c41f3b63d44784566e78b9eb9b7f25f301d81165753af14b06bb8a6cfd67ea7e5bce02a03c311c338f61538d9d981d7de58d7f2b36f8f

data/.cursor/prompts/rspec.md

@@ -0,0 +1,20 @@
+Add tests for the file in context.
+- Expectations should be concise, non-repetitive, and realistic (how it would be used in the real world)
+- Follow best practices and implementation
+- Update any pre-existing specs to match stated rules
+- New tests should be consistent with current `spec/cmdx` specs
+- Use custom matchers available within `lib/cmdx/rspec`
+- Use task helpers available within `spec/support/helpers`
+- Use stubs to return predefined values for specific methods. Isolate the unit being tested, but avoid over-mocking; test real behavior when possible. (mocks should be used only when necessary)
+- Ensure each test is independent; avoid shared state between tests.
+- Use let and let! to define test data, ensuring minimal and necessary setup.
+- Context block descriptions should start with the following words: `when`, `with`, `without`
+- Organize tests logically using describe for classes/modules and context for different scenarios.
+- Use subject to define the object under test when appropriate to avoid repetition.
+- Ensure test file paths mirror the structure of the files being tested, but within the spec directory (e.g., lib/cmdx/task.rb → spec/cmdx/task_spec.rb).
+- Use clear and descriptive names for describe, context, and it blocks.
+- Prefer the expect syntax for assertions to improve readability.
+- Keep test code concise; avoid unnecessary complexity or duplication.
+- Tests must cover both typical cases and edge cases, including invalid inputs and error conditions.
+- Consider all possible scenarios for each method or behavior and ensure they are tested.
+- Verify all specs are passing

data/.cursor/prompts/yardoc.md

@@ -0,0 +1,8 @@
+Add yardoc to the file in context.
+- Do NOT include `CMDx` module level docs
+- Module level docs description should NOT include `@example`
+- Method level docs should include `@example`, `@return`, `@raise`
+- Examples should be concise and realistic
+- Follow best practices and implementation
+- Update any pre-existing docs to match stated rules
+- New documentation should be consistent with current `lib/cmdx` documentation

data/.rubocop.yml

@@ -62,6 +62,8 @@ RSpec/SpecFilePathFormat:
     CMDx: cmdx
 RSpec/StubbedMock:
   Enabled: false
+RSpec/SubjectStub:
+  Enabled: false
 RSpec/VerifiedDoubles:
   Enabled: false
 RSpec/VerifiedDoubleReference:

data/CHANGELOG.md

@@ -8,11 +8,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [TODO]
 
 - Add table and pretty_table log formatters
-- Add method and proc style validations
-- Refactor parameter modules and classes for more robust usages
+- Refactor all `docs`
 
 ## [Unreleased]
 
+### Added
+- Added `CoercionRegistry` class for managing parameter coercions with support for custom type registration
+- Added `ValidatorRegistry` class for managing parameter validators with support for custom validator registration
+- Added `CallbackRegistry` class to take uninstantiated callback classes
+- Added `Validator` and `Coercion` classes to build their respective handlers
+
+### Changed
+- Moved `Task::CALLBACKS` constant to `CallbackRegistry::TYPES`
+- Updated `ParameterRegistry` class to not inherit from `Hash`
+- Updated `MiddlewareRegistry` class to not inherit from `Hash`
+- Updated `CallbackRegistry` class to not inherit from `Hash`
+
+### Removed
+- Removed task `register` class method
+- Removed `Custom` validator since users can create and register a custom one
+
 ## [1.0.1] - 2025-07-07
 
 ### Added

data/README.md

@@ -31,7 +31,7 @@ Or install it yourself as:
 ```ruby
 # Setup task
 class SendWelcomeEmailTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 5
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 5
 
   on_success :track_email_delivery!
 

data/docs/basics/call.md

@@ -103,7 +103,7 @@ task.context.notify_customer #=> true
 task.result.state            #=> "initialized"
 
 # Manual execution
-task.perform
+task.process
 task.result.success?         #=> true/false
 ```
 
@@ -113,7 +113,7 @@ task.result.success?         #=> true/false
 |----------|----------|----------|
 | `TaskClass.call(...)` | Standard execution | Simple, handles full lifecycle |
 | `TaskClass.call!(...)` | Exception-based flow | Automatic fault raising |
-| `TaskClass.new(...).perform` | Advanced scenarios | Full control, testing flexibility |
+| `TaskClass.new(...).process` | Advanced scenarios | Full control, testing flexibility |
 
 > [!NOTE]
 > Direct instantiation gives you access to the task instance before and after execution, but you must call the execution method manually.

data/docs/basics/chain.md

@@ -195,7 +195,7 @@ The `CMDx::Middlewares::Correlate` middleware automatically manages correlation
 ```ruby
 class ProcessOrderTask < CMDx::Task
   # Apply correlate middleware globally or per-task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Correlation is automatically managed

data/docs/callbacks.md

@@ -79,9 +79,7 @@ end
 
 ## Callback Classes
 
-For complex callback logic or reusable patterns, you can create Callback classes similar to Middleware classes. Callback classes inherit from `CMDx::Callback` and implement the `call(task, callback_type)` method.
-
-### Creating Callback Classes
+For complex callback logic or reusable patterns, you can create Callback classes similar to Middleware classes. Callback classes inherit from `CMDx::Callback` and implement the `call(task, type)` method.
 
 ```ruby
 class NotificationCallback < CMDx::Callback
@@ -89,8 +87,8 @@ class NotificationCallback < CMDx::Callback
     @channels = Array(channels)
   end
 
-  def call(task, callback_type)
-    return unless callback_type == :on_success
+  def call(task, type)
+    return unless type == :on_success
 
     @channels.each do |channel|
       NotificationService.send(channel, "Task #{task.class.name} completed")
@@ -99,37 +97,6 @@ class NotificationCallback < CMDx::Callback
 end
 ```
 
-### Registering Callback Classes
-
-Callback classes can be registered using the `register` class method (recommended) or by directly calling the CallbackRegistry:
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-  # Recommended: Use the register class method
-  register :before_execution, LoggingCallback.new(:debug)
-  register :on_success, NotificationCallback.new([:email, :slack])
-  register :on_failure, :alert_admin, if: :critical?
-
-  # Alternative: Direct CallbackRegistry access (less common)
-  # cmd_callbacks.register(:after_execution, CleanupCallback.new)
-
-  # Traditional callback definitions still work alongside Callback classes
-  before_validation :validate_order_data
-  on_success :update_metrics
-
-  def call
-    context.order = Order.find(order_id)
-    context.order.process!
-  end
-
-  private
-
-  def critical?
-    context.order.value > 10_000
-  end
-end
-```
-
 ## Available Callbacks
 
 ### Validation Callbacks

data/docs/configuration.md

@@ -10,6 +10,8 @@ CMDx provides a flexible configuration system that allows customization at both
   - [Configuration Options](#configuration-options)
   - [Global Middlewares](#global-middlewares)
   - [Global Callbacks](#global-callbacks)
+  - [Global Coercions](#global-coercions)
+  - [Global Validators](#global-validators)
 - [Task Settings](#task-settings)
   - [Available Task Settings](#available-task-settings)
   - [Workflow Configuration](#workflow-configuration)
@@ -21,7 +23,7 @@ CMDx provides a flexible configuration system that allows customization at both
 
 - **Hierarchy** - Global → Task Settings → Runtime (each level overrides previous)
 - **Global config** - Framework-wide defaults via `CMDx.configure`
-- **Task settings** - Class-level overrides using `task_settings!`
+- **Task settings** - Class-level overrides using `cmd_settings!`
 - **Key options** - `task_halt`, `workflow_halt`, `logger`, `middlewares`, `callbacks`
 - **Generator** - Use `rails g cmdx:install` to create configuration file
 - **Inheritance** - Settings are inherited from parent classes
@@ -31,7 +33,7 @@ CMDx provides a flexible configuration system that allows customization at both
 CMDx follows a three-tier configuration hierarchy:
 
 1. **Global Configuration**: Framework-wide defaults
-2. **Task Settings**: Class-level overrides via `task_settings!`
+2. **Task Settings**: Class-level overrides via `cmd_settings!`
 3. **Runtime Parameters**: Instance-specific overrides during execution
 
 > [!IMPORTANT]
@@ -56,6 +58,8 @@ This creates `config/initializers/cmdx.rb` with default settings.
 | `logger`      | Logger                | Line formatter | Logger instance for task execution logging |
 | `middlewares` | MiddlewareRegistry    | Empty registry | Global middleware registry applied to all tasks |
 | `callbacks`   | CallbackRegistry      | Empty registry | Global callback registry applied to all tasks |
+| `coercions`   | CoercionRegistry      | Built-in coercions | Global coercion registry for custom parameter types |
+| `validators`  | ValidatorRegistry     | Built-in validators | Global validator registry for parameter validation |
 
 ### Global Middlewares
 
@@ -82,30 +86,70 @@ Configure callbacks that automatically apply to all tasks in your application:
 CMDx.configure do |config|
   # Add method callbacks
   config.callbacks.register :before_execution, :log_task_start
-  config.callbacks.register :after_execution, :log_task_end
 
   # Add callback instances
   config.callbacks.register :on_success, NotificationCallback.new([:slack])
-  config.callbacks.register :on_failure, AlertCallback.new(severity: :critical)
 
   # Add conditional callbacks
   config.callbacks.register :on_failure, :page_admin, if: :production?
-  config.callbacks.register :before_validation, :skip_validation, unless: :validate_params?
 
   # Add proc callbacks
-  config.callbacks.register :on_complete, proc { |task, callback_type|
+  config.callbacks.register :on_complete, proc { |task, type|
     Metrics.increment("task.#{task.class.name.underscore}.completed")
   }
 end
 ```
 
+### Global Coercions
+
+Configure custom coercions that automatically apply to all tasks in your application:
+
+```ruby
+CMDx.configure do |config|
+  # Add custom coercion classes
+  config.coercions.register :money, MoneyCoercion
+
+  # Add complex coercions with options support
+  config.coercions.register :tags, proc { |value, options|
+    separator = options[:separator] || ','
+    max_tags = options[:max_tags] || 10
+
+    tags = value.to_s.split(separator).map(&:strip).reject(&:empty?)
+    tags = tags.first(max_tags) if max_tags
+    tags.uniq
+  }
+end
+```
+
+### Global Validators
+
+Configure validators that automatically apply to all tasks in your application:
+
+```ruby
+CMDx.configure do |config|
+  # Add validator classes
+  config.validators.register :email, EmailValidator
+
+  # Add complex validators with options support
+  config.validators.register :phone, proc { |value, options|
+    country = options.dig(:phone, :country) || "US"
+    case country
+    when "US"
+      value.match?(/\A\d{3}-\d{3}-\d{4}\z/)
+    else
+      value.match?(/\A\+?\d{10,15}\z/)
+    end
+  }
+end
+```
+
 ## Task Settings
 
-Override global configuration for specific tasks or workflows using `task_settings!`:
+Override global configuration for specific tasks or workflows using `cmd_settings!`:
 
 ```ruby
 class ProcessPaymentTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     task_halt: ["failed"],                       # Only halt on failures
     tags: ["payments", "critical"],              # Add logging tags
     logger: Rails.logger,                        # Use Rails logger
@@ -137,7 +181,7 @@ Configure halt behavior for workflows:
 ```ruby
 class OrderProcessingWorkflow < CMDx::Workflow
   # Strict workflow - halt on any failure
-  task_settings!(workflow_halt: ["failed", "skipped"])
+  cmd_settings!(workflow_halt: ["failed", "skipped"])
 
   process ValidateOrderTask
   process ChargePaymentTask
@@ -155,14 +199,16 @@ CMDx.configuration.logger      #=> <Logger instance>
 CMDx.configuration.task_halt   #=> "failed"
 CMDx.configuration.middlewares #=> <MiddlewareRegistry instance>
 CMDx.configuration.callbacks   #=> <CallbackRegistry instance>
+CMDx.configuration.coercions   #=> <CoercionRegistry instance>
+CMDx.configuration.validators  #=> <ValidatorRegistry instance>
 
 # Task-specific settings
 class AnalyzeDataTask < CMDx::Task
-  task_settings!(tags: ["analytics"])
+  cmd_settings!(tags: ["analytics"])
 
   def call
-    tags = task_setting(:tags)               # Gets ["analytics"]
-    halt_statuses = task_setting(:task_halt) # Gets global default
+    tags = cmd_setting(:tags)               # Gets ["analytics"]
+    halt_statuses = cmd_setting(:task_halt) # Gets global default
   end
 end
 ```

data/docs/interruptions/exceptions.md

@@ -187,7 +187,7 @@ CMDx faults have special handling in both call methods:
 ```ruby
 class ProcessOrderWithHaltTask < CMDx::Task
   # Configure to halt on failures
-  task_settings!(task_halt: [CMDx::Result::FAILED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED])
 
   def call
     fail!(reason: "This is a controlled failure")

data/docs/interruptions/faults.md

@@ -213,7 +213,7 @@ Control which statuses raise exceptions using the `task_halt` setting:
 ```ruby
 class ProcessUserOrderTask < CMDx::Task
   # Only failed tasks raise exceptions on call!
-  task_settings!(task_halt: [CMDx::Result::FAILED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED])
 
   def call
     skip!(reason: "Order already processed") if already_processed?
@@ -223,7 +223,7 @@ end
 
 class ValidateUserDataTask < CMDx::Task
   # Both failed and skipped tasks raise exceptions
-  task_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
   def call
     skip!(reason: "Validation not required") if skip_validation?

data/docs/logging.md

@@ -27,7 +27,7 @@ CMDx provides comprehensive automatic logging for task execution with structured
 
 - **Automatic logging** - All task results logged after completion with structured data
 - **8 formatters** - Standard (Line, Json, KeyValue, Logstash, Raw) and Stylized (Pretty variants)
-- **Configuration** - Global via `CMDx.configure` or task-specific via `task_settings!`
+- **Configuration** - Global via `CMDx.configure` or task-specific via `cmd_settings!`
 - **Severity mapping** - Success=INFO, Skipped=WARN, Failed=ERROR
 - **Rich metadata** - Includes runtime, chain_id, status, context, and failure chains
 - **Manual logging** - Access `logger` within tasks for custom messages
@@ -93,7 +93,7 @@ Override logging settings for individual tasks:
 
 ```ruby
 class SendEmailTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Rails.logger,
     log_formatter: CMDx::LogFormatters::Json.new,
     log_level: Logger::WARN
@@ -106,7 +106,7 @@ end
 
 # Base class with shared logging configuration
 class ApplicationTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Logger.new("log/tasks.log"),
     log_formatter: CMDx::LogFormatters::Logstash.new,
     log_level: Logger::INFO
@@ -179,7 +179,7 @@ class SlackLogFormatter
 end
 
 class SendNotificationTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Logger.new("log/notifications.log", formatter: SlackLogFormatter.new)
   )
 end