cmdx 1.21.0 → 2.0.0

data/lib/cmdx/coercion_registry.rb

@@ -1,138 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Registry for managing type coercion handlers.
-  #
-  # Provides a centralized way to register, deregister, and execute type coercions
-  # for various data types including arrays, numbers, dates, and other primitives.
-  #
-  # Supports copy-on-write semantics: a duped registry shares the parent's
-  # data until a write operation triggers materialization.
-  class CoercionRegistry
-
-    # Initialize a new coercion registry.
-    #
-    # @param registry [Hash{Symbol => Class}, nil] optional initial registry hash
-    #
-    # @example
-    #   registry = CoercionRegistry.new
-    #   registry = CoercionRegistry.new(custom: CustomCoercion)
-    #
-    # @rbs (?Hash[Symbol, Class]? registry) -> void
-    def initialize(registry = nil)
-      @registry = registry || {
-        array: Coercions::Array,
-        big_decimal: Coercions::BigDecimal,
-        boolean: Coercions::Boolean,
-        complex: Coercions::Complex,
-        date: Coercions::Date,
-        datetime: Coercions::DateTime,
-        float: Coercions::Float,
-        hash: Coercions::Hash,
-        integer: Coercions::Integer,
-        rational: Coercions::Rational,
-        string: Coercions::String,
-        time: Coercions::Time
-      }
-    end
-
-    # Sets up copy-on-write state when duplicated via dup.
-    #
-    # @param source [CoercionRegistry] The registry being duplicated
-    #
-    # @rbs (CoercionRegistry source) -> void
-    def initialize_dup(source)
-      @parent = source
-      @registry = nil
-      super
-    end
-
-    # Returns the internal registry mapping coercion types to handler classes.
-    # Delegates to the parent registry when not yet materialized.
-    #
-    # @return [Hash{Symbol => Class}] Hash of coercion type names to coercion classes
-    #
-    # @example
-    #   registry.registry # => { integer: Coercions::Integer, boolean: Coercions::Boolean }
-    #
-    # @rbs () -> Hash[Symbol, Class]
-    def registry
-      @registry || @parent.registry
-    end
-    alias to_h registry
-
-    # Register a new coercion handler for a type.
-    #
-    # @param name [Symbol, String] the type name to register
-    # @param coercion [Class] the coercion class to handle this type
-    #
-    # @return [CoercionRegistry] self for method chaining
-    #
-    # @example
-    #   registry.register(:custom_type, CustomCoercion)
-    #   registry.register("another_type", AnotherCoercion)
-    #
-    # @rbs ((Symbol | String) name, Class coercion) -> self
-    def register(name, coercion)
-      materialize!
-
-      @registry[name.to_sym] = coercion
-      self
-    end
-
-    # Remove a coercion handler for a type.
-    #
-    # @param name [Symbol, String] the type name to deregister
-    #
-    # @return [CoercionRegistry] self for method chaining
-    #
-    # @example
-    #   registry.deregister(:custom_type)
-    #   registry.deregister("another_type")
-    #
-    # @rbs ((Symbol | String) name) -> self
-    def deregister(name)
-      materialize!
-
-      @registry.delete(name.to_sym)
-      self
-    end
-
-    # Coerce a value to the specified type using the registered handler.
-    #
-    # @param type [Symbol] the type to coerce to
-    # @param task [Object] the task context for the coercion
-    # @param value [Object] the value to coerce
-    # @param options [Hash] additional options for the coercion
-    # @option options [Object] :* Any coercion option key-value pairs
-    #
-    # @return [Object] the coerced value
-    #
-    # @raise [TypeError] when the type is not registered
-    #
-    # @example
-    #   result = registry.coerce(:integer, task, "42")
-    #   result = registry.coerce(:boolean, task, "true", strict: true)
-    #
-    # @rbs (Symbol type, untyped task, untyped value, ?Hash[Symbol, untyped] options) -> untyped
-    def coerce(type, task, value, options = EMPTY_HASH)
-      raise TypeError, "unknown coercion type #{type.inspect}" unless registry.key?(type)
-
-      Utils::Call.invoke(task, registry[type], value, options)
-    end
-
-    private
-
-    # Copies the parent's registry data into this instance,
-    # severing the copy-on-write link.
-    #
-    # @rbs () -> void
-    def materialize!
-      return if @registry
-
-      @registry = @parent.registry.dup
-      @parent = nil
-    end
-
-  end
-end

data/lib/cmdx/deprecator.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Handles deprecation warnings and restrictions for tasks.
-  #
-  # The Deprecator module provides functionality to restrict usage of deprecated
-  # tasks based on configuration settings. It supports different deprecation
-  # behaviors including warnings, logging, and errors.
-  module Deprecator
-
-    extend self
-
-    # @rbs RAISE_REGEXP: Regexp
-    RAISE_REGEXP = /\Araise\z/
-    private_constant :RAISE_REGEXP
-
-    # @rbs LOG_REGEXP: Regexp
-    LOG_REGEXP = /\Alog\z/
-    private_constant :LOG_REGEXP
-
-    # @rbs WARN_REGEXP: Regexp
-    WARN_REGEXP = /\Awarn\z/
-    private_constant :WARN_REGEXP
-
-    # @rbs EVAL: Proc
-    EVAL = proc do |target, callable|
-      case callable
-      when NilClass, FalseClass, TrueClass then !!callable
-      when RAISE_REGEXP, LOG_REGEXP, WARN_REGEXP then callable
-      when Symbol then target.send(callable)
-      when Proc then target.instance_eval(&callable)
-      else
-        raise "cannot evaluate #{callable.inspect}" unless callable.respond_to?(:call)
-
-        callable.call(target)
-      end
-    end.freeze
-    private_constant :EVAL
-
-    # Restricts task usage based on deprecation settings.
-    #
-    # @param task [Object] The task object to check for deprecation
-    # @option task.class.settings.deprecate [Symbol, Proc, String, Boolean]
-    #   The deprecation configuration for the task
-    # @option task.class.settings.deprecate :raise Raises DeprecationError
-    # @option task.class.settings.deprecate :log Logs deprecation warning
-    # @option task.class.settings.deprecate :warn Outputs warning to stderr
-    # @option task.class.settings.deprecate true Raises DeprecationError
-    # @option task.class.settings.deprecate false No action taken
-    # @option task.class.settings.deprecate nil No action taken
-    #
-    # @raise [DeprecationError] When deprecation type is :raise or true
-    # @raise [RuntimeError] When deprecation type is unknown
-    #
-    # @example
-    #   class MyTask
-    #     settings(deprecate: :warn)
-    #   end
-    #
-    #   MyTask.new # => [MyTask] DEPRECATED: migrate to a replacement or discontinue use
-    #
-    # @rbs (Task task) -> void
-    def restrict(task)
-      setting = task.class.settings.deprecate
-      return unless setting
-
-      case type = EVAL.call(task, setting)
-      when NilClass, FalseClass then nil # Do nothing
-      when TrueClass, RAISE_REGEXP then raise DeprecationError, "#{task.class.name} usage prohibited"
-      when LOG_REGEXP then task.logger.warn { "DEPRECATED: migrate to a replacement or discontinue use" }
-      when WARN_REGEXP then warn("[#{task.class.name}] DEPRECATED: migrate to a replacement or discontinue use", category: :deprecated)
-      else raise "unknown deprecation type #{type.inspect}"
-      end
-    end
-
-  end
-end

data/lib/cmdx/exception.rb

@@ -1,46 +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.
-  Exception = 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)
-
-  # Error raised when task execution exceeds the configured timeout limit.
-  #
-  # This error occurs when a task takes longer to execute than the specified
-  # time limit. Timeout errors are raised by Ruby's Timeout module and are
-  # caught by the middleware to properly fail the task with timeout information.
-  TimeoutError = Class.new(Interrupt)
-
-  # 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/executor.rb

@@ -1,378 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Executes CMDx tasks with middleware support, error handling, and lifecycle management.
-  #
-  # The Executor class is responsible for orchestrating task execution, including
-  # pre-execution validation, execution with middleware, post-execution callbacks,
-  # and proper error handling for different types of failures.
-  class Executor
-
-    extend Forwardable
-
-    # @rbs STATE_CALLBACKS: Hash[String, Symbol]
-    STATE_CALLBACKS = Result::STATES.to_h { |s| [s, :"on_#{s}"] }.freeze
-    private_constant :STATE_CALLBACKS
-
-    # @rbs STATUS_CALLBACKS: Hash[String, Symbol]
-    STATUS_CALLBACKS = Result::STATUSES.to_h { |s| [s, :"on_#{s}"] }.freeze
-    private_constant :STATUS_CALLBACKS
-
-    # Returns the task being executed.
-    #
-    # @return [Task] The task instance
-    #
-    # @example
-    #   executor.task.id # => "abc123"
-    #
-    # @rbs @task: Task
-    attr_reader :task
-
-    def_delegators :task, :result
-
-    # @param task [CMDx::Task] The task to execute
-    #
-    # @return [CMDx::Executor] A new executor instance
-    #
-    # @example
-    #   executor = CMDx::Executor.new(my_task)
-    #
-    # @rbs (Task task) -> void
-    def initialize(task)
-      @task = task
-    end
-
-    # Executes a task with optional exception raising.
-    #
-    # @param task [CMDx::Task] The task to execute
-    # @param raise [Boolean] Whether to raise exceptions (default: false)
-    #
-    # @return [CMDx::Result] The execution result
-    #
-    # @raise [StandardError] When raise is true and execution fails
-    #
-    # @example
-    #   CMDx::Executor.execute(my_task)
-    #   CMDx::Executor.execute(my_task, raise: true)
-    #
-    # @rbs (Task task, raise: bool) -> Result
-    def self.execute(task, raise: false)
-      instance = new(task)
-      raise ? instance.execute! : instance.execute
-    end
-
-    # Executes the task with graceful error handling.
-    #
-    # @return [CMDx::Result] The execution result
-    #
-    # @example
-    #   executor = CMDx::Executor.new(my_task)
-    #   result = executor.execute
-    #
-    # @rbs () -> Result
-    def execute
-      task.class.settings.middlewares.call!(task) do
-        pre_execution! unless @pre_execution
-        execution!
-        verify_context_returns!
-      rescue UndefinedMethodError => e
-        raise_exception(e)
-      rescue Fault => e
-        result.throw!(e.result, halt: false, cause: e)
-      rescue StandardError => e
-        retry if retry_execution?(e)
-        result.fail!(Utils::Normalize.exception(e), halt: false, cause: e, source: :exception)
-        task.class.settings.exception_handler&.call(task, e)
-      ensure
-        result.executed!
-        post_execution!
-      end
-
-      verify_middleware_yield!
-      finalize_execution!
-    end
-
-    # Executes the task with exception raising on failure.
-    #
-    # @return [CMDx::Result] The execution result
-    #
-    # @raise [StandardError] When execution fails
-    #
-    # @example
-    #   executor = CMDx::Executor.new(my_task)
-    #   result = executor.execute!
-    #
-    # @rbs () -> Result
-    def execute!
-      task.class.settings.middlewares.call!(task) do
-        pre_execution! unless @pre_execution
-        execution!
-        verify_context_returns!
-      rescue UndefinedMethodError => e
-        raise_exception(e)
-      rescue Fault => e
-        result.throw!(e.result, halt: false, cause: e)
-
-        if halt_execution?(e)
-          raise_exception(e)
-        else
-          result.executed!
-          post_execution!
-        end
-      rescue StandardError => e
-        retry if retry_execution?(e)
-        result.fail!(Utils::Normalize.exception(e), halt: false, cause: e, source: :exception)
-        raise_exception(e)
-      else
-        result.executed!
-        post_execution!
-      end
-
-      verify_middleware_yield!
-      finalize_execution!
-    end
-
-    protected
-
-    # Determines if execution should halt based on breakpoint configuration.
-    # Returns false when the result was created with +strict: false+.
-    #
-    # @param exception [Exception] The exception that occurred
-    #
-    # @return [Boolean] Whether execution should halt
-    #
-    # @rbs (Exception exception) -> bool
-    def halt_execution?(exception)
-      return false unless exception.result.strict?
-
-      @halt_statuses ||= Utils::Normalize.statuses(
-        task.class.settings.breakpoints ||
-        task.class.settings.task_breakpoints
-      ).freeze
-
-      @halt_statuses.include?(exception.result.status)
-    end
-
-    # Determines if execution should be retried based on retry configuration.
-    #
-    # @param exception [Exception] The exception that occurred
-    #
-    # @return [Boolean] Whether execution should be retried
-    #
-    # @rbs (Exception exception) -> bool
-    def retry_execution?(exception)
-      @retry ||= Retry.new(task)
-
-      return false unless @retry.available? && @retry.remaining?
-      return false unless @retry.exception?(exception)
-
-      result.retries += 1
-
-      task.logger.warn do
-        reason = Utils::Normalize.exception(exception)
-        task.to_h.merge!(reason:, remaining_retries: @retry.remaining)
-      end
-
-      task.errors.clear
-
-      wait = @retry.wait
-      sleep(wait) if wait.positive?
-
-      true
-    end
-
-    # Raises an exception and clears the chain.
-    #
-    # @param exception [Exception] The exception to raise
-    #
-    # @raise [Exception] The provided exception
-    #
-    # @rbs (Exception exception) -> void
-    def raise_exception(exception)
-      Chain.clear
-
-      raise(exception)
-    end
-
-    # Invokes callbacks of a specific type for the task.
-    #
-    # @param type [Symbol] The type of callback to invoke
-    #
-    # @return [void]
-    #
-    # @example
-    #   invoke_callbacks(:before_execution)
-    #
-    # @rbs (Symbol type) -> void
-    def invoke_callbacks(type)
-      task.class.settings.callbacks.invoke(type, task)
-    end
-
-    private
-
-    # Performs pre-execution tasks including validation and attribute verification.
-    #
-    # @rbs () -> void
-    def pre_execution!
-      @pre_execution = true
-
-      invoke_callbacks(:before_validation)
-
-      task.class.settings.attributes.define_and_verify(task)
-      return if task.errors.empty?
-
-      result.fail!(
-        Locale.t("cmdx.faults.invalid"),
-        source: :validation,
-        errors: {
-          full_message: task.errors.to_s,
-          messages: task.errors.to_h
-        }
-      )
-    end
-
-    # Executes the main task logic.
-    # Wraps task.work in catch(:cmdx_halt) so that success! can halt early.
-    #
-    # @rbs () -> void
-    def execution!
-      invoke_callbacks(:before_execution)
-
-      result.executing!
-      catch(:cmdx_halt) { task.work }
-    end
-
-    # Verifies that all declared returns are present in the context after execution.
-    #
-    # @rbs () -> void
-    def verify_context_returns!
-      return unless result.success?
-
-      returns = Utils::Wrap.array(task.class.settings.returns)
-      missing = returns.reject { |name| task.context.key?(name) }
-      return if missing.empty?
-
-      missing.each { |name| task.errors.add(name, Locale.t("cmdx.returns.missing")) }
-
-      result.fail!(
-        Locale.t("cmdx.faults.invalid"),
-        source: :context,
-        errors: {
-          full_message: task.errors.to_s,
-          messages: task.errors.to_h
-        }
-      )
-    end
-
-    # Performs post-execution tasks including callback invocation.
-    #
-    # @rbs () -> void
-    def post_execution!
-      return if task.class.settings.callbacks.empty?
-
-      invoke_callbacks(STATE_CALLBACKS[result.state])
-      invoke_callbacks(:on_executed) if result.executed?
-
-      invoke_callbacks(STATUS_CALLBACKS[result.status])
-      invoke_callbacks(:on_good) if result.good?
-      invoke_callbacks(:on_bad) if result.bad?
-    end
-
-    # Detects if middleware swallowed the block without yielding.
-    # When this happens the result is still in the initialized state.
-    #
-    # @rbs () -> void
-    def verify_middleware_yield!
-      return unless result.initialized?
-
-      result.fail!(
-        Locale.t("cmdx.faults.invalid"),
-        halt: false,
-        source: :middleware
-      )
-      result.executed!
-    end
-
-    # Finalizes execution by freezing the task, logging results, and rolling back work.
-    #
-    # @rbs () -> void
-    def finalize_execution!
-      log_execution!
-      log_backtrace! if task.class.settings.backtrace
-
-      rollback_execution!
-      freeze_execution!
-      clear_chain!
-    end
-
-    # Logs the execution result at the configured log level.
-    #
-    # @rbs () -> void
-    def log_execution!
-      task.logger.info { result.to_h }
-    end
-
-    # Logs the backtrace of the exception if the task failed.
-    #
-    # @rbs () -> void
-    def log_backtrace!
-      return unless result.failed?
-
-      exception = result.caused_failure&.cause
-      return if exception.nil? || exception.is_a?(Fault)
-
-      task.logger.error do
-        Utils::Normalize.exception(exception) << "\n" <<
-          if (cleaner = task.class.settings.backtrace_cleaner)
-            cleaner.call(exception.backtrace).join("\n\t")
-          else
-            exception.full_message(highlight: false)
-          end
-      end
-    end
-
-    # Freezes the task and its associated objects to prevent modifications.
-    #
-    # @rbs () -> void
-    def freeze_execution!
-      # Stubbing on frozen objects is not allowed in most test environments.
-      return unless CMDx.configuration.freeze_results
-
-      task.freeze
-      result.freeze
-
-      # Freezing the context and chain can only be done once the outer-most
-      # task has completed.
-      return unless result.index.zero?
-
-      task.context.freeze
-      task.chain.freeze
-    end
-
-    # Clears the chain if the task is the outermost (top-level) task
-    # and the current thread's chain is the same instance this task belongs to.
-    #
-    # @rbs () -> void
-    def clear_chain!
-      return unless result.index.zero?
-      return unless Chain.current.equal?(task.chain)
-
-      Chain.clear
-    end
-
-    # Rolls back the work of a task.
-    #
-    # @rbs () -> void
-    def rollback_execution!
-      return if result.rolled_back?
-      return unless task.respond_to?(:rollback)
-
-      @rollback_statuses ||= Utils::Normalize.statuses(task.class.settings.rollback_on).freeze
-      return unless @rollback_statuses.include?(result.status)
-
-      result.rolled_back = true
-      task.rollback
-    end
-
-  end
-end

data/lib/cmdx/identifier.rb

@@ -1,30 +0,0 @@
-# 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"
-    #
-    # @rbs () -> String
-    if SecureRandom.respond_to?(:uuid_v7)
-      def generate = SecureRandom.uuid_v7
-    else
-      def generate = SecureRandom.uuid
-    end
-
-  end
-end