cmdx 1.1.1 → 1.5.0

data/lib/cmdx/chain_serializer.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Serialization module for converting chain objects to hash representation.
-  #
-  # ChainSerializer provides functionality to serialize chain objects into a
-  # standardized hash format that includes essential metadata about the chain
-  # execution including unique identification, execution state, status, outcome,
-  # runtime, and all contained task results. The serialized format is commonly
-  # used for debugging, logging, introspection, and data exchange throughout
-  # the task execution pipeline.
-  module ChainSerializer
-
-    module_function
-
-    # Serializes a chain object into a hash representation.
-    #
-    # Converts a chain instance into a standardized hash format containing
-    # key metadata about the chain's execution context and all contained results.
-    # The serialization includes information delegated from the first result in
-    # the chain (state, status, outcome, runtime) along with the chain's unique
-    # identifier and complete collection of task results converted to hashes.
-    #
-    # @param chain [CMDx::Chain] the chain object to serialize
-    #
-    # @return [Hash] a hash containing the chain's metadata and execution information
-    # @option return [String] :id the unique identifier of the chain
-    # @option return [String] :state the execution state delegated from first result
-    # @option return [String] :status the execution status delegated from first result
-    # @option return [String] :outcome the execution outcome delegated from first result
-    # @option return [Float] :runtime the execution runtime in seconds delegated from first result
-    # @option return [Array<Hash>] :results array of serialized result hashes from all tasks in the chain
-    #
-    # @raise [NoMethodError] if the chain doesn't respond to required methods (id, state, status, outcome, runtime, results)
-    #
-    # @example Serialize a workflow chain with multiple tasks
-    #   workflow = DataProcessingWorkflow.call(input: "data")
-    #   ChainSerializer.call(workflow.chain)
-    #   #=> {
-    #   #   id: "def456",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   runtime: 0.123,
-    #   #   results: [
-    #   #     { index: 0, class: "ValidateDataTask", status: "success", ... },
-    #   #     { index: 1, class: "ProcessDataTask", status: "success", ... },
-    #   #     { index: 2, class: "SaveDataTask", status: "success", ... }
-    #   #   ]
-    #   # }
-    def call(chain)
-      {
-        id: chain.id,
-        state: chain.state,
-        status: chain.status,
-        outcome: chain.outcome,
-        runtime: chain.runtime,
-        results: chain.results.map(&:to_h)
-      }
-    end
-
-  end
-end

data/lib/cmdx/coercion.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Base class for implementing parameter coercion functionality in task processing.
-  #
-  # Coercions are used to convert parameter values from one type to another during
-  # task execution, enabling automatic type conversion and normalization. All coercion
-  # implementations must inherit from this class and implement the abstract call method.
-  class Coercion
-
-    # Executes a coercion by creating a new instance and calling it.
-    #
-    # @param value [Object] the value to be coerced
-    # @param options [Hash] additional options for the coercion
-    #
-    # @return [Object] the coerced value
-    #
-    # @raise [UndefinedCallError] when the coercion subclass doesn't implement call
-    # @raise [CoercionError] when coercion fails in subclass implementations
-    #
-    # @example Execute a coercion on a value
-    #   StringCoercion.call(123) #=> "123"
-    #
-    # @example Execute with options
-    #   CustomCoercion.call("value", strict: true) #=> processed_value
-    def self.call(value, options = {})
-      new.call(value, options)
-    end
-
-    # Abstract method that must be implemented by coercion subclasses.
-    #
-    # This method contains the actual coercion logic to convert the input
-    # value to the desired type. Subclasses must override this method
-    # to provide their specific coercion implementation.
-    #
-    # @param value [Object] the value to be coerced (unused in base class)
-    # @param options [Hash] additional options for the coercion (unused in base class)
-    #
-    # @return [Object] the coerced value
-    #
-    # @raise [UndefinedCallError] always raised in the base class
-    # @raise [CoercionError] when coercion fails in subclass implementations
-    #
-    # @example Implement in a subclass
-    #   class StringCoercion < CMDx::Coercion
-    #     def call(value, _options = {})
-    #       String(value)
-    #     rescue ArgumentError, TypeError
-    #       raise CoercionError, "could not coerce into a string"
-    #     end
-    #   end
-    def call(value, options = {}) # rubocop:disable Lint/UnusedMethodArgument
-      raise UndefinedCallError, "call method not defined in #{self.class.name}"
-    end
-
-  end
-end

data/lib/cmdx/coercions/virtual.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Coercions
-    # Coercion class for virtual values that performs no conversion.
-    #
-    # 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
-
-      # Returns the given value unchanged.
-      #
-      # @param value [Object] the value to return as-is
-      # @param _options [Hash] optional configuration (currently unused)
-      #
-      # @return [Object] the original value without any conversion
-      #
-      # @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
-
-    end
-  end
-end

data/lib/cmdx/core_ext/hash.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module CoreExt
-    # 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
-
-      # Fetches a value from the hash with flexible key matching.
-      # Tries the exact key first, then attempts symbol/string conversion if not found.
-      #
-      # @param key [Symbol, String, Object] the key to fetch from the hash
-      #
-      # @return [Object, nil] the value associated with the key, or nil if not found
-      #
-      # @example Fetch with symbol key
-      #   hash = { name: "John", "age" => 30 }
-      #   hash.cmdx_fetch(:name) #=> "John"
-      #   hash.cmdx_fetch(:age)  #=> 30
-      #
-      # @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] }
-        else self[key]
-        end
-      end
-
-      # Checks if a key exists in the hash with flexible key matching.
-      # Tries the exact key first, then attempts symbol/string conversion.
-      #
-      # @param key [Symbol, String, Object] the key to check for existence
-      #
-      # @return [Boolean] true if the key exists (in any form), false otherwise
-      #
-      # @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
-          when String then key.to_sym
-          end
-        )
-      rescue NoMethodError
-        false
-      end
-
-      # Checks if the hash responds to a method or contains a key.
-      # Combines method existence checking with flexible key existence checking.
-      #
-      # @param key [Symbol, String] the method name or key to check
-      # @param include_private [Boolean] whether to include private methods in the check
-      #
-      # @return [Boolean] true if the hash responds to the method or contains the 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)
-      end
-
-    end
-  end
-end
-
-Hash.include(CMDx::CoreExt::HashExtensions)

data/lib/cmdx/core_ext/module.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module CoreExt
-    # Extensions for Ruby's Module class that provide attribute delegation and settings functionality.
-    # These extensions are automatically included in all modules when CMDx is loaded.
-    module ModuleExtensions
-
-      # Creates delegated methods that forward calls to another object or class.
-      # Supports method name prefixing, privacy levels, and optional method existence checking.
-      #
-      # @param methods [Array<Symbol>] the method names to delegate
-      # @param options [Hash] delegation options
-      # @option options [Symbol] :to the target object or :class to delegate to
-      # @option options [Boolean] :allow_missing (false) whether to allow delegation to non-existent methods
-      # @option options [Boolean] :protected (false) whether to make the delegated method protected
-      # @option options [Boolean] :private (false) whether to make the delegated method private
-      # @option options [String, Symbol] :prefix optional prefix for the delegated method name
-      # @option options [String, Symbol] :suffix optional suffix for the delegated method name
-      #
-      # @return [void]
-      # @raise [NoMethodError] when delegating to a non-existent method and :allow_missing is false
-      #
-      # @example Delegate methods to an instance variable
-      #   class Task
-      #     def initialize
-      #       @logger = Logger.new
-      #     end
-      #
-      #     cmdx_attr_delegator :info, :warn, :error, to: :@logger
-      #   end
-      #
-      # @example Delegate with prefix and privacy
-      #   class Workflow
-      #     cmdx_attr_delegator :perform, to: :task, prefix: 'execute_', private: true
-      #   end
-      def cmdx_attr_delegator(*methods, **options)
-        methods.each do |method|
-          method_name = Utils::NameAffix.call(method, options.fetch(:to), options)
-
-          define_method(method_name) do |*args, **kwargs, &block|
-            object = (options[:to] == :class ? self.class : send(options[:to]))
-
-            unless options[:allow_missing] || object.respond_to?(method, true)
-              raise NoMethodError,
-                    "undefined method `#{method}' for #{options[:to]}"
-            end
-
-            object.send(method, *args, **kwargs, &block)
-          end
-
-          case options
-          in { protected: true } then send(:protected, method_name)
-          in { private: true } then send(:private, method_name)
-          else # Leave public
-          end
-        end
-      end
-
-      # Creates a singleton method for accessing inheritable settings with caching and default values.
-      # Settings are inherited from superclass and can have default values via blocks or static values.
-      #
-      # @param method [Symbol] the name of the setting method to create
-      # @param options [Hash] setting options
-      # @option options [Object, Proc] :default the default value or a proc that returns the default value
-      #
-      # @return [void]
-      #
-      # @example Define a setting with a default value
-      #   class BaseTask
-      #     cmdx_attr_setting :timeout, default: 30
-      #   end
-      #
-      #   BaseTask.timeout #=> 30
-      #
-      # @example Define a setting with a dynamic default
-      #   class Task
-      #     cmdx_attr_setting :retry_count, default: -> { ENV['RETRY_COUNT']&.to_i || 3 }
-      #   end
-      def cmdx_attr_setting(method, **options)
-        define_singleton_method(method) do
-          @cmd_facets ||= {}
-          return @cmd_facets[method] if @cmd_facets.key?(method)
-
-          value = superclass.cmdx_try(method)
-          return @cmd_facets[method] = value.dup unless value.nil?
-
-          default = options[:default]
-          value   = default.cmdx_call
-          @cmd_facets[method] = default.is_a?(Proc) ? value : value.dup
-        end
-      end
-
-    end
-  end
-end
-
-Module.include(CMDx::CoreExt::ModuleExtensions)

data/lib/cmdx/core_ext/object.rb

@@ -1,125 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module CoreExt
-    # Extensions for Ruby's Object class that provide flexible method calling and evaluation utilities.
-    # These extensions are automatically included in all objects when CMDx is loaded, providing
-    # safe method invocation, conditional evaluation, and dynamic yielding capabilities.
-    module ObjectExtensions
-
-      alias cmdx_respond_to? respond_to?
-
-      # Safely tries to call a method, evaluate a proc, or access a hash key.
-      # Provides flexible invocation that handles different types of callables gracefully.
-      #
-      # @param key [Symbol, String, Proc, Object] the method name, proc, or hash key to try
-      # @param args [Array] arguments to pass to the method or proc
-      #
-      # @return [Object, nil] the result of the method call, proc evaluation, or hash access; nil if not found
-      #
-      # @example Try calling a method
-      #   "hello".cmdx_try(:upcase) #=> "HELLO"
-      #   "hello".cmdx_try(:missing) #=> nil
-      #
-      # @example Try evaluating a proc
-      #   obj.cmdx_try(-> { self.class.name }) #=> "String"
-      #
-      # @example Try accessing a hash key
-      #   {name: "John"}.cmdx_try(:name) #=> "John"
-      def cmdx_try(key, *args, **kwargs, &)
-        if key.is_a?(Proc)
-          return instance_eval(&key) unless is_a?(Module) || key.inspect.include?("(lambda)")
-
-          if key.arity.positive? && args.empty?
-            key.call(self, *args, **kwargs, &)
-          else
-            key.call(*args, **kwargs, &)
-          end
-        elsif respond_to?(key, true)
-          send(key, *args, **kwargs, &)
-        elsif is_a?(Hash)
-          cmdx_fetch(key)
-        end
-      end
-
-      # Evaluates conditional options using :if and :unless logic.
-      # Supports both method names and procs for conditional evaluation.
-      #
-      # @param options [Hash] evaluation options
-      # @option options [Symbol, Proc] :if condition that must be truthy
-      # @option options [Symbol, Proc] :unless condition that must be falsy
-      # @option options [Object] :default (true) default value when no conditions are specified
-      #
-      # @return [Boolean] true if conditions are met, false otherwise
-      #
-      # @example Evaluate with if condition
-      #   user.cmdx_eval(if: :active?) #=> true if user.active? is truthy
-      #
-      # @example Evaluate with unless condition
-      #   user.cmdx_eval(unless: :banned?) #=> true if user.banned? is falsy
-      #
-      # @example Evaluate with both conditions
-      #   user.cmdx_eval(if: :active?, unless: :banned?) #=> true if active and not banned
-      def cmdx_eval(options = {})
-        if options[:if] && options[:unless]
-          cmdx_try(options[:if]) && !cmdx_try(options[:unless])
-        elsif options[:if]
-          cmdx_try(options[:if])
-        elsif options[:unless]
-          !cmdx_try(options[:unless])
-        else
-          options.fetch(:default, true)
-        end
-      end
-
-      # Yields or returns a value based on its type, with smart method calling.
-      # Handles symbols/strings as method names, procs/hashes via cmdx_try, and returns other values as-is.
-      #
-      # @param key [Symbol, String, Proc, Hash, Object] the value to yield or method to call
-      # @param args [Array] arguments to pass to method calls
-      #
-      # @return [Object] the result of method call, proc evaluation, or the value itself
-      #
-      # @example Yield a method call
-      #   "hello".cmdx_yield(:upcase) #=> "HELLO"
-      #
-      # @example Yield a static value
-      #   obj.cmdx_yield("static") #=> "static"
-      #
-      # @example Yield a proc
-      #   obj.cmdx_yield(-> { Time.now }) #=> 2023-01-01 12:00:00 UTC
-      def cmdx_yield(key, ...)
-        if key.is_a?(Symbol) || key.is_a?(String)
-          return key unless respond_to?(key, true)
-
-          send(key, ...)
-        elsif is_a?(Hash) || key.is_a?(Proc)
-          cmdx_try(key, ...)
-        else
-          key
-        end
-      end
-
-      # Invokes the object if it responds to :call, otherwise returns the object itself.
-      # Useful for handling both callable and non-callable objects uniformly.
-      #
-      # @param args [Array] arguments to pass to the call method
-      #
-      # @return [Object] the result of calling the object, or the object itself if not callable
-      #
-      # @example Invoke a proc
-      #   proc { "hello" }.cmdx_call #=> "hello"
-      #
-      # @example Invoke a non-callable object
-      #   "hello".cmdx_call #=> "hello"
-      def cmdx_call(...)
-        return self unless respond_to?(:call)
-
-        call(...)
-      end
-
-    end
-  end
-end
-
-Object.include(CMDx::CoreExt::ObjectExtensions)

data/lib/cmdx/correlator.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Thread-safe correlation ID management for distributed tracing and request tracking.
-  #
-  # Correlator provides functionality to generate, store, and manage correlation IDs
-  # across thread boundaries for request tracing, logging correlation, and distributed
-  # system monitoring. Correlation IDs are stored in thread-local storage to ensure
-  # thread safety and isolation between concurrent operations.
-  module Correlator
-
-    THREAD_KEY = :cmdx_correlation_id
-
-    module_function
-
-    # Generates a new correlation ID using the best available UUID algorithm.
-    #
-    # Attempts to use UUID v7 (time-ordered) if available in Ruby 3.3+, otherwise
-    # falls back to standard UUID v4. UUID v7 provides better database indexing
-    # performance and natural time-based ordering for correlation tracking.
-    #
-    # @return [String] a new UUID correlation ID
-    #
-    # @example Generate a correlation ID
-    #   Correlator.generate #=> "01234567-89ab-7def-0123-456789abcdef"
-    #
-    # @example Using the generated ID for logging
-    #   correlation_id = Correlator.generate
-    #   logger.info "Request started", correlation_id: correlation_id
-    def generate
-      return SecureRandom.uuid_v7 if SecureRandom.respond_to?(:uuid_v7)
-
-      SecureRandom.uuid
-    end
-
-    # Retrieves the current correlation ID for the active thread.
-    #
-    # Returns the correlation ID that has been set for the current thread's
-    # execution context. Returns nil if no correlation ID has been established
-    # for the current thread.
-    #
-    # @return [String, nil] the current thread's correlation ID, or nil if not set
-    #
-    # @example Get current correlation ID
-    #   Correlator.id #=> "01234567-89ab-7def-0123-456789abcdef"
-    def id
-      Thread.current[THREAD_KEY]
-    end
-
-    # Sets the correlation ID for the current thread.
-    #
-    # Establishes a correlation ID in thread-local storage that will be
-    # accessible to all operations within the current thread's execution
-    # context. This ID will persist until explicitly changed or cleared.
-    #
-    # @param value [String, Symbol] the correlation ID to set for this thread
-    #
-    # @return [String, Symbol] the assigned correlation ID value
-    #
-    # @example Set a custom correlation ID
-    #   Correlator.id = "custom-trace-123"
-    #
-    # @example Set a generated correlation ID
-    #   Correlator.id = Correlator.generate
-    def id=(value)
-      Thread.current[THREAD_KEY] = value
-    end
-
-    # Clears the correlation ID for the current thread.
-    #
-    # Removes the correlation ID from thread-local storage, effectively
-    # resetting the correlation context for the current thread. Useful
-    # for cleanup between request processing or test scenarios.
-    #
-    # @return [nil] always returns nil after clearing
-    #
-    # @example Clear correlation ID
-    #   Correlator.clear
-    #   Correlator.id #=> nil
-    def clear
-      Thread.current[THREAD_KEY] = nil
-    end
-
-    # Temporarily sets a correlation ID for the duration of a block execution.
-    #
-    # Establishes a correlation ID context for the provided block, automatically
-    # restoring the previous correlation ID when the block completes. This ensures
-    # proper correlation ID isolation for nested operations or temporary contexts.
-    #
-    # @param value [String, Symbol] the temporary correlation ID to use during block execution
-    #
-    # @return [Object] the return value of the executed block
-    #
-    # @raise [TypeError] if the provided value is not a String or Symbol
-    #
-    # @example Use temporary correlation ID
-    #   Correlator.use("temp-id-123") do
-    #     logger.info "Processing with temporary ID"
-    #     perform_operation
-    #   end
-    #
-    # @example Nested correlation contexts
-    #   Correlator.id = "parent-id"
-    #   Correlator.use("child-id") do
-    #     puts Correlator.id #=> "child-id"
-    #   end
-    #   puts Correlator.id #=> "parent-id"
-    def use(value)
-      unless value.is_a?(String) || value.is_a?(Symbol)
-        raise TypeError,
-              "must be a String or Symbol"
-      end
-
-      previous_id = id
-      self.id = value
-      yield
-    ensure
-      self.id = previous_id
-    end
-
-  end
-end

data/lib/cmdx/error.rb

@@ -1,60 +0,0 @@
-# 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 parameter coercion fails during task execution.
-  #
-  # This error occurs when a parameter value cannot be converted to the expected
-  # type using the registered coercion handlers. It indicates that the provided
-  # value is incompatible with the parameter'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 call methods in validators, callbacks, or middleware. It indicates
-  # incomplete implementation of required functionality.
-  UndefinedCallError = Class.new(Error)
-
-  # Raised when attempting to use an unregistered callback.
-  #
-  # This error occurs when trying to reference a callback that hasn't been
-  # registered in the callback registry. It indicates that the callback name
-  # is not recognized or was misspelled.
-  UnknownCallbackError = Class.new(Error)
-
-  # Raised when attempting to use an unregistered coercion type.
-  #
-  # This error occurs when trying to use a parameter type that doesn't have
-  # a corresponding coercion handler registered. It indicates that the specified
-  # type is not supported by the coercion system.
-  UnknownCoercionError = Class.new(Error)
-
-  # Raised when attempting to use an unregistered validator.
-  #
-  # This error occurs when trying to reference a validator that hasn't been
-  # registered in the validator registry. It indicates that the validator name
-  # is not recognized or was misspelled.
-  UnknownValidatorError = Class.new(Error)
-
-  # Raised when parameter validation fails during task execution.
-  #
-  # This error occurs when a parameter 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