cmdx 1.0.1 → 1.1.0

data/lib/cmdx/coercions/time.rb

@@ -2,54 +2,38 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Time type.
+    # Coercion class for converting values to Time objects.
     #
-    # The Time coercion converts parameter values to Time objects
-    # with support for time parsing, custom format strings, and
-    # automatic handling of time-like objects.
-    #
-    # @example Basic time coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :created_at, type: :time
-    #     optional :scheduled_at, type: :time, format: "%Y-%m-%d %H:%M:%S"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Time.call("2023-12-25 14:30:00")                      # => Time object
-    #   Coercions::Time.call("25/12/2023 2:30 PM", format: "%d/%m/%Y %l:%M %p") # Custom format
-    #   Coercions::Time.call(Date.today)                                 # => Time (from Date)
-    #   Coercions::Time.call("invalid")                                  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Time
-
-      # Time-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent time-like objects
-      ANALOG_TYPES = %w[Date DateTime Time].freeze
+    # This coercion handles conversion of various types to Time objects, with special
+    # handling for analog types (DateTime, Time) and custom format parsing.
+    class Time < Coercion
 
-      module_function
+      ANALOG_TYPES = %w[DateTime Time].freeze
 
-      # Coerce a value to Time.
+      # Converts the given value to a Time object.
+      #
+      # @param value [Object] the value to convert to a Time object
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom format string for parsing
+      #
+      # @return [Time] the converted Time object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a Time object
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as-is)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using Time.parse)
+      # @example Converting with custom format
+      #   Coercions::Time.call('2023-12-25 14:30', strptime: '%Y-%m-%d %H:%M') #=> 2023-12-25 14:30:00
       #
-      # @param value [Object] value to coerce to time
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom time format string
-      # @return [Time] coerced time value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting standard time strings
+      #   Coercions::Time.call('2023-12-25 14:30:00') #=> 2023-12-25 14:30:00
+      #   Coercions::Time.call('Dec 25, 2023') #=> 2023-12-25 00:00:00
       #
-      # @example
-      #   Coercions::Time.call("2023-12-25 14:30:00")                        # => Time
-      #   Coercions::Time.call("25/12/2023 14:30", format: "%d/%m/%Y %H:%M") # => Time with custom format
-      #   Coercions::Time.call(DateTime.now)                                 # => Time from DateTime
+      # @example Analog types pass through unchanged
+      #   time = Time.now
+      #   Coercions::Time.call(time) #=> time (unchanged)
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::Time.strptime(value, options[:format]) if options[:format]
+        return value.to_time if value.respond_to?(:to_time)
+        return ::Time.strptime(value, options[:strptime]) if options[:strptime]
 
         ::Time.parse(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/virtual.rb

@@ -2,41 +2,24 @@
 
 module CMDx
   module Coercions
-    # Virtual coercion that returns values unchanged.
+    # Coercion class for virtual values that performs no conversion.
     #
-    # The Virtual coercion is a pass-through that returns the input value
-    # without any transformation. This is useful for parameters that should
-    # not undergo type coercion or when you want to preserve the original
-    # value type and structure.
-    #
-    # @example Virtual coercion usage
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order  # defaults to virtual type
-    #     optional :metadata, type: :virtual
-    #     optional :config, type: :virtual
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Virtual.call("string")     # => "string"
-    #   Coercions::Virtual.call(123)          # => 123
-    #   Coercions::Virtual.call([1, 2, 3])    # => [1, 2, 3]
-    #   Coercions::Virtual.call({a: 1})       # => {a: 1}
-    #   Coercions::Virtual.call(nil)          # => nil
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions (defaults to virtual)
-    module Virtual
+    # This coercion acts as a pass-through, returning the input value unchanged.
+    # It's useful when you want to maintain the original value type and format
+    # without any transformation.
+    class Virtual < Coercion
 
-      module_function
-
-      # Return the value unchanged (no coercion).
+      # Returns the given value unchanged.
+      #
+      # @param value [Object] the value to return as-is
+      # @param _options [Hash] optional configuration (currently unused)
       #
-      # @param value [Object] value to pass through unchanged
-      # @param _options [Hash] coercion options (unused)
-      # @return [Object] the original value without modification
+      # @return [Object] the original value without any conversion
       #
-      # @example
-      #   Coercions::Virtual.call(anything)  # => anything
+      # @example Returning values unchanged
+      #   Coercions::Virtual.call("hello") #=> "hello"
+      #   Coercions::Virtual.call(123) #=> 123
+      #   Coercions::Virtual.call(nil) #=> nil
       def call(value, _options = {})
         value
       end

data/lib/cmdx/configuration.rb

@@ -2,119 +2,65 @@
 
 module CMDx
 
-  ##
-  # Provides global configuration management for CMDx framework settings.
-  # The configuration system allows customization of default behaviors for tasks,
-  # workflows, logging, and error handling across the entire application.
-  #
-  # Configuration settings are stored as instance variables with explicit accessors
-  # and can be modified through the configure block pattern. These settings serve
-  # as defaults that can be overridden at the task or workflow level when needed.
-  #
-  # ## Available Configuration Options
-  #
-  # - **logger**: Logger instance for task execution logging
-  # - **task_halt**: Result statuses that cause `call!` to raise faults
-  # - **workflow_halt**: Result statuses that halt workflow execution
-  # - **middlewares**: Global middleware registry applied to all tasks
-  # - **callbacks**: Global callback registry applied to all tasks
-  #
-  # ## Configuration Hierarchy
-  #
-  # CMDx follows a configuration hierarchy where settings can be overridden:
-  # 1. **Global Configuration**: Framework-wide defaults (this module)
-  # 2. **Task Settings**: Class-level overrides via `task_settings!`
-  # 3. **Runtime Parameters**: Instance-specific overrides during execution
-  #
-  # @example Basic configuration setup
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout)
-  #     config.task_halt = ["failed"] # Only halt on failures
-  #     config.middlewares.use CMDx::Middlewares::Timeout, 30
-  #   end
-  #
-  # @example Rails initializer configuration
-  #   # config/initializers/cmdx.rb
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout)
-  #     config.task_halt = CMDx::Result::FAILED
-  #     config.workflow_halt = [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
-  #
-  #     # Add global middlewares
-  #     config.middlewares.use CMDx::Middlewares::Timeout, 30
-  #     config.middlewares.use AuthenticationMiddleware if Rails.env.production?
-  #
-  #     # Add global callbacks
-  #     config.callbacks.register :before_execution, :log_task_start
-  #     config.callbacks.register :on_success, NotificationCallback.new([:slack])
-  #     config.callbacks.register :on_failure, :alert_admin, if: :production?
-  #   end
-  #
-  # @example Custom logger configuration
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new(
-  #       Rails.root.join('log', 'cmdx.log'),
-  #       formatter: CMDx::LogFormatters::Json.new
-  #     )
-  #   end
-  #
-  # @example Environment-specific configuration
-  #   CMDx.configure do |config|
-  #     case Rails.env
-  #     when 'development'
-  #       config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::PrettyLine.new)
-  #     when 'test'
-  #       config.logger = Logger.new('/dev/null')  # Silent logging
-  #     when 'production'
-  #       config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Json.new)
-  #     end
-  #   end
-  #
-  # @see Task Task-level configuration overrides
-  # @see Workflow Workflow-level configuration overrides
-  # @see LogFormatters Available logging formatters
-  # @see Result Result statuses for halt configuration
-  # @since 1.0.0
-
-  ##
-  # Configuration class that manages CMDx framework settings.
-  # Provides explicit attribute accessors for all configuration options.
-  #
-  # @since 1.0.0
+  # Global configuration class for CMDx framework settings.
+  # Manages logging, middleware, callbacks, coercions, validators, and halt conditions.
   class Configuration
 
-    # Default configuration values
     DEFAULT_HALT = "failed"
 
-    # Configuration attributes
-    attr_accessor :logger, :middlewares, :callbacks, :task_halt, :workflow_halt
+    # @return [Logger] Logger instance for task execution logging
+    attr_accessor :logger
+
+    # @return [MiddlewareRegistry] Global middleware registry applied to all tasks
+    attr_accessor :middlewares
+
+    # @return [CallbackRegistry] Global callback registry applied to all tasks
+    attr_accessor :callbacks
+
+    # @return [CoercionRegistry] Global coercion registry for custom parameter types
+    attr_accessor :coercions
 
-    ##
-    # Initializes a new configuration with default values.
+    # @return [ValidatorRegistry] Global validator registry for custom parameter validation
+    attr_accessor :validators
+
+    # @return [String, Array<String>] Result statuses that cause `call!` to raise faults
+    attr_accessor :task_halt
+
+    # @return [String, Array<String>] Result statuses that halt workflow execution
+    attr_accessor :workflow_halt
+
+    # Initialize a new Configuration instance with default settings.
     #
     # @example
     #   config = CMDx::Configuration.new
+    #   config.logger.level = Logger::DEBUG
+    #
+    # @return [Configuration] A new configuration instance
     def initialize
-      @logger      = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-      @middlewares = MiddlewareRegistry.new
-      @callbacks   = CallbackRegistry.new
-      @task_halt   = DEFAULT_HALT
+      @logger        = ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
+      @middlewares   = MiddlewareRegistry.new
+      @callbacks     = CallbackRegistry.new
+      @coercions     = CoercionRegistry.new
+      @validators    = ValidatorRegistry.new
+      @task_halt     = DEFAULT_HALT
       @workflow_halt = DEFAULT_HALT
     end
 
-    ##
-    # Returns a hash representation of the configuration.
-    # Used internally by the framework for configuration merging.
+    # Convert the configuration to a hash representation.
     #
-    # @return [Hash] configuration attributes as a hash
     # @example
-    #   config = CMDx.configuration
-    #   config.to_h  #=> { logger: ..., task_halt: "failed", ... }
+    #   config = CMDx::Configuration.new
+    #   hash = config.to_h
+    #   puts hash[:task_halt] # => "failed"
+    #
+    # @return [Hash] Hash containing all configuration values
     def to_h
       {
         logger: @logger,
         middlewares: @middlewares,
         callbacks: @callbacks,
+        coercions: @coercions,
+        validators: @validators,
         task_halt: @task_halt,
         workflow_halt: @workflow_halt
       }
@@ -124,72 +70,33 @@ module CMDx
 
   module_function
 
-  ##
-  # Returns the current global configuration instance.
-  # Creates a new configuration with default values if none exists.
+  # Get the current global configuration instance.
+  # Creates a new configuration if none exists.
   #
-  # The configuration is stored as a module-level variable and persists
-  # throughout the application lifecycle. It uses lazy initialization,
-  # creating the configuration only when first accessed.
-  #
-  # @return [Configuration] the current configuration object
-  #
-  # @example Accessing configuration values
-  #   CMDx.configuration.logger          #=> <Logger instance>
-  #   CMDx.configuration.task_halt       #=> "failed"
-  #
-  # @example Checking configuration state
+  # @example
   #   config = CMDx.configuration
-  #   config.logger.class                #=> Logger
+  #   config.logger.level = Logger::INFO
+  #
+  # @return [Configuration] The global configuration instance
   def configuration
     return @configuration if @configuration
 
     @configuration ||= Configuration.new
   end
 
-  ##
-  # Configures CMDx settings using a block-based DSL.
-  # This is the preferred method for setting up CMDx configuration
-  # as it provides a clean, readable syntax for configuration management.
-  #
-  # The configuration block yields the current configuration object,
-  # allowing you to set multiple options in a single, organized block.
-  #
-  # @yieldparam config [Configuration] the configuration object to modify
-  # @return [Configuration] the updated configuration object
-  # @raise [ArgumentError] if no block is provided
+  # Configure the global CMDx settings using a block.
   #
-  # @example Basic configuration
+  # @example
   #   CMDx.configure do |config|
-  #     config.task_halt = ["failed", "skipped"]
+  #     config.task_halt = ["failed", "error"]
+  #     config.logger.level = Logger::DEBUG
   #   end
   #
-  # @example Complex configuration with conditionals
-  #   CMDx.configure do |config|
-  #     config.logger = Rails.logger if defined?(Rails)
-  #
-  #     config.task_halt = if Rails.env.production?
-  #       "failed"  # Only halt on failures in production
-  #     else
-  #       ["failed", "skipped"]  # Halt on both in development
-  #     end
+  # @yield [Configuration] The configuration instance
   #
-
-  #   end
+  # @return [Configuration] The configured instance
   #
-  # @example Formatter configuration
-  #   CMDx.configure do |config|
-  #     config.logger = Logger.new($stdout).tap do |logger|
-  #       logger.formatter = case ENV['LOG_FORMAT']
-  #       when 'json'
-  #         CMDx::LogFormatters::Json.new
-  #       when 'pretty'
-  #         CMDx::LogFormatters::PrettyLine.new
-  #       else
-  #         CMDx::LogFormatters::Line.new
-  #       end
-  #     end
-  #   end
+  # @raise [ArgumentError] If no block is provided
   def configure
     raise ArgumentError, "block required" unless block_given?
 
@@ -198,34 +105,13 @@ module CMDx
     config
   end
 
-  ##
-  # Resets the configuration to default values.
-  # This method creates a fresh configuration object with framework defaults,
-  # discarding any previously set custom values.
+  # Reset the global configuration to default values.
   #
-  # @return [Configuration] the newly created configuration with default values
-  #
-  # @example Resetting configuration
-  #   # After custom configuration
-  #   CMDx.configure { |c| c.task_halt = ["failed"] }
-  #   CMDx.configuration.task_halt  #=> ["failed"]
-  #
-  #   # Reset to defaults
+  # @example
   #   CMDx.reset_configuration!
-  #   CMDx.configuration.task_halt  #=> "failed"
-  #
-  # @example Testing with clean configuration
-  #   # In test setup
-  #   def setup
-  #     CMDx.reset_configuration!  # Start with clean defaults
-  #   end
-  #
-  # @example Conditional reset
-  #   # Reset configuration in development for experimentation
-  #   CMDx.reset_configuration! if Rails.env.development?
+  #   CMDx.configuration.task_halt # => "failed"
   #
-  # @note This method is primarily useful for testing or when you need
-  #   to return to a known default state.
+  # @return [Configuration] A new configuration instance with defaults
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -1,181 +1,38 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Context provides a flexible parameter storage and data passing mechanism for CMDx tasks.
-  # It extends LazyStruct to offer dynamic attribute access with both hash-style and method-style
-  # syntax, serving as the primary interface for task input parameters and inter-task communication.
+  # Parameter and data context for task execution.
   #
-  # Context objects act as the data container for task execution, holding input parameters,
-  # intermediate results, and any data that needs to be shared between tasks. They support
-  # dynamic attribute assignment and provide a convenient API for data manipulation throughout
-  # the task execution lifecycle.
-  #
-  #
-  # ## Usage Patterns
-  #
-  # Context is typically used in three main scenarios:
-  # 1. **Parameter Input**: Passing initial data to tasks
-  # 2. **Data Storage**: Storing intermediate results during task execution
-  # 3. **Task Communication**: Sharing data between multiple tasks
-  #
-  # @example Basic parameter input
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #     optional :notify_customer, type: :boolean, default: true
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #       context.processed_at = Time.now
-  #
-  #       if notify_customer
-  #         context.notification_sent = send_notification
-  #       end
-  #     end
-  #   end
-  #
-  #   result = ProcessOrderTask.call(order_id: 123, notify_customer: false)
-  #   result.context.order         #=> <Order id: 123>
-  #   result.context.processed_at  #=> 2023-01-01 12:00:00 UTC
-  #   result.context.notification_sent #=> nil
-  #
-  # @example Dynamic attribute assignment
-  #   class DataProcessingTask < CMDx::Task
-  #     required :input_data, type: :hash
-  #
-  #     def call
-  #       # Method-style assignment
-  #       context.processed_data = transform(input_data)
-  #       context.validation_errors = validate(context.processed_data)
-  #
-  #       # Hash-style assignment
-  #       context[:metadata] = { processed_at: Time.now }
-  #       context["summary"] = generate_summary
-  #
-  #       # Workflow assignment
-  #       context.merge!(
-  #         status: "complete",
-  #         record_count: context.processed_data.size
-  #       )
-  #     end
-  #   end
-  #
-  # @example Inter-task communication
-  #   class OrderProcessingWorkflow < CMDx::Workflow
-  #     def call
-  #       # First task sets up context
-  #       ValidateOrderTask.call(context)
-  #
-  #       # Subsequent tasks use and modify context
-  #       ProcessPaymentTask.call(context)
-  #       UpdateInventoryTask.call(context)
-  #       SendConfirmationTask.call(context)
-  #     end
-  #   end
-  #
-  #   # Initial context with order data
-  #   result = OrderProcessingWorkflow.call(
-  #     order_id: 123,
-  #     payment_method: "credit_card",
-  #     customer_email: "customer@example.com"
-  #   )
-  #
-  #   # Context accumulates data from all tasks
-  #   result.context.order           #=> <Order> (from ValidateOrderTask)
-  #   result.context.payment_result  #=> <Payment> (from ProcessPaymentTask)
-  #   result.context.inventory_updated #=> true (from UpdateInventoryTask)
-  #   result.context.confirmation_sent #=> true (from SendConfirmationTask)
-  #
-  # @example Context passing between tasks
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #
-  #       # Pass context to subtasks
-  #       payment_result = ProcessPaymentTask.call(context)
-  #       email_result = SendEmailTask.call(context)
-  #
-  #       # Results maintain context continuity
-  #       context.payment_processed = payment_result.success?
-  #       context.email_sent = email_result.success?
-  #     end
-  #   end
-  #
-  #   # After execution, context contains accumulated data
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.context.order              #=> <Order>
-  #   result.context.payment_processed  #=> true
-  #   result.context.email_sent         #=> true
-  #
-  # @example Context with nested data structures
-  #   class AnalyticsTask < CMDx::Task
-  #     required :user_id, type: :integer
-  #
-  #     def call
-  #       context.user = User.find(user_id)
-  #       context.analytics = {
-  #         page_views: calculate_page_views,
-  #         session_duration: calculate_session_duration,
-  #         conversion_rate: calculate_conversion_rate
-  #       }
-  #
-  #       # Access nested data
-  #       context.dig(:analytics, :page_views)  #=> 150
-  #
-  #       # Add more nested data
-  #       context.analytics[:last_login] = context.user.last_login
-  #     end
-  #   end
-  #
-  # @see LazyStruct Base class providing dynamic attribute functionality
-  # @see Task Task base class that uses Context for parameter storage
-  # @see Chain Chain execution context that Context belongs to
-  # @see Parameter Parameter definitions that populate Context
-  # @since 1.0.0
+  # Context provides flexible data storage and access patterns for task
+  # parameters and runtime data. Built on LazyStruct, it supports both
+  # hash-like and object-like access patterns with dynamic attribute
+  # assignment and automatic key normalization.
   class Context < LazyStruct
 
-    ##
-    # Builds a Context instance from the given input, with intelligent handling
-    # of existing Context objects to avoid unnecessary object creation.
+    # Creates or returns a context instance from the given input.
     #
-    # This factory method provides optimized Context creation by:
-    # - Returning existing Context objects if they're unfrozen (reusable)
-    # - Creating new Context objects for frozen contexts (immutable)
-    # - Converting hash-like objects into new Context instances
+    # This method provides a safe way to build context instances, returning
+    # the input unchanged if it's already a Context instance and not frozen,
+    # otherwise creating a new Context instance with the provided data.
     #
-    # @param context [Hash, Context, #to_h] input data for context creation
-    # @return [Context] a Context instance ready for task execution
+    # @param context [Hash, Context, Object] input data to build context from
     #
-    # @example Creating context from hash
-    #   context = Context.build(name: "John", age: 30)
-    #   context.name  #=> "John"
-    #   context.age   #=> 30
+    # @return [Context] a Context instance containing the provided data
     #
-    # @example Reusing unfrozen context
-    #   original = Context.build(data: "test")
-    #   reused = Context.build(original)
-    #   original.object_id == reused.object_id  #=> true
+    # @raise [ArgumentError] if the input doesn't respond to to_h
     #
-    # @example Creating new context from frozen context
-    #   original = Context.build(data: "test")
-    #   original.freeze
-    #   new_context = Context.build(original)
-    #   original.object_id == new_context.object_id  #=> false
+    # @example Build context from hash
+    #   Context.build(name: "John", age: 30)
+    #   # => #<CMDx::Context :name="John" :age=30>
     #
-    # @example Converting ActionController::Parameters
-    #   # In Rails controllers
-    #   params = ActionController::Parameters.new(user: { name: "John" })
-    #   context = Context.build(params.permit(:user))
-    #   context.user  #=> { name: "John" }
+    # @example Build context from existing context
+    #   existing = Context.build(user_id: 123)
+    #   Context.build(existing)
+    #   # => returns existing context unchanged
     #
-    # @example Task execution with built context
-    #   # CMDx automatically uses Context.build for task parameters
-    #   result = ProcessOrderTask.call(order_id: 123, priority: "high")
-    #   # Equivalent to:
-    #   # context = Context.build(order_id: 123, priority: "high")
-    #   # ProcessOrderTask.new(context).call
+    # @example Build context from hash-like object
+    #   Context.build(OpenStruct.new(status: "active"))
+    #   # => #<CMDx::Context :status="active">
     def self.build(context = {})
       return context if context.is_a?(self) && !context.frozen?