cmdx 1.18.0 → 1.20.0

data/lib/cmdx/chain.rb

@@ -31,7 +31,7 @@ module CMDx
     # @rbs @results: Array[Result]
     attr_reader :results
 
-    def_delegators :results, :index, :first, :last, :size
+    def_delegators :results, :first, :last, :size
     def_delegators :first, :state, :status, :outcome, :runtime
 
     # Creates a new chain with a unique identifier and empty results collection.
@@ -40,6 +40,7 @@ module CMDx
     #
     # @rbs () -> void
     def initialize(dry_run: false)
+      @mutex = Mutex.new
       @id = Identifier.generate
       @results = []
       @dry_run = !!dry_run
@@ -107,7 +108,7 @@ module CMDx
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
         self.current ||= new(dry_run:)
-        current.results << result
+        current.push(result)
         current
       end
 
@@ -118,12 +119,40 @@ module CMDx
       # @return [Hash] The thread or fiber storage
       #
       # @rbs () -> Hash
-      def thread_or_fiber
-        Fiber.respond_to?(:storage) ? Fiber.storage : Thread.current
+      if Fiber.respond_to?(:storage)
+        def thread_or_fiber = Fiber.storage
+      else
+        def thread_or_fiber = Thread.current
       end
 
     end
 
+    # Thread-safe append of a result to the chain.
+    # Caches the result's index to avoid repeated O(n) lookups.
+    #
+    # @param result [Result] The result to append
+    #
+    # @return [Array<Result>] The updated results array
+    #
+    # @rbs (Result result) -> Array[Result]
+    def push(result)
+      @mutex.synchronize do
+        result.instance_variable_set(:@chain_index, @results.size)
+        @results << result
+      end
+    end
+
+    # Thread-safe lookup of a result's position in the chain.
+    #
+    # @param result [Result] The result to find
+    #
+    # @return [Integer, nil] The zero-based index or nil if not found
+    #
+    # @rbs (Result result) -> Integer?
+    def index(result)
+      @mutex.synchronize { @results.index(result) }
+    end
+
     # Returns whether the chain is running in dry-run mode.
     #
     # @return [Boolean] Whether the chain is running in dry-run mode
@@ -136,6 +165,20 @@ module CMDx
       !!@dry_run
     end
 
+    # Freezes the chain and its internal results to prevent modifications.
+    #
+    # @return [Chain] the frozen chain
+    #
+    # @example
+    #   chain.freeze
+    #   chain.results << result # => raises FrozenError
+    #
+    # @rbs () -> self
+    def freeze
+      results.freeze
+      super
+    end
+
     # Converts the chain to a hash representation.
     #
     # @option return [String] :id The chain identifier

data/lib/cmdx/coercion_registry.rb

@@ -5,19 +5,11 @@ module CMDx
   #
   # 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
 
-    # Returns the internal registry mapping coercion types to handler classes.
-    #
-    # @return [Hash{Symbol => Class}] Hash of coercion type names to coercion classes
-    #
-    # @example
-    #   registry.registry # => { integer: Coercions::Integer, boolean: Coercions::Boolean }
-    #
-    # @rbs @registry: Hash[Symbol, Class]
-    attr_reader :registry
-    alias to_h registry
-
     # Initialize a new coercion registry.
     #
     # @param registry [Hash{Symbol => Class}, nil] optional initial registry hash
@@ -44,17 +36,30 @@ module CMDx
       }
     end
 
-    # Create a duplicate of this registry.
+    # Sets up copy-on-write state when duplicated via dup.
     #
-    # @return [CoercionRegistry] a new instance with duplicated registry hash
+    # @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
-    #   new_registry = registry.dup
+    #   registry.registry # => { integer: Coercions::Integer, boolean: Coercions::Boolean }
     #
-    # @rbs () -> CoercionRegistry
-    def dup
-      self.class.new(registry.dup)
+    # @rbs () -> Hash[Symbol, Class]
+    def registry
+      @registry || @parent.registry
     end
+    alias to_h registry
 
     # Register a new coercion handler for a type.
     #
@@ -69,7 +74,9 @@ module CMDx
     #
     # @rbs ((Symbol | String) name, Class coercion) -> self
     def register(name, coercion)
-      registry[name.to_sym] = coercion
+      materialize!
+
+      @registry[name.to_sym] = coercion
       self
     end
 
@@ -85,7 +92,9 @@ module CMDx
     #
     # @rbs ((Symbol | String) name) -> self
     def deregister(name)
-      registry.delete(name.to_sym)
+      materialize!
+
+      @registry.delete(name.to_sym)
       self
     end
 
@@ -106,11 +115,24 @@ module CMDx
     #   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 = {})
+    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/coercions/array.rb

@@ -18,7 +18,7 @@ module CMDx
       #
       # @return [Array] The converted array value
       #
-      # @raise [JSON::ParserError] If the string value contains invalid JSON
+      # @raise [CoercionError] If the value cannot be converted to an array
       #
       # @example Convert a JSON-like string to an array
       #   Array.call("[1, 2, 3]") # => [1, 2, 3]
@@ -26,17 +26,22 @@ module CMDx
       #   Array.call("hello")     # => ["hello"]
       #   Array.call(42)          # => [42]
       #   Array.call(nil)         # => []
+      # @example Handle invalid JSON-like strings
+      #   Array.call("[not json") # => raises CoercionError
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Array[untyped]
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         if value.is_a?(::String) && (
           value.start_with?("[") ||
           value.strip == "null"
         )
           JSON.parse(value) || []
         else
-          Array(value)
+          Utils::Wrap.array(value)
         end
+      rescue JSON::ParserError
+        type = Locale.t("cmdx.types.array")
+        raise CoercionError, Locale.t("cmdx.coercions.into_an", type:)
       end
 
     end

data/lib/cmdx/coercions/big_decimal.rb

@@ -31,7 +31,7 @@ module CMDx
       #   BigDecimal.call(3.14159)                    # => #<BigDecimal:7f8b8c0d8e0f '0.314159E1',9(18)>
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> BigDecimal
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError
         type = Locale.t("cmdx.types.big_decimal")

data/lib/cmdx/coercions/boolean.rb

@@ -34,14 +34,18 @@ module CMDx
       #   Boolean.call("false")  # => false
       #   Boolean.call("no")     # => false
       #   Boolean.call("0")      # => false
+      #   Boolean.call(nil)      # => false
+      #   Boolean.call("")       # => false
       # @example Handle case-insensitive input
       #   Boolean.call("TRUE")   # => true
       #   Boolean.call("False")  # => false
+      # @example Handle edge cases
+      #   Boolean.call("abc")    # => raises CoercionError
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> bool
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         case value.to_s
-        when FALSEY then false
+        when FALSEY, EMPTY_STRING then false
         when TRUTHY then true
         else
           type = Locale.t("cmdx.types.boolean")

data/lib/cmdx/coercions/complex.rb

@@ -29,7 +29,7 @@ module CMDx
       #   Complex.call(Complex(1, 2))              # => (1+2i)
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Complex
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         Complex(value)
       rescue ArgumentError, TypeError
         type = Locale.t("cmdx.types.complex")

data/lib/cmdx/coercions/date.rb

@@ -11,11 +11,6 @@ module CMDx
 
       extend self
 
-      # Types that are already date-like and don't need conversion
-      #
-      # @rbs ANALOG_TYPES: Array[String]
-      ANALOG_TYPES = %w[Date DateTime Time].freeze
-
       # Converts a value to a Date object
       #
       # @param value [Object] The value to convert to a Date
@@ -37,8 +32,8 @@ module CMDx
       #   Date.call(DateTime.new(2023, 12, 25)) # => #<Date: 2023-12-25>
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Date
-      def call(value, options = {})
-        return value if ANALOG_TYPES.include?(value.class.name)
+      def call(value, options = EMPTY_HASH)
+        return value.to_date if value.respond_to?(:to_date)
         return ::Date.strptime(value, options[:strptime]) if options[:strptime]
 
         ::Date.parse(value)

data/lib/cmdx/coercions/date_time.rb

@@ -11,11 +11,6 @@ module CMDx
 
       extend self
 
-      # Types that are already date-time-like and don't need conversion
-      #
-      # @rbs ANALOG_TYPES: Array[String]
-      ANALOG_TYPES = %w[Date DateTime Time].freeze
-
       # Converts a value to a DateTime
       #
       # @param value [Object] The value to convert to DateTime
@@ -37,8 +32,8 @@ module CMDx
       #   DateTime.call(Time.new(2023, 12, 25))     # => #<DateTime: 2023-12-25T00:00:00+00:00>
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> DateTime
-      def call(value, options = {})
-        return value if ANALOG_TYPES.include?(value.class.name)
+      def call(value, options = EMPTY_HASH)
+        return value.to_datetime if value.respond_to?(:to_datetime)
         return ::DateTime.strptime(value, options[:strptime]) if options[:strptime]
 
         ::DateTime.parse(value)

data/lib/cmdx/coercions/float.rb

@@ -32,7 +32,7 @@ module CMDx
       #   Float.call(Complex(5.0, 0))      # => 5.0
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Float
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         Float(value)
       rescue ArgumentError, RangeError, TypeError
         type = Locale.t("cmdx.types.float")

data/lib/cmdx/coercions/hash.rb

@@ -33,7 +33,7 @@ module CMDx
       #   Hash.call('{"key": "value"}') # => {"key" => "value"}
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Hash[untyped, untyped]
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         if value.nil?
           {}
         elsif value.is_a?(::Hash)

data/lib/cmdx/coercions/integer.rb

@@ -30,13 +30,12 @@ module CMDx
       #   Integer.call(3.14)      # => 3
       #   Integer.call(0.0)       # => 0
       # @example Handle edge cases
-      #   Integer.call("")        # => 0
-      #   Integer.call(nil)       # => 0
-      #   Integer.call(false)     # => 0
-      #   Integer.call(true)      # => 1
+      #   Integer.call("")        # => raises CoercionError
+      #   Integer.call(nil)       # => raises CoercionError
+      #   Integer.call("abc")     # => raises CoercionError
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Integer
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         Integer(value)
       rescue ArgumentError, FloatDomainError, RangeError, TypeError
         type = Locale.t("cmdx.types.integer")

data/lib/cmdx/coercions/rational.rb

@@ -35,7 +35,7 @@ module CMDx
       #   Rational.call(0)         # => (0/1)
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Rational
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         Rational(value)
       rescue ArgumentError, FloatDomainError, RangeError, TypeError, ZeroDivisionError
         type = Locale.t("cmdx.types.rational")

data/lib/cmdx/coercions/string.rb

@@ -29,7 +29,7 @@ module CMDx
       #   String.call(true)              # => "true"
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> String
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         String(value)
       end
 

data/lib/cmdx/coercions/symbol.rb

@@ -28,7 +28,7 @@ module CMDx
       #   Symbol.call(:existing)         # => :existing
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Symbol
-      def call(value, options = {})
+      def call(value, options = EMPTY_HASH)
         value.to_sym
       rescue NoMethodError
         type = Locale.t("cmdx.types.symbol")

data/lib/cmdx/coercions/time.rb

@@ -11,11 +11,6 @@ module CMDx
 
       extend self
 
-      # Types that are already time-like and don't need conversion
-      #
-      # @rbs ANALOG_TYPES: Array[String]
-      ANALOG_TYPES = %w[DateTime Time].freeze
-
       # Converts a value to a Time object
       #
       # @param value [Object] The value to convert to a Time object
@@ -39,8 +34,7 @@ module CMDx
       #   Time.call("12-25-2023", strptime: "%m-%d-%Y")  # => Time object
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Time
-      def call(value, options = {})
-        return value if ANALOG_TYPES.include?(value.class.name)
+      def call(value, options = EMPTY_HASH)
         return value.to_time if value.respond_to?(:to_time)
         return ::Time.strptime(value, options[:strptime]) if options[:strptime]
 

data/lib/cmdx/configuration.rb

@@ -123,6 +123,28 @@ module CMDx
     # @rbs @rollback_on: Array[String]
     attr_accessor :rollback_on
 
+    # Returns whether to freeze task results after execution.
+    # Set to false in test environments to allow stubbing on result objects.
+    #
+    # @return [Boolean] true if results should be frozen (default: true)
+    #
+    # @example
+    #   config.freeze_results = false
+    #
+    # @rbs @freeze_results: bool
+    attr_accessor :freeze_results
+
+    # Returns the default locale used for built-in translation lookups.
+    # Must match the basename of a YAML file in lib/locales/ (e.g. "en", "es", "ja").
+    #
+    # @return [String] The locale identifier (default: "en")
+    #
+    # @example
+    #   config.default_locale = "es"
+    #
+    # @rbs @locale: String
+    attr_accessor :default_locale
+
     # Initializes a new Configuration instance with default values.
     #
     # Creates new registry instances for middlewares, callbacks, coercions, and
@@ -145,6 +167,8 @@ module CMDx
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
       @rollback_on = DEFAULT_ROLLPOINTS
+      @freeze_results = true
+      @default_locale = "en"
 
       @backtrace = false
       @backtrace_cleaner = nil
@@ -177,6 +201,8 @@ module CMDx
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
         rollback_on: @rollback_on,
+        freeze_results: @freeze_results,
+        default_locale: @default_locale,
         backtrace: @backtrace,
         backtrace_cleaner: @backtrace_cleaner,
         exception_handler: @exception_handler,

data/lib/cmdx/context.rb

@@ -160,8 +160,8 @@ module CMDx
     #   context.to_h # => {name: "John", age: 30, city: "NYC"}
     #
     # @rbs (?untyped args) -> self
-    def merge!(args = {})
-      args.to_h.each { |key, value| self[key.to_sym] = value }
+    def merge!(args = EMPTY_HASH)
+      table.merge!(args.to_h.transform_keys(&:to_sym))
       self
     end
     alias merge merge!
@@ -280,13 +280,15 @@ module CMDx
     #
     # @rbs (Symbol method_name, *untyped args, **untyped _kwargs) ?{ () -> untyped } -> untyped
     def method_missing(method_name, *args, **_kwargs, &)
-      fetch(method_name) do
-        str_name = method_name.to_s
-        store(str_name.chop, args.first) if str_name.end_with?("=")
+      if method_name.end_with?("=")
+        store(method_name.name.chop, args.first)
+      else
+        table[method_name]
       end
     end
 
     # Checks if the object responds to a given method.
+    # Supports both getter access for existing keys and setter methods.
     #
     # @param method_name [Symbol] the method name to check
     # @param include_private [Boolean] whether to include private methods
@@ -296,11 +298,12 @@ module CMDx
     # @example
     #   context = Context.new(name: "John")
     #   context.respond_to?(:name) # => true
+    #   context.respond_to?(:name=) # => true
     #   context.respond_to?(:age) # => false
     #
     # @rbs (Symbol method_name, ?bool include_private) -> bool
     def respond_to_missing?(method_name, include_private = false)
-      key?(method_name) || super
+      key?(method_name) || method_name.end_with?("=") || super
     end
 
   end

data/lib/cmdx/deprecator.rb

@@ -10,11 +10,23 @@ module CMDx
 
     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 /raise|log|warn/ then 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
@@ -28,14 +40,14 @@ module CMDx
     # 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]
+    # @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
+    # @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
@@ -49,13 +61,14 @@ module CMDx
     #
     # @rbs (Task task) -> void
     def restrict(task)
-      type = EVAL.call(task, task.class.settings[:deprecate])
+      setting = task.class.settings.deprecate
+      return unless setting
 
-      case type
-      when NilClass, FalseClass # Do nothing
-      when TrueClass, /raise/ then raise DeprecationError, "#{task.class.name} usage prohibited"
-      when /log/ then task.logger.warn { "DEPRECATED: migrate to a replacement or discontinue use" }
-      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to a replacement or discontinue use", category: :deprecated)
+      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

data/lib/cmdx/errors.rb

@@ -18,7 +18,7 @@ module CMDx
     # @rbs @messages: Hash[Symbol, Set[String]]
     attr_reader :messages
 
-    def_delegators :messages, :empty?
+    def_delegators :messages, :any?, :clear, :empty?, :size
 
     # Initialize a new error collection.
     #
@@ -57,9 +57,8 @@ module CMDx
     #
     # @rbs (Symbol attribute) -> bool
     def for?(attribute)
-      return false unless messages.key?(attribute)
-
-      !messages[attribute].empty?
+      set = messages[attribute]
+      !set.nil? && !set.empty?
     end
 
     # Convert errors to a hash format with arrays of full messages.

data/lib/cmdx/exception.rb

@@ -29,6 +29,13 @@ module CMDx
   # 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