cmdx 1.0.1 → 1.1.0

data/docs/middlewares.md

@@ -32,9 +32,9 @@ Declare middleware using the `use` method in your task classes:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use AuthenticationMiddleware
-  use LoggingMiddleware, level: :info
-  use CachingMiddleware, ttl: 300
+  use :middleware, AuthenticationMiddleware
+  use :middleware, LoggingMiddleware, level: :info
+  use :middleware, CachingMiddleware, ttl: 300
 
   def call
     context.order = Order.find(order_id)
@@ -71,7 +71,7 @@ class AuditMiddleware < CMDx::Middleware
 end
 
 class ProcessOrderTask < CMDx::Task
-  use AuditMiddleware, action: 'process', resource_type: 'Order'
+  use :middleware, AuditMiddleware, action: 'process', resource_type: 'Order'
 
   def call
     context.order = Order.find(order_id)
@@ -86,7 +86,7 @@ Pre-configured middleware instances for complex initialization:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use LoggingMiddleware.new(
+  use :middleware, LoggingMiddleware.new(
     level: :debug,
     formatter: JSON::JSONFormatter.new,
     tags: ['order', 'payment']
@@ -104,7 +104,7 @@ Inline middleware for simple cases:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use proc { |task, callable|
+  use :middleware, proc { |task, callable|
     start_time = Time.now
     result = callable.call(task)
     duration = Time.now - start_time
@@ -125,9 +125,9 @@ Middleware executes in nested fashion - first declared wraps all others:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-  use TimingMiddleware         # 1st: outermost
-  use AuthenticationMiddleware # 2nd: middle
-  use ValidationMiddleware     # 3rd: innermost
+  use :middleware, TimingMiddleware         # 1st: outermost
+  use :middleware, AuthenticationMiddleware # 2nd: middle
+  use :middleware, ValidationMiddleware     # 3rd: innermost
 
   def call
     # Core logic executes last
@@ -173,7 +173,7 @@ class RateLimitMiddleware < CMDx::Middleware
 end
 
 class SendEmailTask < CMDx::Task
-  use RateLimitMiddleware, limit: 50, window: 1.hour
+  use :middleware, RateLimitMiddleware, limit: 50, window: 1.hour
 
   def call
     # Only executes if rate limit check passes
@@ -192,14 +192,14 @@ Middleware is inherited from parent classes, enabling application-wide patterns:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use RequestIdMiddleware      # All tasks get request tracking
-  use PerformanceMiddleware    # All tasks get performance monitoring
-  use ErrorReportingMiddleware # All tasks get error reporting
+  use :middleware, RequestIdMiddleware      # All tasks get request tracking
+  use :middleware, PerformanceMiddleware    # All tasks get performance monitoring
+  use :middleware, ErrorReportingMiddleware # All tasks get error reporting
 end
 
 class ProcessOrderTask < ApplicationTask
-  use AuthenticationMiddleware  # Specific to order processing
-  use OrderValidationMiddleware # Domain-specific validation
+  use :middleware, AuthenticationMiddleware  # Specific to order processing
+  use :middleware, OrderValidationMiddleware # Domain-specific validation
 
   def call
     # Inherits all ApplicationTask middleware plus order-specific ones
@@ -220,7 +220,7 @@ Enforces execution time limits with support for static and dynamic timeout value
 
 ```ruby
 class ProcessLargeReportTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 300 # 5 minutes
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 300 # 5 minutes
 
   def call
     # Long-running report generation
@@ -229,7 +229,7 @@ end
 
 # Default timeout (3 seconds when no value specified)
 class QuickValidationTask < CMDx::Task
-  use CMDx::Middlewares::Timeout # Uses 3 seconds default
+  use :middleware, CMDx::Middlewares::Timeout # Uses 3 seconds default
 
   def call
     # Fast validation logic
@@ -244,7 +244,7 @@ The middleware supports dynamic timeout calculation using method names, procs, a
 ```ruby
 # Method-based timeout calculation
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :calculate_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :calculate_timeout
 
   def call
     # Task execution with dynamic timeout
@@ -265,7 +265,7 @@ end
 
 # Proc-based timeout for inline calculation
 class ProcessWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: -> {
+  use :middleware, CMDx::Middlewares::Timeout, seconds: -> {
     context.workflow_size > 100 ? 120 : 60
   }
 
@@ -277,7 +277,7 @@ end
 
 # Context-aware timeout calculation
 class GenerateReportTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :report_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :report_timeout
 
   def call
     context.report = ReportGenerator.create(report_params)
@@ -309,12 +309,12 @@ The middleware follows this precedence for determining timeout values:
 ```ruby
 # Static timeout - highest precedence when specified
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 45 # Always 45 seconds
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 45 # Always 45 seconds
 end
 
 # Method-based timeout - calls task method
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
 
   private
   def dynamic_timeout
@@ -324,7 +324,7 @@ end
 
 # Default fallback when method returns nil
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: :might_return_nil
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :might_return_nil
 
   private
   def might_return_nil
@@ -340,7 +340,7 @@ Apply timeout middleware conditionally based on environment or task state:
 ```ruby
 # Environment-based conditional timeout
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: 60,
       unless: -> { Rails.env.development? }
 
@@ -353,7 +353,7 @@ end
 
 # Context-based conditional timeout
 class SendEmailTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: 30,
       if: :timeout_enabled?
 
@@ -370,7 +370,7 @@ end
 
 # Combined dynamic timeout with conditions
 class ProcessComplexOrderTask < CMDx::Task
-  use CMDx::Middlewares::Timeout,
+  use :middleware, CMDx::Middlewares::Timeout,
       seconds: :calculate_timeout,
       unless: :skip_timeout?
 
@@ -399,11 +399,11 @@ Apply timeout middleware globally with inheritance:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 60 # Default 60 seconds for all tasks
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 60 # Default 60 seconds for all tasks
 end
 
 class QuickTask < ApplicationTask
-  use CMDx::Middlewares::Timeout, seconds: 15 # Override with 15 seconds
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 15 # Override with 15 seconds
 
   def call
     # Fast operation with shorter timeout
@@ -411,7 +411,7 @@ class QuickTask < ApplicationTask
 end
 
 class LongRunningTask < ApplicationTask
-  use CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
+  use :middleware, CMDx::Middlewares::Timeout, seconds: :dynamic_timeout
 
   def call
     # Long operation with dynamic timeout
@@ -437,7 +437,7 @@ Manages correlation IDs for request tracing across task boundaries. This middlew
 
 ```ruby
 class ProcessApiRequestTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Correlation ID is automatically managed
@@ -456,19 +456,19 @@ The middleware follows a hierarchical precedence system for determining correlat
 
 # 1a. Static string ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: "fixed-correlation-123"
+  use :middleware, CMDx::Middlewares::Correlate, id: "fixed-correlation-123"
 end
 ProcessOrderTask.call # Always uses "fixed-correlation-123"
 
 # 1b. Dynamic proc/lambda ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{rand(1000)}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{rand(1000)}" }
 end
 ProcessOrderTask.call(order_id: 456) # Uses "order-456-847" (random number varies)
 
 # 1c. Method-based ID
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :correlation_method
+  use :middleware, CMDx::Middlewares::Correlate, id: :correlation_method
 
   private
 
@@ -498,7 +498,7 @@ Set fixed or dynamic correlation IDs for specific tasks or workflows using strin
 ```ruby
 # Static string correlation ID
 class ProcessPaymentTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: "payment-processing"
+  use :middleware, CMDx::Middlewares::Correlate, id: "payment-processing"
 
   def call
     # Always uses "payment-processing" as correlation ID
@@ -509,7 +509,7 @@ end
 
 # Dynamic correlation ID using proc/lambda
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{Time.now.to_i}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "order-#{order_id}-#{Time.now.to_i}" }
 
   def call
     # Dynamic correlation ID based on order and timestamp
@@ -521,7 +521,7 @@ end
 
 # Method-based correlation ID
 class ProcessApiRequestTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :generate_correlation_id
+  use :middleware, CMDx::Middlewares::Correlate, id: :generate_correlation_id
 
   def call
     # Uses correlation ID from generate_correlation_id method
@@ -537,7 +537,7 @@ end
 
 # Symbol fallback when method doesn't exist
 class ProcessWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: :workflow_processing
+  use :middleware, CMDx::Middlewares::Correlate, id: :workflow_processing
 
   def call
     # Uses :workflow_processing as correlation ID (symbol as-is)
@@ -554,7 +554,7 @@ Apply correlation middleware conditionally based on environment or task state:
 ```ruby
 class ProcessOrderTask < CMDx::Task
   # Only apply correlation in production environments
-  use CMDx::Middlewares::Correlate, unless: -> { Rails.env.development? }
+  use :middleware, CMDx::Middlewares::Correlate, unless: -> { Rails.env.development? }
 
   def call
     context.order = Order.find(order_id)
@@ -564,7 +564,7 @@ end
 
 class SendEmailTask < CMDx::Task
   # Apply correlation only when tracing is enabled
-  use CMDx::Middlewares::Correlate, if: :tracing_enabled?
+  use :middleware, CMDx::Middlewares::Correlate, if: :tracing_enabled?
 
   def call
     EmailService.deliver(email_params)
@@ -584,7 +584,7 @@ Use correlation blocks to establish correlation contexts for groups of related t
 
 ```ruby
 class ProcessOrderWorkflowTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Establish correlation context for entire workflow
@@ -604,7 +604,7 @@ Apply correlation middleware globally to all tasks:
 
 ```ruby
 class ApplicationTask < CMDx::Task
-  use CMDx::Middlewares::Correlate # All tasks get correlation management
+  use :middleware, CMDx::Middlewares::Correlate # All tasks get correlation management
 end
 
 class ProcessOrderTask < ApplicationTask
@@ -648,7 +648,7 @@ class ApiController < ApplicationController
 end
 
 class ProcessOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Inherits correlation ID from controller thread context
@@ -661,7 +661,7 @@ end
 
 # Alternative: Task-specific correlation for API endpoints
 class ProcessApiOrderTask < CMDx::Task
-  use CMDx::Middlewares::Correlate, id: -> { "api-order-#{context.request_id}" }
+  use :middleware, CMDx::Middlewares::Correlate, id: -> { "api-order-#{context.request_id}" }
 
   def call
     # Uses correlation ID specific to this API request

data/docs/parameters/coercions.md

@@ -20,11 +20,10 @@ string-to-integer conversion to complex JSON parsing and custom type handling.
   - [Numeric Coercion](#numeric-coercion)
 - [Coercion with Nested Parameters](#coercion-with-nested-parameters)
 - [Coercion Error Handling](#coercion-error-handling)
-  - [Single Type Coercion Errors](#single-type-coercion-errors)
-  - [Multiple Type Coercion Errors](#multiple-type-coercion-errors)
 - [Custom Coercion Options](#custom-coercion-options)
   - [Date/Time Format Options](#datetime-format-options)
   - [BigDecimal Precision Options](#bigdecimal-precision-options)
+- [Custom Coercions](#custom-coercions)
 
 ## TLDR
 
@@ -33,6 +32,7 @@ string-to-integer conversion to complex JSON parsing and custom type handling.
 - **No conversion** - Default `:virtual` type returns values unchanged
 - **Before validation** - Coercion happens automatically before parameter validation
 - **Rich types** - Supports all Ruby built-ins plus JSON parsing for arrays/hashes
+- **Custom coercions** - Register custom coercion types
 
 ## Coercion Fundamentals
 
@@ -316,13 +316,11 @@ end
 > [!WARNING]
 > When coercion fails, CMDx provides detailed error information including the parameter name, attempted types, and specific failure reasons.
 
-### Single Type Coercion Errors
-
 ```ruby
 class ValidateUserProfileTask < CMDx::Task
 
   required :age, type: :integer
-  required :salary, type: :float
+  required :salary, type: [:float, :big_decimal]
   required :is_employed, type: :boolean
 
   def call
@@ -341,46 +339,15 @@ result = ValidateUserProfileTask.call(
 result.failed?  #=> true
 result.metadata
 #=> {
-#     reason: "age could not coerce into an integer. salary could not coerce into a float. is_employed could not coerce into a boolean.",
+#     reason: "age could not coerce into an integer. could not coerce into one of: float, big_decimal. is_employed could not coerce into a boolean.",
 #     messages: {
 #       age: ["could not coerce into an integer"],
-#       salary: ["could not coerce into a float"],
+#       salary: ["could not coerce into one of: float, big_decimal"],
 #       is_employed: ["could not coerce into a boolean"]
 #     }
 #   }
 ```
 
-### Multiple Type Coercion Errors
-
-```ruby
-class ProcessFlexibleDataTask < CMDx::Task
-
-  required :order_value, type: [:float, :integer]
-  required :customer_data, type: [:hash, :array, :string]
-
-  def call
-    # Task logic here
-  end
-
-end
-
-# Failed coercion with multiple types
-result = ProcessFlexibleDataTask.call(
-  order_value: "invalid-number",
-  customer_data: Object.new
-)
-
-result.failed?  #=> true
-result.metadata
-#=> {
-#     reason: "order_value could not coerce into one of: float, integer. customer_data could not coerce into one of: hash, array, string.",
-#     messages: {
-#       order_value: ["could not coerce into one of: float, integer"],
-#       customer_data: ["could not coerce into one of: hash, array, string"]
-#     }
-#   }
-```
-
 ## Custom Coercion Options
 
 ### Date/Time Format Options
@@ -428,6 +395,50 @@ class CalculatePricingTask < CMDx::Task
 end
 ```
 
+## Custom Coercions
+
+> [!NOTE]
+> CMDx allows you to register custom coercions for domain-specific types that aren't covered by the built-in coercions. Custom coercions can be registered globally or per-task basis.
+
+```ruby
+module MoneyCoercion
+  module_function
+
+  def call(value, options = {})
+    return value if value.is_a?(BigDecimal)
+
+    # Handle string amounts like "$123.45"
+    if value.is_a?(String)
+      clean_value = value.gsub(/[$,]/, '')
+      BigDecimal(clean_value)
+    else
+      BigDecimal(value.to_s)
+    end
+  end
+end
+
+CMDx.configure do |config|
+  config.coercions.register(:money, MoneyCoercion)
+  config.coercions.register(:slug, proc do |value|
+    value.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/-+/, '-').strip('-')
+  end)
+end
+
+# Now use in any task
+class ProcessProductTask < CMDx::Task
+  required :cost, type: :money
+  required :slug, type: :slug
+
+  def call
+    cost #=> 123.45
+    slug #=> "my-blog-post-title" (URL-friendly)
+  end
+end
+```
+
+> [!TIP]
+> Custom coercions should be idempotent - calling them multiple times with the same input should produce the same result. This ensures predictable behavior when coercions are applied during parameter processing.
+
 ---
 
 - **Prev:** [Parameters - Namespacing](namespacing.md)

data/docs/parameters/defaults.md

@@ -180,7 +180,7 @@ class ValidateOrderPriorityTask < CMDx::Task
 
   # Custom validation with default
   optional :approval_code, type: :string, default: :generate_approval_code,
-    custom: { validator: ApprovalCodeValidator }
+    presence: true
 
   def call
     priority           #=> "standard" (validated against inclusion list)

data/docs/parameters/validations.md

@@ -12,7 +12,6 @@ Parameter values can be validated using built-in validators or custom validation
 - [Inclusion](#inclusion)
 - [Length](#length)
 - [Numeric](#numeric)
-- [Custom](#custom)
 - [Validation Results](#validation-results)
 
 ## TLDR
@@ -21,7 +20,6 @@ Parameter values can be validated using built-in validators or custom validation
 - **Common options** - All support `:allow_nil`, `:if`, `:unless`, `:message`
 - **Usage** - Add to parameter definitions: `required :email, presence: true, format: { with: /@/ }`
 - **Conditional** - Use `:if` and `:unless` for conditional validation
-- **Custom validators** - Use `custom: { validator: CustomValidator }` for complex logic
 
 ## Common Options
 
@@ -247,43 +245,6 @@ end
 | `:is_message`         | "must be %{is}" |
 | `:is_not_message`     | "must not be %{is_not}" |
 
-## Custom
-
-Validates using custom logic. Accepts any callable object (class, proc, lambda) implementing a `call` method that returns truthy for valid values.
-
-```ruby
-class EmailDomainValidator
-  def self.call(value, options)
-    allowed_domains = options.dig(:custom, :allowed_domains) || ['example.com']
-    domain = value.split('@').last
-    allowed_domains.include?(domain)
-  end
-end
-
-class CreateAccountTask < CMDx::Task
-  required :work_email, custom: {
-    validator: EmailDomainValidator,
-    allowed_domains: ['company.com', 'partner.org'],
-    message: "must be from an approved domain"
-  }
-
-  required :age, custom: {
-    validator: ->(value, options) { value.between?(18, 120) },
-    message: "must be a valid age"
-  }
-
-  def call
-    create_user_account
-  end
-end
-```
-
-**Options:**
-
-| Option       | Description |
-| ------------ | ----------- |
-| `:validator` | Callable object returning true/false. Receives value and options as parameters |
-
 ## Validation Results
 
 When validation fails, tasks enter a failed state with detailed error information:

data/docs/testing.md

@@ -24,7 +24,7 @@ CMDx provides a comprehensive suite of custom RSpec matchers designed for expres
 ## TLDR
 
 - **Custom matchers** - 40+ specialized RSpec matchers for testing CMDx tasks and results
-- **Setup** - Require `cmdx/rspec/result_matchers` and `cmdx/rspec/task_matchers`
+- **Setup** - Require `cmdx/rspec/matchers`
 - **Result matchers** - `be_successful_task`, `be_failed_task`, `be_skipped_task` with chainable metadata
 - **Task matchers** - Parameter validation, lifecycle, exception handling, and configuration testing
 - **Composable** - Chain matchers for complex validation scenarios
@@ -35,18 +35,17 @@ CMDx provides a comprehensive suite of custom RSpec matchers designed for expres
 To use CMDx's custom matchers in an external RSpec-based project update your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
 
 ```ruby
-require "cmdx/rspec/result_matchers"
-require "cmdx/rspec/task_matchers"
+require "cmdx/rspec/matchers"
 ```
 
 ## Matcher Organization
 
 CMDx matchers are organized into two primary files with comprehensive YARD documentation:
 
-| File | Purpose | Matcher Count |
-|------|---------|---------------|
-| `result_matchers.rb` | Task execution outcomes and side effects | 25+ matchers |
-| `task_matchers.rb` | Task behavior, validation, and lifecycle | 15+ matchers |
+| Purpose | Matcher Count |
+|---------|---------------|
+| Task execution outcomes and side effects | 15+ matchers |
+| Task behavior, validation, and lifecycle | 5+ matchers |
 
 All matchers include:
 - Complete parameter descriptions
@@ -437,15 +436,15 @@ expect(SimpleTask).not_to have_middleware(ComplexMiddleware)
 
 ```ruby
 # Test setting presence
-expect(ConfiguredTask).to have_task_setting(:timeout)
-expect(CustomTask).to have_task_setting(:priority)
+expect(ConfiguredTask).to have_cmd_setting(:timeout)
+expect(CustomTask).to have_cmd_setting(:priority)
 
 # Test setting with specific value
-expect(TimedTask).to have_task_setting(:timeout, 30)
-expect(PriorityTask).to have_task_setting(:priority, "high")
+expect(TimedTask).to have_cmd_setting(:timeout, 30)
+expect(PriorityTask).to have_cmd_setting(:priority, "high")
 
 # Negated usage
-expect(SimpleTask).not_to have_task_setting(:complex_setting)
+expect(SimpleTask).not_to have_cmd_setting(:complex_setting)
 ```
 
 ## Composable Testing

data/docs/workflows.md

@@ -153,12 +153,12 @@ end
 
 ### Class-Level Configuration
 
-Configure halt behavior for the entire workflow using `task_settings!`:
+Configure halt behavior for the entire workflow using `cmd_settings!`:
 
 ```ruby
 class CriticalDataProcessingWorkflow < CMDx::Workflow
   # Halt on both failed and skipped results
-  task_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  cmd_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
   process LoadCriticalDataTask
   process ValidateCriticalDataTask
@@ -166,7 +166,7 @@ end
 
 class OptionalDataProcessingWorkflow < CMDx::Workflow
   # Never halt, always continue
-  task_settings!(workflow_halt: [])
+  cmd_settings!(workflow_halt: [])
 
   process TryLoadDataTask
   process TryValidateDataTask
@@ -274,7 +274,7 @@ Workflows support all task settings and can be configured like regular tasks:
 ```ruby
 class PaymentProcessingWorkflow < CMDx::Workflow
   # Configure workflow-specific settings
-  task_settings!(
+  cmd_settings!(
     workflow_halt: [CMDx::Result::FAILED],
     log_level: :debug,
     tags: [:critical, :payment]