cmdx 0.4.0 → 1.0.0

data/lib/cmdx/faults.rb

@@ -2,10 +2,166 @@
 
 module CMDx
 
-  # Raised when halting task processing with skipped context
+  ##
+  # Skipped is a specific fault type raised when a task execution is intentionally
+  # skipped via the `skip!` method. This represents a controlled interruption where
+  # the task determines that execution is not necessary or appropriate under the
+  # current conditions.
+  #
+  # Skipped faults are typically used for:
+  # - Conditional logic where certain conditions make execution unnecessary
+  # - Early returns when prerequisites are not met
+  # - Business logic that determines the operation is redundant
+  # - Graceful handling of edge cases that don't constitute errors
+  #
+  # @example Basic skip usage
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :order_id, type: :integer
+  #
+  #     def call
+  #       context.order = Order.find(order_id)
+  #       skip!(reason: "Order already processed") if context.order.processed?
+  #
+  #       context.order.process!
+  #     end
+  #   end
+  #
+  #   # Non-bang call returns result
+  #   result = ProcessOrderTask.call(order_id: 123)
+  #   result.skipped? #=> true
+  #   result.metadata[:reason] #=> "Order already processed"
+  #
+  #   # Bang call raises exception
+  #   begin
+  #     ProcessOrderTask.call!(order_id: 123)
+  #   rescue CMDx::Skipped => e
+  #     puts "Skipped: #{e.message}"
+  #   end
+  #
+  # @example Conditional skip logic
+  #   class SendNotificationTask < CMDx::Task
+  #     required :user_id, type: :integer
+  #     optional :force, type: :boolean, default: false
+  #
+  #     def call
+  #       context.user = User.find(user_id)
+  #
+  #       unless force || context.user.notifications_enabled?
+  #         skip!(reason: "User has notifications disabled")
+  #       end
+  #
+  #       NotificationService.send(context.user)
+  #     end
+  #   end
+  #
+  # @example Handling skipped tasks in workflows
+  #   begin
+  #     OrderProcessingWorkflow.call!(orders: orders)
+  #   rescue CMDx::Skipped => e
+  #     # Log skipped operations but continue processing
+  #     logger.info "Skipped processing: #{e.message}"
+  #   end
+  #
+  # @see Fault Base fault class with advanced matching capabilities
+  # @see Failed Failed fault type for error conditions
+  # @see Result#skip! Method for triggering skipped faults
+  # @since 1.0.0
   Skipped = Class.new(Fault)
 
-  # Raised when halting task processing with failed context
+  ##
+  # Failed is a specific fault type raised when a task execution encounters an
+  # error condition via the `fail!` method. This represents a controlled failure
+  # where the task explicitly determines that execution cannot continue successfully.
+  #
+  # Failed faults are typically used for:
+  # - Validation errors that prevent successful execution
+  # - Business rule violations that constitute failures
+  # - Resource unavailability or constraint violations
+  # - Explicit error conditions that require attention
+  #
+  # @example Basic failure usage
+  #   class ProcessPaymentTask < CMDx::Task
+  #     required :payment_amount, type: :float
+  #     required :payment_method, type: :string
+  #
+  #     def call
+  #       unless payment_amount > 0
+  #         fail!(reason: "Payment amount must be positive", code: "INVALID_AMOUNT")
+  #       end
+  #
+  #       unless valid_payment_method?
+  #         fail!(reason: "Invalid payment method", code: "INVALID_METHOD")
+  #       end
+  #
+  #       process_payment
+  #     end
+  #   end
+  #
+  #   # Non-bang call returns result
+  #   result = ProcessPaymentTask.call(payment_amount: -10, payment_method: "card")
+  #   result.failed? #=> true
+  #   result.metadata[:reason] #=> "Payment amount must be positive"
+  #   result.metadata[:code] #=> "INVALID_AMOUNT"
+  #
+  #   # Bang call raises exception
+  #   begin
+  #     ProcessPaymentTask.call!(payment_amount: -10, payment_method: "card")
+  #   rescue CMDx::Failed => e
+  #     puts "Failed: #{e.message}"
+  #     puts "Error code: #{e.result.metadata[:code]}"
+  #   end
+  #
+  # @example Validation failure with detailed metadata
+  #   class CreateUserTask < CMDx::Task
+  #     required :email, type: :string
+  #     required :password, type: :string
+  #
+  #     def call
+  #       if User.exists?(email: email)
+  #         fail!(
+  #           "Email already exists",
+  #           code: "EMAIL_EXISTS",
+  #           field: "email",
+  #           suggested_action: "Use different email or login instead"
+  #         )
+  #       end
+  #
+  #       context.user = User.create!(email: email, password: password)
+  #     end
+  #   end
+  #
+  # @example Handling specific failure types
+  #   begin
+  #     ProcessOrderTask.call!(order_id: 123)
+  #   rescue CMDx::Failed.matches? { |f| f.result.metadata[:code] == "PAYMENT_DECLINED" } => e
+  #     # Handle payment failures specifically
+  #     retry_with_backup_payment_method(e.context)
+  #   rescue CMDx::Failed => e
+  #     # Handle all other failures
+  #     log_failure_and_notify_support(e)
+  #   end
+  #
+  # @example Failure propagation in complex workflows
+  #   class OrderFulfillmentTask < CMDx::Task
+  #     def call
+  #       payment_result = ProcessPaymentTask.call(context)
+  #
+  #       if payment_result.failed?
+  #         fail!(
+  #           "Cannot fulfill order due to payment failure",
+  #           code: "PAYMENT_REQUIRED",
+  #           original_error: payment_result.metadata
+  #         )
+  #       end
+  #
+  #       fulfill_order
+  #     end
+  #   end
+  #
+  # @see Fault Base fault class with advanced matching capabilities
+  # @see Skipped Skipped fault type for conditional interruptions
+  # @see Result#fail! Method for triggering failed faults
+  # @since 1.0.0
   Failed = Class.new(Fault)
 
 end

data/lib/cmdx/immutator.rb

@@ -1,20 +1,139 @@
 # frozen_string_literal: true
 
 module CMDx
+  ##
+  # Immutator provides task finalization by freezing objects to prevent mutation
+  # after task execution is complete. This ensures task immutability and prevents
+  # accidental side effects or modifications to completed task instances.
+  #
+  # The Immutator is automatically called during the task termination phase as part
+  # of the execution lifecycle. It freezes the task instance, its result, and
+  # associated objects to maintain data integrity and enforce the single-use pattern
+  # of CMDx tasks.
+  #
+  # ## Freezing Strategy
+  #
+  # The Immutator employs a selective freezing strategy:
+  # 1. **Task Instance**: Always frozen to prevent method calls and modifications
+  # 2. **Result Object**: Always frozen to preserve execution outcome
+  # 3. **Context Object**: Frozen only for the first task in a chain (index 0)
+  # 4. **Chain Object**: Frozen only for the first task in a chain (index 0)
+  #
+  # This selective approach allows subsequent tasks in a workflow or chain to continue
+  # using the shared context and chain objects while ensuring completed tasks remain
+  # immutable.
+  #
+  # ## Test Environment Handling
+  #
+  # In test environments (Rails or Rack), freezing is automatically disabled to
+  # prevent conflicts with test frameworks that may need to stub or mock frozen
+  # objects. This ensures smooth testing without compromising the immutability
+  # guarantees in production environments.
+  #
+  # @example Task execution with automatic freezing
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :order_id, type: :integer
+  #
+  #     def call
+  #       context.order = Order.find(order_id)
+  #       context.order.process!
+  #     end
+  #   end
+  #
+  #   result = ProcessOrderTask.call(order_id: 123)
+  #   result.frozen?         #=> true
+  #   result.task.frozen?    #=> true
+  #   result.context.frozen? #=> true (if first task in chain)
+  #
+  # @example Attempting to modify frozen task (will raise error)
+  #   result = ProcessOrderTask.call(order_id: 123)
+  #   result.context.new_field = "value"  #=> FrozenError
+  #   result.task.call                    #=> FrozenError
+  #
+  # @example Workflow execution with selective freezing
+  #   class OrderWorkflow < CMDx::Workflow
+  #     def call
+  #       ProcessOrderTask.call(context)
+  #       SendEmailTask.call(context)
+  #     end
+  #   end
+  #
+  #   result = OrderWorkflow.call(order_id: 123)
+  #   # First task freezes context and chain
+  #   # Second task can still use unfrozen context for execution
+  #   # But both task instances are individually frozen
+  #
+  # @example Test environment behavior
+  #   # In test environment (SKIP_CMDX_FREEZING=1)
+  #   result = ProcessOrderTask.call(order_id: 123)
+  #   result.frozen?      #=> false (freezing disabled)
+  #   result.task.frozen? #=> false (allows stubbing/mocking)
+  #
+  # @see Task Task execution lifecycle
+  # @see Result Result object that gets frozen
+  # @see Context Context object that may get frozen
+  # @see Chain Chain object that may get frozen
+  # @since 1.0.0
   module Immutator
 
     module_function
 
+    ##
+    # Freezes task-related objects to ensure immutability after execution.
+    # This method is called automatically during task termination and implements
+    # a selective freezing strategy based on task position within a chain.
+    #
+    # The freezing process:
+    # 1. Checks if running in test environment and skips freezing if so
+    # 2. Always freezes the task instance and its result
+    # 3. Freezes context and chain only for the first task (index 0) in a chain
+    #
+    # This selective approach ensures that:
+    # - Completed tasks cannot be modified or re-executed
+    # - Results remain immutable and trustworthy
+    # - Shared objects (context/chain) remain available for subsequent tasks
+    # - Test environments can continue to function with mocking/stubbing
+    #
+    # @param task [Task] the task instance to freeze along with its associated objects
+    # @return [void]
+    #
+    # @example First task in chain (freezes everything)
+    #   task = ProcessOrderTask.call(order_id: 123)
+    #   # task.result.index == 0
+    #   Immutator.call(task)
+    #   # Freezes: task, result, context, chain
+    #
+    # @example Subsequent task in chain (selective freezing)
+    #   # After first task has run
+    #   task = SendEmailTask.call(context)
+    #   # task.result.index == 1
+    #   Immutator.call(task)
+    #   # Freezes: task, result (context and chain remain unfrozen)
+    #
+    # @example Test environment (no freezing)
+    #   ENV["RAILS_ENV"] = "test"
+    #   task = ProcessOrderTask.call(order_id: 123)
+    #   Immutator.call(task)
+    #   # No objects are frozen, allows test stubbing
+    #
+    # @note This method is automatically called by the task execution framework
+    #   and should not typically be called directly by user code.
+    #
+    # @note Freezing is skipped entirely in test environments to prevent conflicts
+    #   with test frameworks that need to stub or mock objects.
     def call(task)
       # Stubbing on frozen objects is not allowed
-      return if (ENV.fetch("RAILS_ENV", nil) || ENV.fetch("RACK_ENV", nil)) == "test"
+      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
+      return if Coercions::Boolean.call(skip_freezing)
 
       task.freeze
       task.result.freeze
       return unless task.result.index.zero?
 
       task.context.freeze
-      task.run.freeze
+      task.chain.freeze
+
+      Chain.clear
     end
 
   end

data/lib/cmdx/lazy_struct.rb

@@ -1,78 +1,321 @@
 # frozen_string_literal: true
 
 module CMDx
+  ##
+  # LazyStruct provides a flexible, hash-like data structure with dynamic method access
+  # and lazy attribute definition. It serves as the foundation for CMDx's Context system,
+  # allowing for dynamic parameter access and manipulation with both hash-style and
+  # method-style syntax.
+  #
+  # LazyStruct combines the flexibility of a Hash with the convenience of method access,
+  # automatically creating getter and setter methods for any key-value pairs stored within it.
+  # All keys are normalized to symbols for consistent access patterns.
+  #
+  #
+  # @example Basic usage
+  #   struct = LazyStruct.new(name: "John", age: 30)
+  #   struct.name        #=> "John"
+  #   struct.age         #=> 30
+  #   struct[:name]      #=> "John"
+  #   struct["age"]      #=> 30
+  #
+  # @example Dynamic attribute assignment
+  #   struct = LazyStruct.new
+  #   struct.email = "john@example.com"
+  #   struct[:phone] = "555-1234"
+  #   struct["address"] = "123 Main St"
+  #
+  #   struct.email       #=> "john@example.com"
+  #   struct.phone       #=> "555-1234"
+  #   struct.address     #=> "123 Main St"
+  #
+  # @example Hash-like operations
+  #   struct = LazyStruct.new(name: "John")
+  #   struct.merge!(age: 30, city: "NYC")
+  #   struct.delete!(:city)
+  #   struct.to_h        #=> {:name => "John", :age => 30}
+  #
+  # @example Nested data access
+  #   struct = LazyStruct.new(user: {profile: {name: "John"}})
+  #   struct.dig(:user, :profile, :name)  #=> "John"
+  #
+  # @example Usage in CMDx Context
+  #   class ProcessUserTask < CMDx::Task
+  #     required :user_id, type: :integer
+  #
+  #     def call
+  #       context.user = User.find(user_id)
+  #       context.processed_at = Time.now
+  #       context.result_data = {status: "complete"}
+  #     end
+  #   end
+  #
+  #   result = ProcessUserTask.call(user_id: 123)
+  #   result.context.user         #=> <User id: 123>
+  #   result.context.processed_at #=> 2023-01-01 12:00:00 UTC
+  #
+  # @see Context Context class that inherits from LazyStruct
+  # @see Configuration Configuration class that uses LazyStruct
+  # @since 1.0.0
   class LazyStruct
 
+    ##
+    # Initializes a new LazyStruct with the given data.
+    # The input must respond to `to_h` for hash conversion.
+    #
+    # @param args [Hash, #to_h] initial data for the struct
+    # @raise [ArgumentError] if args doesn't respond to `to_h`
+    #
+    # @example With hash
+    #   struct = LazyStruct.new(name: "John", age: 30)
+    #
+    # @example With hash-like object
+    #   params = ActionController::Parameters.new(name: "John")
+    #   struct = LazyStruct.new(params)
+    #
+    # @example Empty initialization
+    #   struct = LazyStruct.new
+    #   struct.name = "John"  # Dynamic assignment
     def initialize(args = {})
       unless args.respond_to?(:to_h)
         raise ArgumentError,
               "must be respond to `to_h`"
       end
 
-      @table = args.transform_keys(&:to_sym)
+      @table = args.to_h.transform_keys { |k| symbolized_key(k) }
     end
 
+    ##
+    # Retrieves a value by key using hash-style access.
+    # Keys are automatically converted to symbols.
+    #
+    # @param key [Symbol, String] the key to retrieve
+    # @return [Object, nil] the stored value or nil if not found
+    #
+    # @example
+    #   struct[:name]    #=> "John"
+    #   struct["name"]   #=> "John"
+    #   struct[:missing] #=> nil
     def [](key)
-      @table[key.to_sym]
+      table[symbolized_key(key)]
     end
 
+    ##
+    # Retrieves a value by key with error handling and default support.
+    # Similar to Hash#fetch, raises KeyError if key not found and no default given.
+    #
+    # @param key [Symbol, String] the key to retrieve
+    # @param args [Array] default value if key not found
+    # @return [Object] the stored value or default
+    # @raise [KeyError] if key not found and no default provided
+    #
+    # @example With existing key
+    #   struct.fetch!(:name)  #=> "John"
+    #
+    # @example With default value
+    #   struct.fetch!(:missing, "default")  #=> "default"
+    #
+    # @example With block default
+    #   struct.fetch!(:missing) { "computed default" }  #=> "computed default"
+    #
+    # @example Key not found
+    #   struct.fetch!(:missing)  #=> raises KeyError
     def fetch!(key, ...)
-      @table.fetch(key.to_sym, ...)
+      table.fetch(symbolized_key(key), ...)
     end
 
+    ##
+    # Stores a value by key, converting the key to a symbol.
+    #
+    # @param key [Symbol, String] the key to store under
+    # @param value [Object] the value to store
+    # @return [Object] the stored value
+    #
+    # @example
+    #   struct.store!(:name, "John")
+    #   struct.store!("age", 30)
+    #   struct.name  #=> "John"
+    #   struct.age   #=> 30
     def store!(key, value)
-      @table[key.to_sym] = value
+      table[symbolized_key(key)] = value
     end
     alias []= store!
 
+    ##
+    # Merges another hash-like object into this struct.
+    # All keys from the source are converted to symbols.
+    #
+    # @param args [Hash, #to_h] data to merge into this struct
+    # @return [LazyStruct] self for method chaining
+    #
+    # @example
+    #   struct = LazyStruct.new(name: "John")
+    #   struct.merge!(age: 30, city: "NYC")
+    #   struct.to_h  #=> {:name => "John", :age => 30, :city => "NYC"}
     def merge!(args = {})
-      args.to_h.each { |key, value| store!(key, value) }
+      args.to_h.each { |key, value| store!(symbolized_key(key), value) }
       self
     end
 
+    ##
+    # Deletes a key-value pair from the struct.
+    #
+    # @param key [Symbol, String] the key to delete
+    # @param block [Proc] optional block to execute if key not found
+    # @return [Object, nil] the deleted value or result of block
+    #
+    # @example
+    #   struct.delete!(:name)     #=> "John"
+    #   struct.delete!(:missing)  #=> nil
+    #   struct.delete!(:missing) { "not found" }  #=> "not found"
     def delete!(key, &)
-      @table.delete(key.to_sym, &)
+      table.delete(symbolized_key(key), &)
     end
     alias delete_field! delete!
 
+    ##
+    # Compares this struct with another for equality.
+    # Two LazyStructs are equal if they have the same class and hash representation.
+    #
+    # @param other [Object] object to compare with
+    # @return [Boolean] true if structs are equal
+    #
+    # @example
+    #   struct1 = LazyStruct.new(name: "John")
+    #   struct2 = LazyStruct.new(name: "John")
+    #   struct1 == struct2  #=> true
+    #   struct1.eql?(struct2)  #=> true
     def eql?(other)
       other.is_a?(self.class) && (to_h == other.to_h)
     end
     alias == eql?
 
+    ##
+    # Retrieves nested values using a sequence of keys.
+    # Similar to Hash#dig, safely navigates nested structures.
+    #
+    # @param key [Symbol, String] the first key to access
+    # @param keys [Array<Symbol, String>] additional keys for nested access
+    # @return [Object, nil] the nested value or nil if path doesn't exist
+    # @raise [TypeError] if key cannot be converted to symbol
+    #
+    # @example
+    #   struct = LazyStruct.new(user: {profile: {name: "John"}})
+    #   struct.dig(:user, :profile, :name)  #=> "John"
+    #   struct.dig(:user, :missing, :name)  #=> nil
     def dig(key, *keys)
-      begin
-        key = key.to_sym
-      rescue NoMethodError
-        raise TypeError, "#{key} is not a symbol nor a string"
-      end
-
-      @table.dig(key, *keys)
+      table.dig(symbolized_key(key), *keys)
     end
 
+    ##
+    # Iterates over each key-value pair in the struct.
+    #
+    # @yieldparam key [Symbol] the key
+    # @yieldparam value [Object] the value
+    # @return [LazyStruct] self if block given, Enumerator otherwise
+    #
+    # @example
+    #   struct.each_pair { |key, value| puts "#{key}: #{value}" }
     def each_pair(&)
-      @table.each_pair(&)
+      table.each_pair(&)
     end
 
+    ##
+    # Converts the struct to a hash representation.
+    #
+    # @param block [Proc] optional block for hash transformation
+    # @return [Hash] hash representation with symbol keys
+    #
+    # @example
+    #   struct = LazyStruct.new(name: "John", age: 30)
+    #   struct.to_h  #=> {:name => "John", :age => 30}
     def to_h(&)
-      @table.to_h(&)
+      table.to_h(&)
     end
 
+    ##
+    # Returns a string representation of the struct showing all key-value pairs.
+    #
+    # @return [String] formatted string representation
+    #
+    # @example
+    #   struct = LazyStruct.new(name: "John", age: 30)
+    #   struct.inspect  #=> '#<CMDx::LazyStruct:name="John" :age=30>'
     def inspect
-      "#<#{self.class}#{@table.map { |key, value| ":#{key}=#{value.inspect}" }.join(' ')}>"
+      "#<#{self.class.name}#{table.map { |key, value| ":#{key}=#{value.inspect}" }.join(' ')}>"
     end
     alias to_s inspect
 
     private
 
+    def table
+      @table ||= {}
+    end
+
+    ##
+    # Handles dynamic method calls for attribute access and assignment.
+    # Getter methods return the stored value, setter methods (ending with =) store values.
+    #
+    # @param method_name [Symbol] the method name being called
+    # @param args [Array] arguments passed to the method
+    # @return [Object] the stored value for getters, the assigned value for setters
+    #
+    # @example Getter methods
+    #   struct.name        # Calls method_missing(:name)
+    #   struct.undefined   # Calls method_missing(:undefined) => nil
+    #
+    # @example Setter methods
+    #   struct.name = "John"  # Calls method_missing(:name=, "John")
+    #
+    # @api private
     def method_missing(method_name, *args, **_kwargs, &)
-      @table.fetch(method_name.to_sym) do
+      table.fetch(symbolized_key(method_name)) do
         store!(method_name[0..-2], args.first) if method_name.end_with?("=")
       end
     end
 
+    ##
+    # Determines if the struct responds to a given method name.
+    # Returns true for any key in the internal table or standard methods.
+    #
+    # @param method_name [Symbol] the method name to check
+    # @param include_private [Boolean] whether to include private methods
+    # @return [Boolean] true if the struct responds to the method
+    #
+    # @example
+    #   struct = LazyStruct.new(name: "John")
+    #   struct.respond_to?(:name)     #=> true
+    #   struct.respond_to?(:missing)  #=> false
+    #   struct.respond_to?(:to_h)     #=> true
+    #
+    # @api private
     def respond_to_missing?(method_name, include_private = false)
-      @table.key?(method_name.to_sym) || super
+      table.key?(symbolized_key(method_name)) || super
+    end
+
+    ##
+    # Converts a key to a symbol for consistent internal storage.
+    # This method normalizes all keys to symbols regardless of their input type,
+    # ensuring consistent access patterns throughout the LazyStruct.
+    #
+    # @param key [Object] the key to convert to a symbol
+    # @return [Symbol] the key converted to a symbol
+    # @raise [TypeError] if the key cannot be converted to a symbol (doesn't respond to `to_sym`)
+    #
+    # @example Valid key conversion
+    #   symbolized_key("name")    #=> :name
+    #   symbolized_key(:name)     #=> :name
+    #   symbolized_key("123")     #=> :"123"
+    #
+    # @example Invalid key conversion
+    #   symbolized_key(Object.new)  #=> raises TypeError
+    #   symbolized_key(123)         #=> raises TypeError
+    #
+    # @api private
+    def symbolized_key(key)
+      key.to_sym
+    rescue NoMethodError
+      raise TypeError, "#{key} is not a symbol nor a string"
     end
 
   end