cmdx 1.0.0 → 1.1.0

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?
 

data/lib/cmdx/core_ext/hash.rb

@@ -2,51 +2,28 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Hash that provide CMDx-specific key access methods.
-    #
-    # HashExtensions adds flexible key access that works with both
-    # string and symbol keys interchangeably. These methods are prefixed
-    # with `__cmdx_` to avoid conflicts with existing Hash methods.
-    #
-    # @example Flexible key access
-    #   hash = {name: "John", "age" => 30}
-    #   hash.__cmdx_fetch(:name)      # => "John" (symbol key)
-    #   hash.__cmdx_fetch("name")     # => "John" (tries symbol fallback)
-    #   hash.__cmdx_fetch(:age)       # => 30 (string fallback)
-    #
-    # @example Key checking
-    #   hash.__cmdx_key?(:name)       # => true (checks both symbol and string)
-    #   hash.__cmdx_key?("age")       # => true (checks both string and symbol)
-    #
-    # @example Method response checking
-    #   hash.__cmdx_respond_to?(:name)   # => true (considers key as method)
-    #
-    # @see Context Context objects that use hash extensions
-    # @see LazyStruct Structs that leverage hash-like behavior
+    # Extensions for Ruby's Hash class that provide flexible key access and querying.
+    # These extensions are automatically included in all hashes when CMDx is loaded, providing
+    # seamless symbol/string key interoperability and enhanced key existence checking.
     module HashExtensions
 
-      # Fetch a value with automatic symbol/string key conversion.
+      # Fetches a value from the hash with flexible key matching.
+      # Tries the exact key first, then attempts symbol/string conversion if not found.
       #
-      # This method provides flexible key access by trying both the original
-      # key and its converted form (symbol to string or string to symbol).
-      # This is particularly useful for parameter hashes that might use
-      # either format.
+      # @param key [Symbol, String, Object] the key to fetch from the hash
       #
-      # @param key [Symbol, String, Object] key to fetch
-      # @return [Object] value for the key or its converted equivalent
+      # @return [Object, nil] the value associated with the key, or nil if not found
       #
-      # @example Symbol to string conversion
-      #   hash = {"name" => "John"}
-      #   hash.__cmdx_fetch(:name)        # => "John" (tries :name, then "name")
+      # @example Fetch with symbol key
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_fetch(:name) # => "John"
+      #   hash.cmdx_fetch(:age)  # => 30
       #
-      # @example String to symbol conversion
-      #   hash = {name: "John"}
-      #   hash.__cmdx_fetch("name")       # => "John" (tries "name", then :name)
-      #
-      # @example Direct key access
-      #   hash = {id: 123}
-      #   hash.__cmdx_fetch(:id)          # => 123 (direct match)
-      def __cmdx_fetch(key)
+      # @example Fetch with string key
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_fetch("name") # => "John"
+      #   hash.cmdx_fetch("age")  # => 30
+      def cmdx_fetch(key)
         case key
         when Symbol then fetch(key) { self[key.to_s] }
         when String then fetch(key) { self[key.to_sym] }
@@ -54,21 +31,21 @@ module CMDx
         end
       end
 
-      # Check if a key exists with automatic symbol/string conversion.
+      # Checks if a key exists in the hash with flexible key matching.
+      # Tries the exact key first, then attempts symbol/string conversion.
       #
-      # This method checks for key existence by trying both the original
-      # key and its converted form. Returns true if either variant exists.
+      # @param key [Symbol, String, Object] the key to check for existence
       #
-      # @param key [Symbol, String, Object] key to check
-      # @return [Boolean] true if key exists in either format
+      # @return [Boolean] true if the key exists (in any form), false otherwise
       #
-      # @example Symbol/string checking
-      #   hash = {name: "John", "age" => 30}
-      #   hash.__cmdx_key?(:name)         # => true
-      #   hash.__cmdx_key?("name")        # => true (checks :name fallback)
-      #   hash.__cmdx_key?(:age)          # => true (checks "age" fallback)
-      #   hash.__cmdx_key?(:missing)      # => false
-      def __cmdx_key?(key)
+      # @example Check key existence
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_key?(:name)   # => true
+      #   hash.cmdx_key?("name")  # => true
+      #   hash.cmdx_key?(:age)    # => true
+      #   hash.cmdx_key?("age")   # => true
+      #   hash.cmdx_key?(:missing) # => false
+      def cmdx_key?(key)
         key?(key) || key?(
           case key
           when Symbol then key.to_s
@@ -79,30 +56,28 @@ module CMDx
         false
       end
 
-      # Check if hash responds to a method or contains a key.
+      # Checks if the hash responds to a method or contains a key.
+      # Combines method existence checking with flexible key existence checking.
       #
-      # This method extends respond_to? behavior to also check if the
-      # hash contains a key that matches the method name. This enables
-      # hash keys to be treated as virtual methods.
+      # @param key [Symbol, String] the method name or key to check
+      # @param include_private [Boolean] whether to include private methods in the check
       #
-      # @param key [Symbol, String] method name to check
-      # @param include_private [Boolean] whether to include private methods
-      # @return [Boolean] true if responds to method or contains key
+      # @return [Boolean] true if the hash responds to the method or contains the key
       #
-      # @example Method response checking
-      #   hash = {name: "John"}
-      #   hash.__cmdx_respond_to?(:name)     # => true (has key :name)
-      #   hash.__cmdx_respond_to?(:keys)     # => true (real Hash method)
-      #   hash.__cmdx_respond_to?(:missing)  # => false
-      def __cmdx_respond_to?(key, include_private = false)
-        respond_to?(key.to_sym, include_private) || __cmdx_key?(key)
+      # @example Check method or key response
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_respond_to?(:keys)     # => true (method exists)
+      #   hash.cmdx_respond_to?(:name)     # => true (key exists)
+      #   hash.cmdx_respond_to?("age")     # => true (key exists)
+      #   hash.cmdx_respond_to?(:missing)  # => false
+      def cmdx_respond_to?(key, include_private = false)
+        respond_to?(key.to_sym, include_private) || cmdx_key?(key)
       rescue NoMethodError
-        __cmdx_key?(key)
+        cmdx_key?(key)
       end
 
     end
   end
 end
 
-# Extend all hashes with CMDx utility methods
 Hash.include(CMDx::CoreExt::HashExtensions)