cmdx 1.1.2 → 1.5.1

data/lib/cmdx/errors.rb

@@ -1,284 +1,74 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Container for collecting and managing validation and execution errors by attribute.
-  # Provides a comprehensive API for adding, querying, and formatting error messages
-  # with support for multiple errors per attribute and various output formats.
+  # Collection of validation and execution errors organized by attribute.
+  # Provides methods to add, query, and format error messages for different
+  # attributes in a task or workflow execution.
   class Errors
 
-    cmdx_attr_delegator :clear, :delete, :empty?, :key?, :keys, :size, :values,
-                        to: :errors
+    extend Forwardable
 
-    # @return [Hash] internal hash storing error messages by attribute
-    attr_reader :errors
+    attr_reader :messages
 
-    # @return [Array<Symbol>] list of attributes that have errors
-    alias attribute_names keys
+    def_delegators :messages, :empty?
 
-    # @return [Boolean] true if no errors are present
-    alias blank? empty?
-
-    # @return [Boolean] true if no errors are present
-    alias valid? empty?
-
-    # Alias for {#key?}. Checks if an attribute has error messages.
-    alias has_key? key?
-
-    # Alias for {#key?}. Checks if an attribute has error messages.
-    alias include? key?
-
-    # Creates a new empty errors collection.
-    #
-    # @return [Errors] a new errors instance with empty internal hash
-    #
-    # @example Create new errors collection
-    #   errors = CMDx::Errors.new
-    #   errors.empty? # => true
+    # Initialize a new error collection.
     def initialize
-      @errors = {}
-    end
-
-    # Adds an error message to the specified attribute. Automatically handles
-    # array initialization and prevents duplicate messages for the same attribute.
-    #
-    # @param key [Symbol, String] the attribute name to associate the error with
-    # @param value [String, Object] the error message or error object to add
-    #
-    # @return [Array] the updated array of error messages for the attribute
-    #
-    # @example Add error to attribute
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:name, "is too short")
-    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
-    #
-    # @example Prevent duplicate errors
-    #   errors.add(:email, "is invalid")
-    #   errors.add(:email, "is invalid")
-    #   errors.messages_for(:email) # => ["is invalid"]
-    def add(key, value)
-      errors[key] ||= []
-      errors[key] << value
-      errors[key].uniq!
+      @messages = {}
     end
-    alias []= add
 
-    # Checks if a specific error message has been added to an attribute.
-    #
-    # @param key [Symbol, String] the attribute name to check
-    # @param val [String, Object] the error message to look for
-    #
-    # @return [Boolean] true if the error exists for the attribute, false otherwise
-    #
-    # @example Check for specific error
-    #   errors.add(:name, "can't be blank")
-    #   errors.added?(:name, "can't be blank") # => true
-    #   errors.added?(:name, "is invalid") # => false
-    #
-    # @example Check non-existent attribute
-    #   errors.added?(:nonexistent, "error") # => false
-    def added?(key, val)
-      return false unless key?(key)
-
-      errors[key].include?(val)
-    end
-    alias of_kind? added?
-
-    # Iterates over each error, yielding the attribute name and error message.
-    #
-    # @yield [key, value] gives the attribute name and error message for each error
-    # @yieldparam key [Symbol, String] the attribute name
-    # @yieldparam value [String, Object] the error message
-    #
-    # @return [Hash] the errors hash when no block given
-    #
-    # @example Iterate over all errors
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:email, "is invalid")
-    #   errors.each { |attr, msg| puts "#{attr}: #{msg}" }
-    #   # Output:
-    #   # name: can't be blank
-    #   # email: is invalid
-    def each
-      errors.each_key do |key|
-        errors[key].each { |val| yield(key, val) }
-      end
-    end
-
-    # Formats an error message by combining the attribute name and error value.
-    #
-    # @param key [Symbol, String] the attribute name
-    # @param value [String, Object] the error message
-    #
-    # @return [String] the formatted full error message
-    #
-    # @example Format error message
-    #   errors.full_message(:name, "can't be blank") # => "name can't be blank"
-    #   errors.full_message(:email, "is invalid") # => "email is invalid"
-    def full_message(key, value)
-      "#{key} #{value}"
-    end
-
-    # Returns all error messages formatted with their attribute names.
-    #
-    # @return [Array<String>] array of formatted error messages
+    # Add an error message for a specific attribute.
     #
-    # @example Get all formatted messages
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:email, "is invalid")
-    #   errors.full_messages # => ["name can't be blank", "email is invalid"]
+    # @param attribute [Symbol] The attribute name associated with the error
+    # @param message [String] The error message to add
     #
-    # @example Empty errors collection
-    #   errors.full_messages # => []
-    def full_messages
-      errors.each_with_object([]) do |(key, arr), memo|
-        arr.each { |val| memo << full_message(key, val) }
-      end
-    end
-    alias to_a full_messages
-
-    # Returns formatted error messages for a specific attribute.
-    #
-    # @param key [Symbol, String] the attribute name to get messages for
-    #
-    # @return [Array<String>] array of formatted error messages for the attribute
-    #
-    # @example Get messages for existing attribute
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:name, "is too short")
-    #   errors.full_messages_for(:name) # => ["name can't be blank", "name is too short"]
-    #
-    # @example Get messages for non-existent attribute
-    #   errors.full_messages_for(:nonexistent) # => []
-    def full_messages_for(key)
-      return [] unless key?(key)
-
-      errors[key].map { |val| full_message(key, val) }
-    end
-
-    # Checks if the errors collection contains any validation errors.
-    #
-    # @return [Boolean] true if there are any errors present, false otherwise
-    #
-    # @example Check invalid state
-    #   errors.add(:name, "can't be blank")
-    #   errors.invalid? # => true
-    #
-    # @example Check valid state
-    #   errors.invalid? # => false
-    def invalid?
-      !valid?
-    end
-
-    # Transforms each error using the provided block and returns results as an array.
-    #
-    # @yield [key, value] gives the attribute name and error message for transformation
-    # @yieldparam key [Symbol, String] the attribute name
-    # @yieldparam value [String, Object] the error message
-    # @yieldreturn [Object] the transformed value to include in result array
-    #
-    # @return [Array] array of transformed error values
-    #
-    # @example Transform errors to uppercase messages
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:email, "is invalid")
-    #   errors.map { |attr, msg| msg.upcase } # => ["CAN'T BE BLANK", "IS INVALID"]
-    #
-    # @example Create custom error objects
-    #   errors.map { |attr, msg| { attribute: attr, message: msg } }
-    #   # => [{ attribute: :name, message: "can't be blank" }]
-    def map
-      errors.each_with_object([]) do |(key, _arr), memo|
-        memo.concat(errors[key].map { |val| yield(key, val) })
-      end
-    end
+    # @example
+    #   errors = CMDx::Errors.new
+    #   errors.add(:email, "must be valid format")
+    #   errors.add(:email, "cannot be blank")
+    def add(attribute, message)
+      return if message.empty?
 
-    # Merges another errors hash into this collection, combining arrays for duplicate keys.
-    #
-    # @param hash [Hash] hash of errors to merge, with attribute keys and message arrays as values
-    #
-    # @return [Hash] the updated internal errors hash
-    #
-    # @example Merge additional errors
-    #   errors.add(:name, "can't be blank")
-    #   other_errors = { email: ["is invalid"], name: ["is too short"] }
-    #   errors.merge!(other_errors)
-    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
-    #   errors.messages_for(:email) # => ["is invalid"]
-    #
-    # @example Merge with duplicate prevention
-    #   errors.add(:name, "can't be blank")
-    #   duplicate_errors = { name: ["can't be blank", "is required"] }
-    #   errors.merge!(duplicate_errors)
-    #   errors.messages_for(:name) # => ["can't be blank", "is required"]
-    def merge!(hash)
-      errors.merge!(hash) do |_, arr1, arr2|
-        arr3 = arr1 + arr2
-        arr3.uniq!
-        arr3
-      end
+      messages[attribute] ||= Set.new
+      messages[attribute] << message
     end
 
-    # Returns the raw error messages for a specific attribute without formatting.
-    #
-    # @param key [Symbol, String] the attribute name to get messages for
+    # Check if there are any errors for a specific attribute.
     #
-    # @return [Array] array of raw error messages for the attribute
+    # @param attribute [Symbol] The attribute name to check for errors
     #
-    # @example Get raw messages for existing attribute
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:name, "is too short")
-    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
+    # @return [Boolean] true if the attribute has errors, false otherwise
     #
-    # @example Get messages for non-existent attribute
-    #   errors.messages_for(:nonexistent) # => []
-    def messages_for(key)
-      return [] unless key?(key)
+    # @example
+    #   errors.for?(:email) # => true
+    #   errors.for?(:name)  # => false
+    def for?(attribute)
+      return false unless messages.key?(attribute)
 
-      errors[key]
+      !messages[attribute].empty?
     end
-    alias [] messages_for
 
-    # Checks if the errors collection contains any validation errors.
+    # Convert errors to a hash format with arrays of messages.
     #
-    # @return [Boolean] true if there are any errors present, false otherwise
+    # @return [Hash{Symbol => Array<String>}] Hash with attribute keys and message arrays
     #
-    # @example Check for errors presence
-    #   errors.add(:name, "can't be blank")
-    #   errors.present? # => true
-    #
-    # @example Check empty collection
-    #   errors.present? # => false
-    def present?
-      !blank?
+    # @example
+    #   errors.to_h # => { email: ["must be valid format", "cannot be blank"] }
+    def to_h
+      messages.transform_values(&:to_a)
     end
 
-    # Converts the errors collection to a hash format, optionally with full formatted messages.
-    #
-    # @param full_messages [Boolean] whether to format messages with attribute names
+    # Convert errors to a human-readable string format.
     #
-    # @return [Hash] hash representation of errors
-    # @option return [Array<String>] attribute_name array of error messages (raw or formatted)
+    # @return [String] Formatted error messages joined with periods
     #
-    # @example Get raw errors hash
-    #   errors.add(:name, "can't be blank")
-    #   errors.add(:email, "is invalid")
-    #   errors.to_hash # => { :name => ["can't be blank"], :email => ["is invalid"] }
-    #
-    # @example Get formatted errors hash
-    #   errors.to_hash(true) # => { :name => ["name can't be blank"], :email => ["email is invalid"] }
-    #
-    # @example Empty errors collection
-    #   errors.to_hash # => {}
-    def to_hash(full_messages = false)
-      return errors unless full_messages
-
-      errors.each_with_object({}) do |(key, arr), memo|
-        memo[key] = arr.map { |val| full_message(key, val) }
-      end
+    # @example
+    #   errors.to_s # => "email must be valid format. email cannot be blank"
+    def to_s
+      messages.each_with_object([]) do |(attribute, messages), memo|
+        messages.each { |message| memo << "#{attribute} #{message}" }
+      end.join(". ")
     end
-    alias messages to_hash
-    alias group_by_attribute to_hash
-    alias as_json to_hash
 
   end
 end

data/lib/cmdx/exceptions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CMDx
+
+  # Base exception class for all CMDx-related errors.
+  #
+  # This serves as the root exception class for all errors raised by the CMDx
+  # framework. It inherits from StandardError and provides a common base for
+  # handling CMDx-specific exceptions.
+  Error = Class.new(StandardError)
+
+  # Raised when attribute coercion fails during task execution.
+  #
+  # This error occurs when a attribute value cannot be converted to the expected
+  # type using the registered coercion handlers. It indicates that the provided
+  # value is incompatible with the attribute's defined type.
+  CoercionError = Class.new(Error)
+
+  # Raised when a deprecated task is used.
+  #
+  # This error occurs when a deprecated task is called. It indicates that the
+  # task is no longer supported and should be replaced with a newer alternative.
+  DeprecationError = Class.new(Error)
+
+  # Raised when an abstract method is called without being implemented.
+  #
+  # This error occurs when a subclass fails to implement required abstract
+  # methods such as 'task' in tasks. It indicates incomplete implementation
+  # of required functionality.
+  UndefinedMethodError = Class.new(Error)
+
+  # Raised when attribute validation fails during task execution.
+  #
+  # This error occurs when a attribute value doesn't meet the validation criteria
+  # defined by the validator. It indicates that the provided value violates
+  # business rules or data integrity constraints.
+  ValidationError = Class.new(Error)
+
+end

data/lib/cmdx/faults.rb

@@ -2,55 +2,94 @@
 
 module CMDx
 
+  # Base fault class for handling task execution failures and interruptions.
+  #
+  # Faults represent error conditions that occur during task execution, providing
+  # a structured way to handle and categorize different types of failures.
+  # Each fault contains a reference to the result object that caused the fault.
+  class Fault < Error
+
+    extend Forwardable
+
+    attr_reader :result
+
+    def_delegators :result, :task, :context, :chain
+
+    # Initialize a new fault with the given result.
+    #
+    # @param result [Result] the result object that caused this fault
+    #
+    # @raise [ArgumentError] if result is nil or invalid
+    #
+    # @example
+    #   fault = Fault.new(task_result)
+    #   fault.result.reason # => "Task validation failed"
+    def initialize(result)
+      @result = result
+
+      super(result.reason)
+    end
+
+    class << self
+
+      # Create a fault class that matches specific task types.
+      #
+      # @param tasks [Array<Class>] array of task classes to match against
+      #
+      # @return [Class] a new fault class that matches the specified tasks
+      #
+      # @example
+      #   Fault.for?(UserTask, AdminUserTask)
+      #   # => true if fault.task is a UserTask or AdminUserTask
+      def for?(*tasks)
+        temp_fault = Class.new(self) do
+          def self.===(other)
+            other.is_a?(superclass) && @tasks.any? { |task| other.task.is_a?(task) }
+          end
+        end
+
+        temp_fault.tap { |c| c.instance_variable_set(:@tasks, tasks) }
+      end
+
+      # Create a fault class that matches based on a custom block.
+      #
+      # @param block [Proc] block that determines if a fault matches
+      #
+      # @return [Class] a new fault class that matches based on the block
+      #
+      # @raise [ArgumentError] if no block is provided
+      #
+      # @example
+      #   Fault.matches? { |fault| fault.result.metadata[:critical] }
+      #   # => true if fault has critical metadata
+      def matches?(&block)
+        raise ArgumentError, "block required" unless block_given?
+
+        temp_fault = Class.new(self) do
+          def self.===(other)
+            other.is_a?(superclass) && @block.call(other)
+          end
+        end
+
+        temp_fault.tap { |c| c.instance_variable_set(:@block, block) }
+      end
+
+    end
+
+  end
+
   # Fault raised when a task is intentionally skipped during execution.
   #
   # This fault occurs when a task determines it should not execute based on
   # its current context or conditions. Skipped tasks are not considered failures
   # but rather intentional bypasses of task execution logic.
-  #
-  # @example Task that skips based on conditions
-  #   class ProcessPaymentTask < CMDx::Task
-  #     def call
-  #       skip!(reason: "Payment already processed") if payment_exists?
-  #     end
-  #   end
-  #
-  #   result = ProcessPaymentTask.call(payment_id: 123)
-  #   # raises CMDx::Skipped when payment already exists
-  #
-  # @example Catching skipped faults
-  #   begin
-  #     MyTask.call!(data: "invalid")
-  #   rescue CMDx::Skipped => e
-  #     puts "Task was skipped: #{e.message}"
-  #   end
-  Skipped = Class.new(Fault)
+  SkipFault = Class.new(Fault)
 
   # Fault raised when a task execution fails due to errors or validation failures.
   #
   # This fault occurs when a task encounters an error condition, validation failure,
   # or any other condition that prevents successful completion. Failed tasks indicate
   # that the intended operation could not be completed successfully.
-  #
-  # @example Task that fails due to validation
-  #   class ValidateUserTask < CMDx::Task
-  #     required :email, type: :string
-  #
-  #     def call
-  #       fail!(reason: "Invalid email format") unless valid_email?
-  #     end
-  #   end
-  #
-  #   result = ValidateUserTask.call(email: "invalid-email")
-  #   # raises CMDx::Failed when email is invalid
-  #
-  # @example Catching failed faults
-  #   begin
-  #     RiskyTask.call!(data: "problematic")
-  #   rescue CMDx::Failed => e
-  #     puts "Task failed: #{e.message}"
-  #     puts "Original task: #{e.task.class.name}"
-  #   end
-  Failed = Class.new(Fault)
+  FailFault = Class.new(Fault)
 
 end

data/lib/cmdx/freezer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Provides freezing functionality for CMDx tasks and their associated objects.
+  #
+  # The Freezer module is responsible for making task objects immutable after execution
+  # to prevent accidental modifications and ensure data integrity. It can be disabled
+  # via environment variable for testing or debugging purposes.
+  module Freezer
+
+    extend self
+
+    # Freezes a task and its associated objects to prevent modifications.
+    #
+    # This method makes the task, result, context, and chain immutable after execution.
+    # Freezing can be skipped by setting the SKIP_CMDX_FREEZING environment variable.
+    #
+    # @param task [Task] The task instance to freeze
+    # @option ENV["SKIP_CMDX_FREEZING"] [String, Boolean] Set to "true" or true to skip freezing
+    #
+    # @raise [RuntimeError] If attempting to stub on frozen objects
+    #
+    # @example Freeze a completed task
+    #   task = MyTask.new
+    #   task.execute
+    #   CMDx::Freezer.immute(task)
+    #   # task, result, context, and chain are now frozen
+    # @example Skip freezing for testing
+    #   ENV["SKIP_CMDX_FREEZING"] = "true"
+    #   CMDx::Freezer.immute(task)
+    #   # No freezing occurs
+    def immute(task)
+      # Stubbing on frozen objects is not allowed
+      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
+      return if Coercions::Boolean.call(skip_freezing)
+
+      task.freeze
+      task.result.freeze
+
+      # Freezing the context and chain can only be done
+      # once the outer-most task has completed.
+      return unless task.result.index.zero?
+
+      task.context.freeze
+      task.chain.freeze
+
+      Chain.clear
+    end
+
+  end
+end

data/lib/cmdx/identifier.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Generates unique identifiers for tasks, workflows, and other CMDx components.
+  #
+  # The Identifier module provides a consistent way to generate unique identifiers
+  # across the CMDx system, with fallback support for different Ruby versions.
+  module Identifier
+
+    extend self
+
+    # Generates a unique identifier string.
+    #
+    # @return [String] A unique identifier string (UUID v7 if available, otherwise UUID v4)
+    #
+    # @raise [StandardError] If SecureRandom is unavailable or fails to generate an identifier
+    #
+    # @example Generate a unique identifier
+    #   CMDx::Identifier.generate
+    #   # => "01890b2c-1234-5678-9abc-def123456789"
+    def generate
+      if SecureRandom.respond_to?(:uuid_v7)
+        SecureRandom.uuid_v7
+      else
+        SecureRandom.uuid
+      end
+    end
+
+  end
+end

data/lib/cmdx/locale.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Provides internationalization and localization support for CMDx.
+  # Handles translation lookups with fallback to default English messages
+  # when I18n gem is not available.
+  module Locale
+
+    extend self
+
+    EN = YAML.load_file(CMDx.gem_path.join("lib/locales/en.yml")).freeze
+    private_constant :EN
+
+    # Translates a key to the current locale with optional interpolation.
+    # Falls back to English translations if I18n gem is unavailable.
+    #
+    # @param key [String, Symbol] The translation key (supports dot notation)
+    # @param options [Hash] Translation options
+    # @option options [String] :default Fallback message if translation missing
+    # @option options [String] :locale Target locale (when I18n available)
+    # @option options [Hash] :scope Translation scope (when I18n available)
+    # @option options [Object] :* Any other options passed to I18n.t or string interpolation
+    #
+    # @return [String] The translated message
+    #
+    # @raise [ArgumentError] When interpolation fails due to missing keys
+    #
+    # @example Basic translation
+    #   Locale.translate("errors.invalid_input")
+    #   # => "Invalid input provided"
+    # @example With interpolation
+    #   Locale.translate("welcome.message", name: "John")
+    #   # => "Welcome, John!"
+    # @example With fallback
+    #   Locale.translate("missing.key", default: "Custom fallback message")
+    #   # => "Custom fallback message"
+    def translate(key, **options)
+      options[:default] ||= EN.dig("en", *key.to_s.split("."))
+      return ::I18n.t(key, **options) if defined?(::I18n)
+
+      case message = options.delete(:default)
+      when NilClass then "Translation missing: #{key}"
+      when String then message % options
+      else message
+      end
+    end
+
+    # @see #translate
+    alias t translate
+
+  end
+end