cmdx 1.21.0 → 2.0.0

data/lib/cmdx/chain.rb

@@ -1,215 +1,118 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Manages a collection of task execution results in a thread and fiber safe manner.
-  # Chains provide a way to track related task executions and their outcomes
-  # within the same execution context.
+  # Ordered collection of {Result}s produced by a top-level task and any nested
+  # tasks it triggers. A Chain is stored per-fiber so concurrent workflows
+  # (see Pipeline parallel strategy) each get their own. The root Runtime
+  # clears the chain on teardown.
   class Chain
 
-    extend Forwardable
+    include Enumerable
 
-    # @rbs CONCURRENCY_KEY: Symbol
-    CONCURRENCY_KEY = :cmdx_chain
-
-    # Returns the unique identifier for this chain.
-    #
-    # @return [String] The chain identifier
-    #
-    # @example
-    #   chain.id # => "abc123xyz"
-    #
-    # @rbs @id: String
-    attr_reader :id
-
-    # Returns the collection of execution results in this chain.
-    #
-    # @return [Array<Result>] Array of task results
-    #
-    # @example
-    #   chain.results # => [#<Result>, #<Result>]
-    #
-    # @rbs @results: Array[Result]
-    attr_reader :results
-
-    def_delegators :results, :first, :last, :size
-    def_delegators :first, :state, :status, :outcome
-
-    # Creates a new chain with a unique identifier and empty results collection.
-    #
-    # @return [Chain] A new chain instance
-    #
-    # @rbs () -> void
-    def initialize(dry_run: false)
-      @mutex = Mutex.new
-      @id = Identifier.generate
-      @results = []
-      @dry_run = !!dry_run
-    end
+    # Fiber-local storage key used by {.current}/{.current=}/{.clear}.
+    STORAGE_KEY = :cmdx_chain
 
     class << self
 
-      # Retrieves the current chain for the current execution context.
-      #
-      # @return [Chain, nil] The current chain or nil if none exists
-      #
-      # @example
-      #   chain = Chain.current
-      #   if chain
-      #     puts "Current chain: #{chain.id}"
-      #   end
-      #
-      # @rbs () -> Chain?
+      # @return [Chain, nil] the chain active on the current fiber, or nil outside execution
       def current
-        thread_or_fiber[CONCURRENCY_KEY]
+        Fiber[STORAGE_KEY]
       end
 
-      # Sets the current chain for the current execution context.
-      #
-      # @param chain [Chain] The chain to set as current
-      #
-      # @return [Chain] The set chain
-      #
-      # @example
-      #   Chain.current = my_chain
-      #
-      # @rbs (Chain chain) -> Chain
+      # Installs `chain` as the active chain on the current fiber.
+      # @param chain [Chain, nil]
+      # @return [Chain, nil]
       def current=(chain)
-        thread_or_fiber[CONCURRENCY_KEY] = chain
+        Fiber[STORAGE_KEY] = chain
       end
 
-      # Clears the current chain for the current execution context.
-      #
-      # @return [nil] Always returns nil
-      #
-      # @example
-      #   Chain.clear
-      #
-      # @rbs () -> nil
+      # Clears the fiber-local chain reference.
+      # @return [nil]
       def clear
-        thread_or_fiber[CONCURRENCY_KEY] = nil
+        Fiber[STORAGE_KEY] = nil
       end
 
-      # Builds or extends the current chain by adding a result.
-      # Creates a new chain if none exists, otherwise appends to the current one.
-      #
-      # @param result [Result] The task execution result to add
-      #
-      # @return [Chain] The current chain (newly created or existing)
-      #
-      # @raise [TypeError] If result is not a CMDx::Result instance
-      #
-      # @example
-      #   result = task.execute
-      #   chain = Chain.build(result)
-      #   puts "Chain size: #{chain.size}"
-      #
-      # @rbs (Result result) -> Chain
-      def build(result, dry_run: false)
-        raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
-
-        self.current ||= new(dry_run:)
-        current.push(result)
-        current
-      end
+    end
 
-      private
-
-      # Returns the thread or fiber storage for the current execution context.
-      #
-      # @return [Hash] The thread or fiber storage
-      #
-      # @rbs () -> Hash
-      if Fiber.respond_to?(:storage)
-        def thread_or_fiber = Fiber.storage
-      else
-        def thread_or_fiber = Thread.current
-      end
+    attr_reader :xid, :id, :results
 
+    # @param xid [String, nil] external correlation id (e.g. Rails `request_id`)
+    #   shared across every {Result} in this chain. Resolved once by Runtime
+    #   from {Configuration#xid} when the root chain is created.
+    def initialize(xid = nil)
+      @xid     = xid
+      @id      = SecureRandom.uuid_v7
+      @mutex   = Mutex.new
+      @results = []
     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
+    # Appends `result` to the chain. Thread-safe to support parallel pipelines.
     #
-    # @return [Array<Result>] The updated results array
-    #
-    # @rbs (Result result) -> Array[Result]
+    # @param result [Result]
+    # @return [Chain] self for chaining
     def push(result)
-      @mutex.synchronize do
-        result.instance_variable_set(:@chain_index, @results.size)
-        @results << result
-      end
+      @mutex.synchronize { @results << result }
+      self
     end
+    alias << push
 
-    # Thread-safe lookup of a result's position in the chain.
-    #
-    # @param result [Result] The result to find
+    # Prepends `result` to the chain. Thread-safe to support parallel pipelines.
     #
-    # @return [Integer, nil] The zero-based index or nil if not found
-    #
-    # @rbs (Result result) -> Integer?
+    # @param result [Result]
+    # @return [Chain] self for chaining
+    def unshift(result)
+      @mutex.synchronize { @results.unshift(result) }
+      self
+    end
+
+    # @param result [Result]
+    # @return [Integer, nil] zero-based position of `result`, or nil when absent
     def index(result)
-      @mutex.synchronize { @results.index(result) }
+      @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
-    #
-    # @example
-    #   chain.dry_run? # => true
-    #
-    # @rbs () -> bool
-    def dry_run?
-      !!@dry_run
+    # @return [Result, nil] the most recently appended result
+    def last
+      @results.last
     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
+    # @return [Result, nil] the root result, or nil when absent
+    def root
+      @results.find(&:root?)
     end
 
-    # Converts the chain to a hash representation.
-    #
-    # @option return [String] :id The chain identifier
-    # @option return [Array<Hash>] :results Array of result hashes
-    #
-    # @return [Hash] Hash containing chain id and serialized results
-    #
-    # @example
-    #   chain_hash = chain.to_h
-    #   puts chain_hash[:id]
-    #   puts chain_hash[:results].size
-    #
-    # @rbs () -> Hash[Symbol, untyped]
-    def to_h
-      {
-        id:,
-        dry_run: dry_run?,
-        results: results.map(&:to_h)
-      }
+    # @return [String, nil] the state of the root result, or nil when absent
+    def state
+      root&.state
     end
 
-    # Converts the chain to a string representation.
-    #
-    # @return [String] Formatted string representation of the chain
-    #
-    # @example
-    #   puts chain.to_s
+    # @return [String, nil] the status of the root result, or nil when absent
+    def status
+      root&.status
+    end
+
+    # @return [Boolean]
+    def empty?
+      @results.empty?
+    end
+
+    # @return [Integer]
+    def size
+      @results.size
+    end
+
+    # @yield [Result] each result in insertion order
+    # @return [Enumerator, Chain]
+    def each(&)
+      @results.each(&)
+    end
+
+    # Freezes the chain and its results. Called by Runtime teardown.
     #
-    # @rbs () -> String
-    def to_s
-      Utils::Format.to_str(to_h)
+    # @return [Chain] self
+    def freeze
+      @mutex.synchronize { @results.freeze }
+      super
     end
 
   end

data/lib/cmdx/coercions/array.rb

@@ -1,47 +1,33 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Coercions
-    # Converts various input types to Array format
-    #
-    # Handles conversion from strings that look like JSON arrays and other
-    # values that can be wrapped in an array using Ruby's Array() method.
+  class Coercions
+    # Coerces to Array. JSON-decodes strings; arrays pass through; objects
+    # responding to `#to_a` are unwrapped; everything else is wrapped.
     module Array
 
       extend self
 
-      # Converts a value to an Array
-      #
-      # @param value [Object] The value to convert to an array
-      # @param options [Hash] Optional configuration parameters (currently unused)
-      # @option options [Object] :unused Currently no options are used
-      #
-      # @return [Array] The converted array value
-      #
-      # @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]
-      # @example Convert other values using Array()
-      #   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]
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Object] reserved for future per-coercion configuration (currently ignored)
+      # @return [Array, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        if value.is_a?(::String) && (
-          value.start_with?("[") ||
-          value.strip == "null"
-        )
-          JSON.parse(value) || []
+        if value.is_a?(::Array)
+          value
+        elsif value.is_a?(::String)
+          result = JSON.parse(value)
+          result.is_a?(::Array) ? result : [value]
+        elsif value.respond_to?(:to_a)
+          value.to_a
         else
-          Utils::Wrap.array(value)
+          [value]
         end
       rescue JSON::ParserError
-        type = Locale.t("cmdx.types.array")
-        raise CoercionError, Locale.t("cmdx.coercions.into_an", type:)
+        [value]
+      rescue TypeError
+        type = I18nProxy.t("cmdx.types.array")
+        Failure.new(I18nProxy.t("cmdx.coercions.into_an", type:))
       end
 
     end

data/lib/cmdx/coercions/big_decimal.rb

@@ -1,41 +1,24 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Coercions
-    # Converts various input types to BigDecimal format
-    #
-    # Handles conversion from numeric strings, integers, floats, and other
-    # values that can be converted to BigDecimal using Ruby's BigDecimal() method.
+  class Coercions
+    # Coerces to `BigDecimal`. Default precision is 14 digits; override with
+    # `precision:` on the declaration.
     module BigDecimal
 
       extend self
 
-      # @rbs DEFAULT_PRECISION: Integer
-      DEFAULT_PRECISION = 14
-
-      # Converts a value to a BigDecimal
-      #
-      # @param value [Object] The value to convert to BigDecimal
-      # @param options [Hash] Optional configuration parameters
-      # @option options [Integer] :precision The precision to use (defaults to DEFAULT_PRECISION)
-      #
-      # @return [BigDecimal] The converted BigDecimal value
-      #
-      # @raise [CoercionError] If the value cannot be converted to BigDecimal
-      #
-      # @example Convert numeric strings to BigDecimal
-      #   BigDecimal.call("123.45")                   # => #<BigDecimal:7f8b8c0d8e0f '0.12345E3',9(18)>
-      #   BigDecimal.call("0.001", precision: 6)      # => #<BigDecimal:7f8b8c0d8e0f '0.1E-2',9(18)>
-      # @example Convert other numeric types
-      #   BigDecimal.call(42)                         # => #<BigDecimal:7f8b8c0d8e0f '0.42E2',9(18)>
-      #   BigDecimal.call(3.14159)                    # => #<BigDecimal:7f8b8c0d8e0f '0.314159E1',9(18)>
-      #
-      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> BigDecimal
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Integer] :precision (14)
+      # @return [BigDecimal, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
+        return value if value.is_a?(BigDecimal)
+
+        BigDecimal(value, options[:precision] || 14)
       rescue ArgumentError, TypeError
-        type = Locale.t("cmdx.types.big_decimal")
-        raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
+        type = I18nProxy.t("cmdx.types.big_decimal")
+        Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end
 
     end

data/lib/cmdx/coercions/boolean.rb

@@ -1,56 +1,36 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Coercions
-    # Converts various input types to Boolean format
-    #
-    # Handles conversion from strings, numbers, and other values to boolean
-    # using predefined truthy and falsey patterns.
+  class Coercions
+    # Coerces to Boolean by matching the string form against the {TRUTHY}
+    # and {FALSEY} sets (case- and whitespace-insensitive). Anything else
+    # (including `nil`) fails.
     module Boolean
 
       extend self
 
-      # @rbs FALSEY: Regexp
-      FALSEY = /\A(false|f|no|n|0)\z/i
-
-      # @rbs TRUTHY: Regexp
-      TRUTHY = /\A(true|t|yes|y|1)\z/i
-
-      # Converts a value to a Boolean
-      #
-      # @param value [Object] The value to convert to boolean
-      # @param options [Hash] Optional configuration parameters (currently unused)
-      # @option options [Object] :unused Currently no options are used
-      #
-      # @return [Boolean] The converted boolean value
-      #
-      # @raise [CoercionError] If the value cannot be converted to boolean
-      #
-      # @example Convert truthy strings to true
-      #   Boolean.call("true")   # => true
-      #   Boolean.call("yes")    # => true
-      #   Boolean.call("1")      # => true
-      # @example Convert falsey strings to false
-      #   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
+      TRUTHY = Set["true", "yes", "on", "y", "1", "t"].freeze
+      FALSEY = Set["false", "no", "off", "n", "0", "f"].freeze
+
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Object] reserved for future per-coercion configuration (currently ignored)
+      # @return [Boolean, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        case value.to_s
-        when FALSEY, EMPTY_STRING then false
-        when TRUTHY then true
-        else
-          type = Locale.t("cmdx.types.boolean")
-          raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
-        end
+        return coercion_failure if value.nil?
+
+        str = value.to_s.strip.downcase
+        return true if TRUTHY.include?(str)
+        return false if FALSEY.include?(str)
+
+        coercion_failure
+      end
+
+      private
+
+      def coercion_failure
+        type = I18nProxy.t("cmdx.types.boolean")
+        Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end
 
     end

data/lib/cmdx/coercions/coerce.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Coercions
+    # Invokes an inline `:coerce` handler (Symbol method name, Proc, or
+    # anything with `#call`). Used by {Coercions#coerce} for non-built-in
+    # rules.
+    module Coerce
+
+      extend self
+
+      # @param task [Task] receiver for Symbol/Proc handlers, also passed to callable handlers
+      # @param value [Object]
+      # @param handler [Symbol, Proc, #call]
+      # @return [Object] the handler's return value
+      # @raise [ArgumentError] when `handler` isn't a supported type
+      def call(task, value, handler)
+        case handler
+        when ::Symbol
+          task.send(handler, value)
+        when ::Proc
+          task.instance_exec(value, &handler)
+        else
+          return handler.call(value, task) if handler.respond_to?(:call)
+
+          raise ArgumentError, "coerce handler must be a Symbol, Proc, or respond to #call"
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/coercions/complex.rb

@@ -1,39 +1,24 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Coercions
-    # Converts various input types to Complex number format
-    #
-    # Handles conversion from numeric strings, integers, floats, and other
-    # values that can be converted to Complex using Ruby's Complex() method.
+  class Coercions
+    # Coerces to `Complex`. Supply `imaginary:` to provide the imaginary
+    # component when `value` is a real-only input.
     module Complex
 
       extend self
 
-      # Converts a value to a Complex number
-      #
-      # @param value [Object] The value to convert to Complex
-      # @param options [Hash] Optional configuration parameters (currently unused)
-      # @option options [Object] :* Any configuration option (unused)
-      #
-      # @return [Complex] The converted Complex number value
-      #
-      # @raise [CoercionError] If the value cannot be converted to Complex
-      #
-      # @example Convert numeric strings to Complex
-      #   Complex.call("3+4i")                     # => (3+4i)
-      #   Complex.call("2.5")                      # => (2.5+0i)
-      # @example Convert other numeric types
-      #   Complex.call(5)                          # => (5+0i)
-      #   Complex.call(3.14)                       # => (3.14+0i)
-      #   Complex.call(Complex(1, 2))              # => (1+2i)
-      #
-      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Complex
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [Numeric] :imaginary (0)
+      # @return [Complex, Coercions::Failure]
       def call(value, options = EMPTY_HASH)
-        Complex(value)
+        return value if value.is_a?(::Complex)
+
+        Complex(value, options[:imaginary] || 0)
       rescue ArgumentError, TypeError
-        type = Locale.t("cmdx.types.complex")
-        raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
+        type = I18nProxy.t("cmdx.types.complex")
+        Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end
 
     end

data/lib/cmdx/coercions/date.rb

@@ -1,45 +1,41 @@
 # frozen_string_literal: true
 
 module CMDx
-  module Coercions
-    # Converts various input types to Date format
-    #
-    # Handles conversion from strings, Date objects, DateTime objects, Time objects,
-    # and other date-like values to Date objects using Ruby's built-in parsing
-    # capabilities and optional custom format parsing.
+  class Coercions
+    # Coerces to `Date`. Pass `strptime:` to parse via a specific format;
+    # otherwise `Date.parse` is used for strings, and `#to_date` for any
+    # other responding object.
     module Date
 
       extend self
 
-      # Converts a value to a Date object
-      #
-      # @param value [Object] The value to convert to a Date
-      # @param options [Hash] Optional configuration parameters
-      # @option options [String] :strptime Custom date format string for parsing
-      #
-      # @return [Date] The converted Date object
-      #
-      # @raise [CoercionError] If the value cannot be converted to a Date
-      #
-      # @example Convert string to Date using default parsing
-      #   Date.call("2023-12-25")           # => #<Date: 2023-12-25>
-      #   Date.call("Dec 25, 2023")        # => #<Date: 2023-12-25>
-      # @example Convert string using custom format
-      #   Date.call("25/12/2023", strptime: "%d/%m/%Y")  # => #<Date: 2023-12-25>
-      #   Date.call("12-25-2023", strptime: "%m-%d-%Y")  # => #<Date: 2023-12-25>
-      # @example Return existing Date objects unchanged
-      #   Date.call(Date.new(2023, 12, 25)) # => #<Date: 2023-12-25>
-      #   Date.call(DateTime.new(2023, 12, 25)) # => #<Date: 2023-12-25>
-      #
-      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Date
+      # @param value [Object]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :strptime format string for `Date.strptime`
+      # @return [Date, Coercions::Failure]
       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]
+        if value.is_a?(::Date)
+          value
+        elsif value.is_a?(::String)
+          if (strptime = options[:strptime])
+            ::Date.strptime(value, strptime)
+          else
+            ::Date.parse(value)
+          end
+        elsif value.respond_to?(:to_date)
+          value.to_date
+        else
+          coercion_failure
+        end
+      rescue ArgumentError, TypeError, ::Date::Error
+        coercion_failure
+      end
+
+      private
 
-        ::Date.parse(value)
-      rescue TypeError, ::Date::Error
-        type = Locale.t("cmdx.types.date")
-        raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
+      def coercion_failure
+        type = I18nProxy.t("cmdx.types.date")
+        Failure.new(I18nProxy.t("cmdx.coercions.into_a", type:))
       end
 
     end