cmdx 1.16.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d864a54c25ea1fd3a30f5c84b760bfa1f50207f7b26e47143876c76e2258b37a
-  data.tar.gz: f1381fc4c62e761b0553800ccdd28a1aa0315e8dab4c2504692d936635b07063
+  metadata.gz: 80c55fa1f758dc69cebff57fa5dd770b4bd7692f4a37768c320b6813d28cc9fb
+  data.tar.gz: babf14b98faa436de370d039cc2b6c796f2d0c43d9e408137ccdd1f666f4abe3
 SHA512:
-  metadata.gz: 3431a3d16f0ac92ebb52daa8c412d8f9e33975deab27482d6756e00935015100b3edeb008a419d28daf3daa5e3ba59456110b8ef9554a648ebda348d68152609
-  data.tar.gz: b7837730a25c052356e45d56c69f2f41baa932362031f4f3f2fb9f5302020fff4ed8d690973afd0b482ba22a38d13091fe47f11b54635f1c321372bcbbf0cf60
+  metadata.gz: cbcb58370126bc18aec53218930b11a7c6a3194b4b1e1c6247ae2d6e693ef16f84cc4dbf90a7dbd816e900f421e625cac3ca227aca7ce4898fa711c1451230e0
+  data.tar.gz: de88ce41eacbf4f843803f84055d46dcfb7774aa5532396c820112a5ca3d80d68deb9dbc296f8b782d990122ed6ccc082bbc582f93d3714373c2705c55a936fe

data/CHANGELOG.md

@@ -4,7 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [UNRELEASED]
+
+## [1.18.0] - 2025-03-09
+
+### Changed
+- Use `Fiber.storage` instead of `Thread.current` for `Chain` and `Correlate` storage, with fallback to `Thread.current` for Ruby < 3.2, making them thread and fiber safe
+- Clone shared logger in `Task#logger` when `log_level` or `log_formatter` is customized to prevent mutation of the shared instance
+- Derive attribute values from source objects that respond to the attribute name (via `send`) as fallback when the source is not callable
+
+## [1.17.0] - 2025-02-23
+
+### Added
+- Add `returns` macro for context output validation after task execution
+- Add `remove_return`/`remove_returns` macro to remove declared returns (supports inheritance)
+- Add array coercion for JSON `"null"` string as empty array
+- Add hash coercion for JSON `"null"` string as empty hash
+- Add attribute sourcing to support both string and symbol keys when sourcing/deriving from Hash
+
+## Changed
+- Do not fail coercion if nil on optional attributes
+- Include the source method in the required attribute error message
+
+## [1.16.0] - 2025-02-06
 
 ### Added
 - Add `CMDx::Exception` alias for `CMDx::Error`

data/README.md

@@ -59,8 +59,11 @@ class AnalyzeMetrics < CMDx::Task
   on_success :track_analysis_completion!
 
   required :dataset_id, type: :integer, numeric: { min: 1 }
+
   optional :analysis_type, default: "standard"
 
+  returns :result, :analyzed_at
+
   def work
     if dataset.nil?
       fail!("Dataset not found", code: 404)

data/lib/cmdx/attribute.rb

@@ -184,6 +184,18 @@ module CMDx
 
     end
 
+    # Checks if the attribute is optional.
+    #
+    # @return [Boolean] true if the attribute is optional, false otherwise
+    #
+    # @example
+    #   attribute.optional? # => true
+    #
+    # @rbs () -> bool
+    def optional?
+      !required? || !!options[:optional]
+    end
+
     # Checks if the attribute is required.
     #
     # @return [Boolean] true if the attribute is required, false otherwise

data/lib/cmdx/attribute_value.rb

@@ -18,7 +18,7 @@ module CMDx
     # @rbs @attribute: Attribute
     attr_reader :attribute
 
-    def_delegators :attribute, :task, :parent, :name, :options, :types, :source, :method_name, :required?
+    def_delegators :attribute, :task, :parent, :name, :options, :types, :source, :method_name, :required?, :optional?
     def_delegators :task, :attributes, :errors
 
     # Creates a new attribute value manager for the given attribute.
@@ -113,10 +113,11 @@ module CMDx
 
       if required? && (parent.nil? || parent&.required?) && Utils::Condition.evaluate(task, options)
         case sourced_value
-        when Context, Hash then sourced_value.key?(name)
+        when Context then sourced_value.key?(name)
+        when Hash then sourced_value.key?(name.to_s) || sourced_value.key?(name.to_sym)
         when Proc then true # HACK: Cannot be determined so assume it will respond
         else sourced_value.respond_to?(name, true)
-        end || errors.add(method_name, Locale.t("cmdx.attributes.required"))
+        end || errors.add(method_name, Locale.t("cmdx.attributes.required", method: source))
       end
 
       sourced_value
@@ -164,10 +165,16 @@ module CMDx
     def derive_value(source_value)
       derived_value =
         case source_value
-        when Context, Hash then source_value[name]
+        when Context then source_value[name]
+        when Hash then source_value[name.to_s] || source_value[name.to_sym]
         when Symbol then source_value.send(name)
         when Proc then task.instance_exec(name, &source_value)
-        else source_value.call(task, name) if source_value.respond_to?(:call)
+        else
+          if source_value.respond_to?(:call)
+            source_value.call(task, name)
+          elsif source_value.respond_to?(name, true)
+            source_value.send(name)
+          end
         end
 
       derived_value.nil? ? default_value : derived_value
@@ -222,16 +229,17 @@ module CMDx
       rescue CoercionError => e
         next if i != last_idx
 
-        message =
-          if last_idx.zero?
-            e.message
-          else
-            tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
-            Locale.t("cmdx.coercions.into_any", types: tl)
-          end
+        unless optional? && transformed_value.nil?
+          message =
+            if last_idx.zero?
+              e.message
+            else
+              tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
+              Locale.t("cmdx.coercions.into_any", types: tl)
+            end
 
-        errors.add(method_name, message)
-        nil
+          errors.add(method_name, message)
+        end
       end
     end
 

data/lib/cmdx/chain.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Manages a collection of task execution results in a thread-safe manner.
+  # 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.
   class Chain
 
     extend Forwardable
 
-    # @rbs THREAD_KEY: Symbol
-    THREAD_KEY = :cmdx_chain
+    # @rbs CONCURRENCY_KEY: Symbol
+    CONCURRENCY_KEY = :cmdx_chain
 
     # Returns the unique identifier for this chain.
     #
@@ -47,7 +47,7 @@ module CMDx
 
     class << self
 
-      # Retrieves the current chain for the current thread.
+      # Retrieves the current chain for the current execution context.
       #
       # @return [Chain, nil] The current chain or nil if none exists
       #
@@ -59,10 +59,10 @@ module CMDx
       #
       # @rbs () -> Chain?
       def current
-        Thread.current[THREAD_KEY]
+        thread_or_fiber[CONCURRENCY_KEY]
       end
 
-      # Sets the current chain for the current thread.
+      # Sets the current chain for the current execution context.
       #
       # @param chain [Chain] The chain to set as current
       #
@@ -73,10 +73,10 @@ module CMDx
       #
       # @rbs (Chain chain) -> Chain
       def current=(chain)
-        Thread.current[THREAD_KEY] = chain
+        thread_or_fiber[CONCURRENCY_KEY] = chain
       end
 
-      # Clears the current chain for the current thread.
+      # Clears the current chain for the current execution context.
       #
       # @return [nil] Always returns nil
       #
@@ -85,7 +85,7 @@ module CMDx
       #
       # @rbs () -> nil
       def clear
-        Thread.current[THREAD_KEY] = nil
+        thread_or_fiber[CONCURRENCY_KEY] = nil
       end
 
       # Builds or extends the current chain by adding a result.
@@ -111,6 +111,17 @@ module CMDx
         current
       end
 
+      private
+
+      # Returns the thread or fiber storage for the current execution context.
+      #
+      # @return [Hash] The thread or fiber storage
+      #
+      # @rbs () -> Hash
+      def thread_or_fiber
+        Fiber.respond_to?(:storage) ? Fiber.storage : Thread.current
+      end
+
     end
 
     # Returns whether the chain is running in dry-run mode.

data/lib/cmdx/coercions/array.rb

@@ -5,7 +5,7 @@ module CMDx
     # Converts various input types to Array format
     #
     # Handles conversion from strings that look like JSON arrays and other
-    # values that can be converted to arrays using Ruby's Array() method.
+    # values that can be wrapped in an array using Ruby's Array() method.
     module Array
 
       extend self
@@ -29,8 +29,11 @@ module CMDx
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Array[untyped]
       def call(value, options = {})
-        if value.is_a?(::String) && value.start_with?("[")
-          JSON.parse(value)
+        if value.is_a?(::String) && (
+          value.start_with?("[") ||
+          value.strip == "null"
+        )
+          JSON.parse(value) || []
         else
           Array(value)
         end

data/lib/cmdx/coercions/hash.rb

@@ -9,6 +9,7 @@ module CMDx
     # - Hash objects (returned as-is)
     # - Array objects (converted using Hash[*array])
     # - JSON strings starting with "{" (parsed into Hash)
+    # - JSON strings that are "null" (parsed into empty Hash)
     # - Other types raise CoercionError
     module Hash
 
@@ -39,8 +40,11 @@ module CMDx
           value
         elsif value.is_a?(::Array)
           ::Hash[*value]
-        elsif value.is_a?(::String) && value.start_with?("{")
-          JSON.parse(value)
+        elsif value.is_a?(::String) && (
+          value.start_with?("{") ||
+          value.strip == "null"
+        )
+          JSON.parse(value) || {}
         elsif value.respond_to?(:to_h)
           value.to_h
         else

data/lib/cmdx/executor.rb

@@ -66,6 +66,7 @@ module CMDx
       task.class.settings[:middlewares].call!(task) do
         pre_execution! unless @pre_execution
         execution!
+        verify_returns!
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
@@ -97,6 +98,7 @@ module CMDx
       task.class.settings[:middlewares].call!(task) do
         pre_execution! unless @pre_execution
         execution!
+        verify_returns!
       rescue UndefinedMethodError => e
         raise_exception(e)
       rescue Fault => e
@@ -231,6 +233,27 @@ module CMDx
       task.work
     end
 
+    # Verifies that all declared returns are present in the context after execution.
+    #
+    # @rbs () -> void
+    def verify_returns!
+      return unless result.success?
+
+      returns = 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"),
+        errors: {
+          full_message: task.errors.to_s,
+          messages: task.errors.to_h
+        }
+      )
+    end
+
     # Performs post-execution tasks including callback invocation.
     #
     # @rbs () -> void

data/lib/cmdx/middlewares/correlate.rb

@@ -4,18 +4,18 @@ module CMDx
   module Middlewares
     # Middleware for correlating task executions with unique identifiers.
     #
-    # The Correlate middleware provides thread-safe correlation ID management
-    # for tracking task execution flows across different operations.
-    # It automatically generates correlation IDs when none are provided and
-    # stores them in task result metadata for traceability.
+    # The Correlate middleware provides thread and fiber safe correlation ID management
+    # for tracking task execution flows across different operations. It automatically
+    # generates correlation IDs when none are provided and stores them in task result
+    # metadata for traceability.
     module Correlate
 
       extend self
 
-      # @rbs THREAD_KEY: Symbol
-      THREAD_KEY = :cmdx_correlate
+      # @rbs CONCURRENCY_KEY: Symbol
+      CONCURRENCY_KEY = :cmdx_correlate
 
-      # Retrieves the current correlation ID from thread-local storage.
+      # Retrieves the current correlation ID from local storage.
       #
       # @return [String, nil] The current correlation ID or nil if not set
       #
@@ -24,10 +24,10 @@ module CMDx
       #
       # @rbs () -> String?
       def id
-        Thread.current[THREAD_KEY]
+        thread_or_fiber[CONCURRENCY_KEY]
       end
 
-      # Sets the correlation ID in thread-local storage.
+      # Sets the correlation ID in local storage.
       #
       # @param id [String] The correlation ID to set
       # @return [String] The set correlation ID
@@ -37,10 +37,10 @@ module CMDx
       #
       # @rbs (String id) -> String
       def id=(id)
-        Thread.current[THREAD_KEY] = id
+        thread_or_fiber[CONCURRENCY_KEY] = id
       end
 
-      # Clears the current correlation ID from thread-local storage.
+      # Clears the current correlation ID from local storage.
       #
       # @return [nil] Always returns nil
       #
@@ -49,7 +49,7 @@ module CMDx
       #
       # @rbs () -> nil
       def clear
-        Thread.current[THREAD_KEY] = nil
+        thread_or_fiber[CONCURRENCY_KEY] = nil
       end
 
       # Temporarily uses a new correlation ID for the duration of a block.
@@ -122,6 +122,17 @@ module CMDx
         use(correlation_id, &)
       end
 
+      private
+
+      # Returns the thread or fiber storage for the current execution context.
+      #
+      # @return [Hash] The thread or fiber storage
+      #
+      # @rbs () -> Hash
+      def thread_or_fiber
+        Fiber.respond_to?(:storage) ? Fiber.storage : Thread.current
+      end
+
     end
   end
 end

data/lib/cmdx/task.rb

@@ -130,6 +130,7 @@ module CMDx
             end
 
           hash[:attributes] ||= AttributeRegistry.new
+          hash[:returns] ||= []
           hash[:tags] ||= []
 
           hash.merge!(options)
@@ -217,6 +218,33 @@ module CMDx
       end
       alias remove_attribute remove_attributes
 
+      # Declares expected context returns that must be set after task execution.
+      # If any declared return is missing from the context after {#work} completes
+      # successfully, the task will fail with a validation error.
+      #
+      # @param names [Array<Symbol, String>] Names of expected return keys in the context
+      #
+      # @example
+      #   returns :user, :token
+      #
+      # @rbs (*untyped names) -> void
+      def returns(*names)
+        settings[:returns] |= names.map(&:to_sym)
+      end
+
+      # Removes declared returns from the task.
+      #
+      # @param names [Array<Symbol>] Names of returns to remove
+      #
+      # @example
+      #   remove_returns :old_return
+      #
+      # @rbs (*Symbol names) -> void
+      def remove_returns(*names)
+        settings[:returns] -= names.map(&:to_sym)
+      end
+      alias remove_return remove_returns
+
       # @return [Hash] Hash of attribute names to their configurations
       #
       # @example
@@ -231,8 +259,8 @@ module CMDx
       #
       # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
       def attributes_schema
-        Array(settings[:attributes]).each_with_object({}) do |attr, schema|
-          schema[attr.method_name] = attr.to_h
+        Array(settings[:attributes]).to_h do |attr|
+          [attr.method_name, attr.to_h]
         end
       end
 
@@ -323,6 +351,10 @@ module CMDx
       raise UndefinedMethodError, "undefined method #{self.class.name}#work"
     end
 
+    # Returns a logger for this task. When a custom log_level or
+    # log_formatter is configured, the shared logger is duplicated
+    # so the original instance is never mutated.
+    #
     # @return [Logger] The logger instance for this task
     #
     # @example
@@ -332,10 +364,17 @@ module CMDx
     # @rbs () -> Logger
     def logger
       @logger ||= begin
-        logger = self.class.settings[:logger] || CMDx.configuration.logger
-        logger.level = self.class.settings[:log_level] || logger.level
-        logger.formatter = self.class.settings[:log_formatter] || logger.formatter
-        logger
+        log_instance = self.class.settings[:logger] || CMDx.configuration.logger
+        log_level = self.class.settings[:log_level]
+        log_formatter = self.class.settings[:log_formatter]
+
+        if log_level || log_formatter
+          log_instance = log_instance.dup
+          log_instance.level = log_level if log_level
+          log_instance.formatter = log_formatter if log_formatter
+        end
+
+        log_instance
       end
     end
 

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.16.0"
+  VERSION = "1.18.0"
 
 end

data/lib/locales/af.yml

@@ -1,13 +1,15 @@
 af:
   cmdx:
     attributes:
-      required: "moet toeganklik wees via die bron"
+      required: "moet toeganklik wees via die %{method} bronmetode"
       undefined: "delegeer na ongedefinieerde metode %{method}"
     coercions:
       into_a: "kon nie na %{type} omskep word nie"
       into_an: "kon nie na %{type} omskep word nie"
       into_any: "kon nie na een van: %{types} omskep word nie"
       unknown: "onbekende %{type} omskep tipe"
+    returns:
+      missing: "moet in die konteks gestel word"
     faults:
       invalid: "Ongeldig"
       unspecified: "Ongespesifiseer"

data/lib/locales/ar.yml

@@ -1,13 +1,15 @@
 ar:
   cmdx:
     attributes:
-      required: "يجب أن يكون قابلاً للوصول عبر المصدر"
+      required: "يجب أن يكون قابلاً للوصول عبر طريقة المصدر %{method}"
       undefined: "يفوض إلى طريقة غير معرفة %{method}"
     coercions:
       into_a: "لا يمكن تحويله إلى %{type}"
       into_an: "لا يمكن تحويله إلى %{type}"
       into_any: "لا يمكن تحويله إلى واحد من: %{types}"
       unknown: "نوع تحويل %{type} غير معروف"
+    returns:
+      missing: "يجب تعيينه في السياق"
     faults:
       invalid: "غير صالح"
       unspecified: "غير محدد"

data/lib/locales/az.yml

@@ -1,13 +1,15 @@
 az:
   cmdx:
     attributes:
-      required: "mənbə vasitəsilə əlçatan olmalıdır"
+      required: "%{method} mənbə metodu vasitəsilə əlçatan olmalıdır"
       undefined: "müəyyən edilməmiş metoda %{method} təyin edir"
     coercions:
       into_a: "%{type} tipinə çevrilə bilmədi"
       into_an: "%{type} tipinə çevrilə bilmədi"
       into_any: "aşağıdakılardan birinə çevrilə bilmədi: %{types}"
       unknown: "naməlum %{type} çevrilmə tipi"
+    returns:
+      missing: "kontekstdə təyin edilməlidir"
     faults:
       invalid: "Etibarsız"
       unspecified: "Göstərilməyib"

data/lib/locales/be.yml

@@ -1,13 +1,15 @@
 be:
   cmdx:
     attributes:
-      required: "павінна быць даступна праз крыніцу"
+      required: "павінен быць даступны праз зыходны метад %{method}"
       undefined: "дэлегуе невызначанаму метаду %{method}"
     coercions:
       into_a: "не ўдалося пераўтварыць у %{type}"
       into_an: "не ўдалося пераўтварыць у %{type}"
       into_any: "не ўдалося пераўтварыць у адзін з: %{types}"
       unknown: "невядомы тып пераўтварэння %{type}"
+    returns:
+      missing: "павінна быць усталявана ў кантэксце"
     faults:
       invalid: "Няправільныя"
       unspecified: "Не паказана"

data/lib/locales/bg.yml

@@ -1,13 +1,15 @@
 bg:
   cmdx:
     attributes:
-      required: "трябва да бъде достъпен чрез източника"
+      required: "трябва да е достъпен чрез изходния метод %{method}"
       undefined: "делегира към недефиниран метод %{method}"
     coercions:
       into_a: "не може да бъде преобразуван в %{type}"
       into_an: "не може да бъде преобразуван в %{type}"
       into_any: "не може да бъде преобразуван в един от: %{types}"
       unknown: "неизвестен тип преобразуване %{type}"
+    returns:
+      missing: "трябва да бъде зададено в контекста"
     faults:
       invalid: "Невалидни"
       unspecified: "Не е посочена"

data/lib/locales/bn.yml

@@ -1,13 +1,15 @@
 bn:
   cmdx:
     attributes:
-      required: "উৎসের মাধ্যমে অ্যাক্সেসযোগ্য হতে হবে"
+      required: "%{method} সোর্স মেথডের মাধ্যমে অ্যাক্সেসযোগ্য হতে হবে"
       undefined: "অসংজ্ঞায়িত পদ্ধতিতে %{method} অর্পণ করে"
     coercions:
       into_a: "%{type} এ রূপান্তর করা যায়নি"
       into_an: "%{type} এ রূপান্তর করা যায়নি"
       into_any: "নিম্নলিখিতগুলির মধ্যে একটিতে রূপান্তর করা যায়নি: %{types}"
       unknown: "অজানা %{type} রূপান্তর প্রকার"
+    returns:
+      missing: "প্রসঙ্গে সেট করতে হবে"
     faults:
       invalid: "অবৈধ"
       unspecified: "অনির্দিষ্ট"

data/lib/locales/bs.yml

@@ -1,13 +1,15 @@
 bs:
   cmdx:
     attributes:
-      required: "mora biti dostupan kroz izvor"
+      required: "mora biti dostupan preko izvorne metode %{method}"
       undefined: "delegira nedefiniranoj metodi %{method}"
     coercions:
       into_a: "nije mogao biti pretvoren u %{type}"
       into_an: "nije mogao biti pretvoren u %{type}"
       into_any: "nije mogao biti pretvoren u jedan od: %{types}"
       unknown: "nepoznati tip pretvorbe %{type}"
+    returns:
+      missing: "mora biti postavljeno u kontekstu"
     faults:
       invalid: "Neispravni"
       unspecified: "Nije naveden"

data/lib/locales/ca.yml

@@ -1,13 +1,15 @@
 ca:
   cmdx:
     attributes:
-      required: "ha de ser accessible a través de la font"
+      required: "ha de ser accessible mitjançant el mètode font %{method}"
       undefined: "delega al mètode no definit %{method}"
     coercions:
       into_a: "no es va poder convertir a %{type}"
       into_an: "no es va poder convertir a %{type}"
       into_any: "no es va poder convertir a un de: %{types}"
       unknown: "tipus de conversió %{type} desconegut"
+    returns:
+      missing: "ha de ser establert en el context"
     faults:
       invalid: "No vàlides"
       unspecified: "No especificat"

data/lib/locales/cnr.yml

@@ -1,13 +1,15 @@
 cnr:
   cmdx:
     attributes:
-      required: "mora biti dostupan preko izvora"
+      required: "mora biti dostupan preko izvorne metode %{method}"
       undefined: "delegira na nedefinisani metod %{method}"
     coercions:
       into_a: "nije mogao konvertovati u %{type}"
       into_an: "nije mogao konvertovati u %{type}"
       into_any: "nije mogao konvertovati u jedan od: %{types}"
       unknown: "nepoznati %{type} tip konverzije"
+    returns:
+      missing: "mora biti postavljeno u kontekstu"
     faults:
       invalid: "Neispravni"
       unspecified: "Nije dat"

data/lib/locales/cs.yml

@@ -1,13 +1,15 @@
 cs:
   cmdx:
     attributes:
-      required: "musí být přístupné přes zdroj"
+      required: "musí být přístupné přes zdrojovou metodu %{method}"
       undefined: "deleguje na nedefinovanou metodu %{method}"
     coercions:
       into_a: "nelze převést na %{type}"
       into_an: "nelze převést na %{type}"
       into_any: "nelze převést na jeden z: %{types}"
       unknown: "neznámý typ převodu %{type}"
+    returns:
+      missing: "musí být nastaveno v kontextu"
     faults:
       invalid: "Neplatné"
       unspecified: "Neurčeno"