cmdx 0.5.0 → 1.0.0

data/lib/cmdx/core_ext/object.rb

@@ -2,10 +2,52 @@
 
 module CMDx
   module CoreExt
+    # Extensions to Object that provide CMDx-specific utility methods.
+    #
+    # ObjectExtensions adds safe method calling, conditional evaluation,
+    # and value yielding capabilities to all Ruby objects. These methods
+    # are prefixed with `__cmdx_` to avoid conflicts with existing methods.
+    #
+    # @example Safe method calling
+    #   object.__cmdx_try(:some_method)  # Returns nil if method doesn't exist
+    #   object.__cmdx_try(proc { expensive_calculation })  # Calls proc safely
+    #
+    # @example Conditional evaluation
+    #   object.__cmdx_eval(if: :valid?)       # True if object.valid? is true
+    #   object.__cmdx_eval(unless: :empty?)   # True unless object.empty? is true
+    #   object.__cmdx_eval(if: :valid?, unless: :processed?)  # Combined conditions
+    #
+    # @example Value yielding
+    #   object.__cmdx_yield(:name)           # Returns object.name if method exists, otherwise :name
+    #   object.__cmdx_yield(-> { compute })  # Executes lambda and returns result
+    #
+    # @see Task Tasks that use these object extensions
+    # @see Parameter Parameters that leverage object extensions
     module ObjectExtensions
 
+      # Store original respond_to? method before aliasing
       alias __cmdx_respond_to? respond_to?
 
+      # Safely attempt to call a method or execute a proc on an object.
+      #
+      # This method provides safe method calling with fallback behavior.
+      # It handles method calls, proc execution, and hash key access gracefully.
+      #
+      # @param key [Symbol, String, Proc] method name or callable to attempt
+      # @param args [Array] arguments to pass to the method/proc (passed via splat)
+      # @return [Object, nil] result of method call, proc execution, or nil if not possible
+      #
+      # @example Method calling
+      #   user.__cmdx_try(:name)              # => "John" or nil
+      #   user.__cmdx_try(:age, 25)           # => calls user.age(25) or nil
+      #
+      # @example Proc execution
+      #   user.__cmdx_try(-> { expensive_calc }) # => executes lambda
+      #   user.__cmdx_try(proc { |x| x * 2 }, 5) # => 10
+      #
+      # @example Hash access
+      #   hash = {name: "John"}
+      #   hash.__cmdx_try(:name)              # => "John"
       def __cmdx_try(key, ...)
         if key.is_a?(Proc)
           return instance_eval(&key) unless is_a?(Module) || key.inspect.include?("(lambda)")
@@ -18,6 +60,27 @@ module CMDx
         end
       end
 
+      # Evaluate conditional options for execution control.
+      #
+      # This method evaluates :if and :unless conditions to determine
+      # whether something should proceed. Used extensively in callbacks
+      # and conditional parameter processing.
+      #
+      # @param options [Hash] conditional options
+      # @option options [Symbol, Proc] :if condition that must be true
+      # @option options [Symbol, Proc] :unless condition that must be false
+      # @option options [Boolean] :default default value if no conditions (default: true)
+      # @return [Boolean] true if conditions are met
+      #
+      # @example Simple conditions
+      #   user.__cmdx_eval(if: :admin?)       # => true if user.admin? is true
+      #   user.__cmdx_eval(unless: :guest?)   # => true unless user.guest? is true
+      #
+      # @example Combined conditions
+      #   user.__cmdx_eval(if: :active?, unless: :banned?)  # => active AND not banned
+      #
+      # @example With procs
+      #   user.__cmdx_eval(if: -> { Time.now.monday? }) # => true if today is Monday
       def __cmdx_eval(options = {})
         if options[:if] && options[:unless]
           __cmdx_try(options[:if]) && !__cmdx_try(options[:unless])
@@ -30,6 +93,27 @@ module CMDx
         end
       end
 
+      # Yield a value by attempting to call it as a method or executing it.
+      #
+      # This method provides intelligent value resolution - if the key is
+      # a method name and the object responds to it, call the method.
+      # Otherwise, try to execute it as a proc or return the value as-is.
+      #
+      # @param key [Object] value to yield, method name, or callable
+      # @param args [Array] arguments to pass if calling method/proc (passed via splat)
+      # @return [Object] yielded value
+      #
+      # @example Method yielding
+      #   user.__cmdx_yield(:name)           # => calls user.name if method exists, otherwise returns :name
+      #   user.__cmdx_yield("email")         # => calls user.email if method exists, otherwise returns "email"
+      #
+      # @example Proc yielding
+      #   user.__cmdx_yield(-> { timestamp }) # => executes lambda
+      #   hash.__cmdx_yield({key: "value"})   # => tries hash access
+      #
+      # @example Direct values
+      #   user.__cmdx_yield(42)              # => 42
+      #   user.__cmdx_yield("literal")       # => "literal"
       def __cmdx_yield(key, ...)
         if key.is_a?(Symbol) || key.is_a?(String)
           return key unless respond_to?(key, true)
@@ -42,6 +126,26 @@ module CMDx
         end
       end
 
+      # Call an object if it responds to call, otherwise return itself.
+      #
+      # This method provides safe callable execution - if the object
+      # can be called (like a proc or lambda), call it with the given
+      # arguments. Otherwise, return the object unchanged.
+      #
+      # @param args [Array] arguments to pass to call method (passed via splat)
+      # @return [Object] result of calling or the object itself
+      #
+      # @example Callable objects
+      #   proc = -> { "Hello" }
+      #   proc.__cmdx_call                   # => "Hello"
+      #
+      # @example Non-callable objects
+      #   string = "Hello"
+      #   string.__cmdx_call                 # => "Hello"
+      #
+      # @example With arguments
+      #   adder = ->(a, b) { a + b }
+      #   adder.__cmdx_call(2, 3)           # => 5
       def __cmdx_call(...)
         return self unless respond_to?(:call)
 
@@ -52,4 +156,5 @@ module CMDx
   end
 end
 
+# Extend all objects with CMDx utility methods
 Object.include(CMDx::CoreExt::ObjectExtensions)

data/lib/cmdx/correlator.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # Thread-safe correlation ID management for tracking related operations across request boundaries.
+  #
+  # The Correlator provides a simple, thread-local storage mechanism for managing correlation
+  # identifiers throughout the execution lifecycle. It enables tracing related operations
+  # across different tasks, workflows, and service boundaries within the same execution context.
+  #
+  # Correlation IDs are automatically used by CMDx runs when available, providing seamless
+  # request tracking without requiring explicit parameter passing between tasks.
+  #
+  # ## Thread Safety
+  #
+  # All correlation operations are thread-local, ensuring that different threads maintain
+  # separate correlation contexts without interference. This is essential for concurrent
+  # request processing in multi-threaded applications.
+  #
+  # ## Integration with CMDx Runs
+  #
+  # When a new CMDx::Chain is created, it automatically uses the current thread's correlation
+  # ID as its chain identifier if available, falling back to UUID generation if none exists.
+  #
+  # @example Basic correlation usage
+  #   CMDx::Correlator.id = "req-12345"
+  #   CMDx::Correlator.id  # => "req-12345"
+  #
+  #   # Chain automatically inherits correlation ID
+  #   result = ProcessOrderTask.call(order_id: 123)
+  #   result.chain.id  # => "req-12345"
+  #
+  # @example Block-based correlation context
+  #   CMDx::Correlator.use("workflow-operation-456") do
+  #     # All tasks within this block share the same correlation
+  #     ProcessOrderTask.call(order_id: 123)
+  #     SendEmailTask.call(user_id: 456)
+  #   end
+  #   # Correlation context is automatically restored
+  #
+  # @example Nested correlation contexts
+  #   CMDx::Correlator.use("parent-operation") do
+  #     CMDx::Correlator.use("child-operation") do
+  #       ProcessOrderTask.call(order_id: 123)
+  #       # Uses "child-operation" as correlation ID
+  #     end
+  #     # Restored to "parent-operation"
+  #     SendEmailTask.call(user_id: 456)
+  #   end
+  #
+  # @example Manual correlation management
+  #   # Set correlation ID for current thread
+  #   CMDx::Correlator.id = "manual-correlation"
+  #
+  #   # Check current correlation
+  #   current_id = CMDx::Correlator.id
+  #
+  #   # Clear correlation when done
+  #   CMDx::Correlator.clear
+  #
+  # @example Middleware integration pattern
+  #   class CorrelationMiddleware
+  #     def call(env)
+  #       correlation_id = env['HTTP_X_CORRELATION_ID'] || CMDx::Correlator.generate
+  #
+  #       CMDx::Correlator.use(correlation_id) do
+  #         @app.call(env)
+  #       end
+  #     end
+  #   end
+  #
+  # @see CMDx::Chain Chain execution context that inherits correlation IDs
+  # @since 1.0.0
+  module Correlator
+
+    ##
+    # Thread-local storage key for correlation identifiers.
+    #
+    # Uses a Symbol key to avoid potential conflicts with other thread-local
+    # variables and to ensure consistent access across the correlator methods.
+    #
+    # @return [Symbol] the thread-local storage key
+    THREAD_KEY = :cmdx_correlation_id
+
+    module_function
+
+    ##
+    # Generates a new UUID suitable for use as a correlation identifier.
+    #
+    # Creates a RFC 4122 compliant UUID using SecureRandom, providing a globally
+    # unique identifier suitable for distributed request tracing.
+    #
+    # @return [String] a new UUID string in standard format (e.g., "123e4567-e89b-12d3-a456-426614174000")
+    #
+    # @example Generating correlation IDs
+    #   id1 = CMDx::Correlator.generate  # => "018c2b95-b764-7615-a924-cc5b910ed1e5"
+    #   id2 = CMDx::Correlator.generate  # => "018c2b95-b765-7123-b456-dd7c920fe3a8"
+    #   id1 != id2  # => true
+    def generate
+      SecureRandom.uuid
+    end
+
+    ##
+    # Retrieves the current thread's correlation identifier.
+    #
+    # Returns the correlation ID that was previously set for the current thread,
+    # or nil if no correlation ID has been established. This method is thread-safe
+    # and will not interfere with correlation IDs set in other threads.
+    #
+    # @return [String, nil] the current correlation ID or nil if none is set
+    #
+    # @example Checking current correlation
+    #   CMDx::Correlator.id  # => nil (when none is set)
+    #
+    #   CMDx::Correlator.id = "test-correlation"
+    #   CMDx::Correlator.id  # => "test-correlation"
+    def id
+      Thread.current[THREAD_KEY]
+    end
+
+    ##
+    # Sets the correlation identifier for the current thread.
+    #
+    # Assigns a correlation ID to the current thread's local storage, making it
+    # available for subsequent operations within the same thread context. The
+    # correlation ID will persist until explicitly changed or cleared.
+    #
+    # @param value [String, #to_s] the correlation identifier to set
+    # @return [String] the assigned correlation identifier
+    #
+    # @example Setting correlation ID
+    #   CMDx::Correlator.id = "user-request-123"
+    #   CMDx::Correlator.id  # => "user-request-123"
+    #
+    # @example Type coercion
+    #   CMDx::Correlator.id = 12345
+    #   CMDx::Correlator.id  # => 12345 (stored as provided)
+    def id=(value)
+      Thread.current[THREAD_KEY] = value
+    end
+
+    ##
+    # Clears the correlation identifier for the current thread.
+    #
+    # Removes the correlation ID from the current thread's local storage,
+    # effectively resetting the correlation context. Subsequent calls to
+    # {#id} will return nil until a new correlation ID is set.
+    #
+    # @return [nil] always returns nil
+    #
+    # @example Clearing correlation
+    #   CMDx::Correlator.id = "temporary-correlation"
+    #   CMDx::Correlator.id  # => "temporary-correlation"
+    #
+    #   CMDx::Correlator.clear
+    #   CMDx::Correlator.id  # => nil
+    def clear
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    ##
+    # Temporarily sets a correlation identifier for the duration of a block.
+    #
+    # Establishes a correlation context for the given block, automatically
+    # restoring the previous correlation ID when the block completes. This
+    # method is exception-safe and will restore the original context even
+    # if the block raises an error.
+    #
+    # This is the preferred method for managing correlation contexts as it
+    # ensures proper cleanup and supports nested correlation scopes.
+    #
+    # @param value [String, #to_s] the correlation identifier to use during block execution
+    # @yieldreturn [Object] the return value of the block
+    # @return [Object] the return value of the executed block
+    #
+    # @example Basic usage
+    #   result = CMDx::Correlator.use("operation-123") do
+    #     ProcessOrderTask.call(order_id: 456)
+    #   end
+    #   # Correlation context is automatically restored
+    #
+    # @example Nested contexts
+    #   CMDx::Correlator.use("parent") do
+    #     CMDx::Correlator.id  # => "parent"
+    #
+    #     CMDx::Correlator.use("child") do
+    #       CMDx::Correlator.id  # => "child"
+    #     end
+    #
+    #     CMDx::Correlator.id  # => "parent" (restored)
+    #   end
+    #
+    # @example Exception safety
+    #   CMDx::Correlator.id = "original"
+    #
+    #   begin
+    #     CMDx::Correlator.use("temporary") do
+    #       raise StandardError, "something went wrong"
+    #     end
+    #   rescue StandardError
+    #     CMDx::Correlator.id  # => "original" (still restored)
+    #   end
+    def use(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise TypeError,
+              "must be a String or Symbol"
+      end
+
+      previous_id = id
+      self.id = value
+      yield
+    ensure
+      self.id = previous_id
+    end
+
+  end
+end

data/lib/cmdx/error.rb

@@ -2,22 +2,224 @@
 
 module CMDx
 
-  # Base of all CMDx errors
+  ##
+  # Base exception class for all CMDx-specific errors.
+  # All other CMDx exceptions inherit from this class, providing a common
+  # hierarchy for error handling and rescue operations.
+  #
+  # This allows for catching all CMDx-related exceptions with a single rescue clause
+  # while still maintaining specific error types for detailed error handling.
+  #
+  # @example Catching all CMDx errors
+  #   begin
+  #     ProcessOrderTask.call(invalid_params)
+  #   rescue CMDx::Error => e
+  #     logger.error "CMDx error occurred: #{e.message}"
+  #   end
+  #
+  # @example Specific error handling
+  #   begin
+  #     ProcessOrderTask.call(order_id: "invalid")
+  #   rescue CMDx::CoercionError => e
+  #     # Handle type coercion failures
+  #   rescue CMDx::ValidationError => e
+  #     # Handle validation failures
+  #   rescue CMDx::Error => e
+  #     # Handle any other CMDx errors
+  #   end
+  #
+  # @see StandardError Ruby's standard error base class
+  # @since 1.0.0
   Error = Class.new(StandardError)
 
-  # Raised when value could not be coerced to defined type
+  ##
+  # Raised when a value cannot be coerced to the specified type.
+  # This exception occurs during parameter processing when type coercion fails,
+  # typically due to incompatible data formats or invalid input values.
+  #
+  # CoercionError is raised by the various coercion modules when they encounter
+  # values that cannot be converted to the target type. Each coercion module
+  # provides specific error messages indicating the expected type and the
+  # problematic value.
+  #
+  # @example Integer coercion failure
+  #   class MyTask < CMDx::Task
+  #     required :count, type: :integer
+  #   end
+  #
+  #   # This will raise CoercionError during parameter processing
+  #   MyTask.call(count: "not_a_number")
+  #   # => CMDx::CoercionError: could not coerce into an integer
+  #
+  # @example Date coercion failure
+  #   class ScheduleTask < CMDx::Task
+  #     required :due_date, type: :date
+  #   end
+  #
+  #   ScheduleTask.call(due_date: "invalid_date")
+  #   # => CMDx::CoercionError: could not coerce into a date
+  #
+  # @example Handling coercion errors
+  #   begin
+  #     MyTask.call(count: "invalid")
+  #   rescue CMDx::CoercionError => e
+  #     # Log the coercion failure and provide user-friendly message
+  #     logger.warn "Invalid input format: #{e.message}"
+  #     render json: { error: "Please provide a valid number" }
+  #   end
+  #
+  # @see Parameter Parameter type definitions and coercion
+  # @see ParameterValue Parameter value processing and coercion
+  # @since 1.0.0
   CoercionError = Class.new(Error)
 
-  # Raised when call execution time exceeds max allowed
-  TimeoutError = Class.new(Interrupt)
-
-  # Raised when call method not defined in implementing class
+  ##
+  # Raised when a task class doesn't implement the required `call` method.
+  # This exception enforces the CMDx contract that all task classes must
+  # provide a `call` method containing their business logic.
+  #
+  # This error typically occurs during development when creating new task
+  # classes that inherit from CMDx::Task but forget to implement the
+  # abstract `call` method.
+  #
+  # @example Missing call method
+  #   class IncompleteTask < CMDx::Task
+  #     required :data, type: :string
+  #     # Missing call method implementation
+  #   end
+  #
+  #   IncompleteTask.call(data: "test")
+  #   # => CMDx::UndefinedCallError: call method not defined in IncompleteTask
+  #
+  # @example Proper task implementation
+  #   class CompleteTask < CMDx::Task
+  #     required :data, type: :string
+  #
+  #     def call
+  #       # Business logic implementation
+  #       context.result = process(data)
+  #     end
+  #   end
+  #
+  # @example Handling undefined call errors
+  #   begin
+  #     SomeTask.call(params)
+  #   rescue CMDx::UndefinedCallError => e
+  #     # This should typically only happen during development
+  #     logger.error "Task implementation incomplete: #{e.message}"
+  #     raise # Re-raise as this is a programming error
+  #   end
+  #
+  # @see Task Task base class and call method requirement
+  # @see Workflow Workflow base class and call method requirement
+  # @since 1.0.0
   UndefinedCallError = Class.new(Error)
 
-  # Raised when unknown coercion type
+  ##
+  # Raised when an unknown or unsupported coercion type is specified.
+  # This exception occurs when parameter definitions reference type coercions
+  # that don't exist or aren't registered in the CMDx coercion system.
+  #
+  # This error helps catch typos in type specifications and ensures that
+  # only supported data types are used in parameter definitions.
+  #
+  # @example Unknown type specification
+  #   class MyTask < CMDx::Task
+  #     required :value, type: :unknown_type  # Typo or unsupported type
+  #   end
+  #
+  #   MyTask.call(value: "test")
+  #   # => CMDx::UnknownCoercionError: unknown coercion unknown_type
+  #
+  # @example Common typos
+  #   class TaskWithTypo < CMDx::Task
+  #     required :count, type: :integr      # Should be :integer
+  #     required :flag, type: :bool         # Should be :boolean
+  #     required :data, type: :json         # Should be :hash
+  #   end
+  #
+  # @example Supported types
+  #   class ProperTask < CMDx::Task
+  #     required :id, type: :integer
+  #     required :active, type: :boolean
+  #     required :metadata, type: :hash
+  #     required :tags, type: :array
+  #     required :name, type: :string
+  #     required :score, type: :float
+  #     required :created_at, type: :date_time
+  #   end
+  #
+  # @example Handling unknown coercion errors
+  #   begin
+  #     MyTask.call(params)
+  #   rescue CMDx::UnknownCoercionError => e
+  #     # This indicates a programming error in parameter definition
+  #     logger.error "Invalid type specification: #{e.message}"
+  #     raise # Re-raise as this should be fixed in code
+  #   end
+  #
+  # @see Parameter Parameter type definitions
+  # @see ParameterValue Type coercion processing
+  # @since 1.0.0
   UnknownCoercionError = Class.new(Error)
 
-  # Raised when value failed a validation
+  ##
+  # Raised when a parameter value fails validation rules.
+  # This exception occurs during parameter processing when values don't meet
+  # the specified validation criteria, such as format requirements, length
+  # constraints, or custom validation logic.
+  #
+  # ValidationError provides detailed feedback about why validation failed,
+  # helping developers and users understand what corrections are needed.
+  #
+  # @example Presence validation failure
+  #   class CreateUserTask < CMDx::Task
+  #     required :email, type: :string, presence: true
+  #   end
+  #
+  #   CreateUserTask.call(email: "")
+  #   # => CMDx::ValidationError: cannot be empty
+  #
+  # @example Format validation failure
+  #   class ValidateEmailTask < CMDx::Task
+  #     required :email, type: :string, format: { with: /@/ }
+  #   end
+  #
+  #   ValidateEmailTask.call(email: "invalid-email")
+  #   # => CMDx::ValidationError: is an invalid format
+  #
+  # @example Length validation failure
+  #   class SetPasswordTask < CMDx::Task
+  #     required :password, type: :string, length: { min: 8 }
+  #   end
+  #
+  #   SetPasswordTask.call(password: "short")
+  #   # => CMDx::ValidationError: length must be at least 8
+  #
+  # @example Custom validation failure
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :quantity, type: :integer, custom: -> (val) { val > 0 }
+  #   end
+  #
+  #   ProcessOrderTask.call(quantity: -1)
+  #   # => CMDx::ValidationError: is not valid
+  #
+  # @example Handling validation errors
+  #   begin
+  #     CreateUserTask.call(email: "", password: "short")
+  #   rescue CMDx::ValidationError => e
+  #     # Provide user-friendly feedback
+  #     render json: {
+  #       error: "Validation failed",
+  #       message: e.message,
+  #       field: extract_field_from_context(e)
+  #     }
+  #   end
+  #
+  # @see Parameter Parameter validation options
+  # @see ParameterValue Validation processing
+  # @see Validators Validation modules (Presence, Format, Length, etc.)
+  # @since 1.0.0
   ValidationError = Class.new(Error)
 
 end