cmdx 1.21.0 → 2.0.0

data/lib/cmdx/locale.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Provides internationalization and localization support for CMDx.
-  # Handles translation lookups with fallback to the configured locale's
-  # default messages when I18n gem is not available.
-  module Locale
-
-    extend self
-
-    # Translates a key to the current locale with optional interpolation.
-    # Falls back to the configured locale's YAML file translations if
-    # I18n gem is unavailable.
-    #
-    # @param key [String, Symbol] The translation key (supports dot notation)
-    # @param options [Hash] Translation options
-    # @option options [String] :default Fallback message if translation missing
-    # @option options [String] :locale Target locale (when I18n available)
-    # @option options [Hash] :scope Translation scope (when I18n available)
-    # @option options [Object] :* Any other options passed to I18n.t or string interpolation
-    #
-    # @return [String] The translated message
-    #
-    # @raise [ArgumentError] When interpolation fails due to missing keys
-    #
-    # @example Basic translation
-    #   Locale.translate("errors.invalid_input")
-    #   # => "Invalid input provided"
-    # @example With interpolation
-    #   Locale.translate("welcome.message", name: "John")
-    #   # => "Welcome, John!"
-    # @example With fallback
-    #   Locale.translate("missing.key", default: "Custom fallback message")
-    #   # => "Custom fallback message"
-    #
-    # @rbs ((String | Symbol) key, **untyped options) -> String
-    def translate(key, **options)
-      options[:default] ||= translation_default(key)
-      return ::I18n.t(key, **options) if defined?(::I18n)
-
-      case message = options.delete(:default)
-      when String then message % options
-      when NilClass then "Translation missing: #{key}"
-      else message
-      end
-    end
-
-    # @see #translate
-    alias t translate
-
-    private
-
-    # Resolves and caches the default translation for a key by digging
-    # into the configured locale's YAML translations.
-    #
-    # @param key [String, Symbol] The translation key
-    #
-    # @return [String, nil] The resolved translation or nil
-    #
-    # @rbs ((String | Symbol) key) -> String?
-    def translation_default(key)
-      tkey = "#{CMDx.configuration.default_locale}.#{key}"
-
-      @translation_defaults ||= {}
-      return @translation_defaults[tkey] if @translation_defaults.key?(tkey)
-
-      @default_translations ||= begin
-        path = CMDx.gem_path.join("lib/locales/#{CMDx.configuration.default_locale}.yml")
-        raise ArgumentError, "locale file not found: #{path}" unless path.exist?
-
-        YAML.load_file(path).freeze
-      end
-
-      @translation_defaults[tkey] = @default_translations.dig(*tkey.split("."))
-    end
-
-  end
-end

data/lib/cmdx/middleware_registry.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Registry for managing middleware components in a task execution chain.
-  #
-  # The MiddlewareRegistry maintains an ordered list of middleware components
-  # that can be inserted, removed, and executed in sequence. Each middleware
-  # can be configured with specific options and is executed in the order
-  # they were registered.
-  #
-  # Supports copy-on-write semantics: a duped registry shares the parent's
-  # data until a write operation triggers materialization.
-  class MiddlewareRegistry
-
-    # Initialize a new middleware registry.
-    #
-    # @param registry [Array, nil] Initial array of middleware entries
-    #
-    # @example
-    #   registry = MiddlewareRegistry.new
-    #   registry = MiddlewareRegistry.new([[MyMiddleware, {option: 'value'}]])
-    #
-    # @rbs (?Array[Array[untyped]]? registry) -> void
-    def initialize(registry = nil)
-      @registry = registry || []
-    end
-
-    # Sets up copy-on-write state when duplicated via dup.
-    #
-    # @param source [MiddlewareRegistry] The registry being duplicated
-    #
-    # @rbs (MiddlewareRegistry source) -> void
-    def initialize_dup(source)
-      @parent = source
-      @registry = nil
-      super
-    end
-
-    # Returns the ordered collection of middleware entries.
-    # Delegates to the parent registry when not yet materialized.
-    #
-    # @return [Array<Array>] Array of middleware-options pairs
-    #
-    # @example
-    #   registry.registry # => [[LoggingMiddleware, {level: :debug}], [AuthMiddleware, {}]]
-    #
-    # @rbs () -> Array[Array[untyped]]
-    def registry
-      @registry || @parent.registry
-    end
-    alias to_a registry
-
-    # Register a middleware component in the registry.
-    #
-    # @param middleware [Object] The middleware object to register
-    # @param at [Integer] Position to insert the middleware (default: -1, end of list)
-    # @param options [Hash] Configuration options for the middleware
-    # @option options [Symbol] :key Configuration key for the middleware
-    # @option options [Object] :value Configuration value for the middleware
-    #
-    # @return [MiddlewareRegistry] Returns self for method chaining
-    #
-    # @example
-    #   registry.register(LoggingMiddleware, at: 0, log_level: :debug)
-    #   registry.register(AuthMiddleware, at: -1, timeout: 30)
-    #
-    # @rbs (untyped middleware, ?at: Integer, **untyped options) -> self
-    def register(middleware, at: -1, **options)
-      materialize!
-
-      @registry.insert(at, [middleware, options])
-      self
-    end
-
-    # Remove a middleware component from the registry.
-    #
-    # @param middleware [Object] The middleware object to remove
-    #
-    # @return [MiddlewareRegistry] Returns self for method chaining
-    #
-    # @example
-    #   registry.deregister(LoggingMiddleware)
-    #
-    # @rbs (untyped middleware) -> self
-    def deregister(middleware)
-      materialize!
-
-      @registry.reject! { |mw, _opts| mw == middleware }
-      self
-    end
-
-    # Execute the middleware chain for a given task.
-    #
-    # @param task [Object] The task object to process through middleware
-    #
-    # @yield [task] Block to execute after all middleware processing
-    # @yieldparam task [Object] The processed task object
-    #
-    # @return [Object] Result of the block execution
-    #
-    # @raise [ArgumentError] When no block is provided
-    #
-    # @example
-    #   result = registry.call!(my_task) do |processed_task|
-    #     processed_task.execute
-    #   end
-    #
-    # @rbs (untyped task) { (untyped) -> untyped } -> untyped
-    def call!(task, &)
-      raise ArgumentError, "block required" unless block_given?
-
-      recursively_call_middleware(0, task, &)
-    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.map(&:dup)
-      @parent = nil
-    end
-
-    # Recursively execute middleware in the chain.
-    #
-    # @param index [Integer] Current middleware index in the chain
-    # @param task [Object] The task object being processed
-    # @param block [Proc] Block to execute after middleware processing
-    #
-    # @yield [task] Block to execute after middleware processing
-    # @yieldparam task [Object] The processed task object
-    #
-    # @return [Object] Result of the block execution or next middleware call
-    #
-    # @rbs (Integer index, untyped task) { (untyped) -> untyped } -> untyped
-    def recursively_call_middleware(index, task, &block)
-      return yield(task) if index >= registry.size
-
-      middleware, options = registry[index]
-      middleware.call(task, **options) { recursively_call_middleware(index + 1, task, &block) }
-    end
-
-  end
-end

data/lib/cmdx/middlewares/correlate.rb

@@ -1,140 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Middlewares
-    # Middleware for correlating task executions with unique identifiers.
-    #
-    # 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 CONCURRENCY_KEY: Symbol
-      CONCURRENCY_KEY = :cmdx_correlate
-
-      # Retrieves the current correlation ID from local storage.
-      #
-      # @return [String, nil] The current correlation ID or nil if not set
-      #
-      # @example Get current correlation ID
-      #   Correlate.id # => "550e8400-e29b-41d4-a716-446655440000"
-      #
-      # @rbs () -> String?
-      def id
-        thread_or_fiber[CONCURRENCY_KEY]
-      end
-
-      # Sets the correlation ID in local storage.
-      #
-      # @param id [String] The correlation ID to set
-      # @return [String] The set correlation ID
-      #
-      # @example Set correlation ID
-      #   Correlate.id = "abc-123-def"
-      #
-      # @rbs (String id) -> String
-      def id=(id)
-        thread_or_fiber[CONCURRENCY_KEY] = id
-      end
-
-      # Clears the current correlation ID from local storage.
-      #
-      # @return [nil] Always returns nil
-      #
-      # @example Clear correlation ID
-      #   Correlate.clear
-      #
-      # @rbs () -> nil
-      def clear
-        thread_or_fiber[CONCURRENCY_KEY] = nil
-      end
-
-      # Temporarily uses a new correlation ID for the duration of a block.
-      # Restores the previous ID after the block completes, even if an error occurs.
-      #
-      # @param new_id [String] The correlation ID to use temporarily
-      # @yield The block to execute with the new correlation ID
-      # @return [Object] The result of the yielded block
-      #
-      # @example Use temporary correlation ID
-      #   Correlate.use("temp-id") do
-      #     # Operations here use "temp-id"
-      #     perform_operation
-      #   end
-      #   # Previous ID is restored
-      #
-      # @rbs (String new_id) { () -> untyped } -> untyped
-      def use(new_id)
-        old_id = id
-        self.id = new_id
-        yield
-      ensure
-        self.id = old_id
-      end
-
-      # Middleware entry point that applies correlation ID logic to task execution.
-      #
-      # Evaluates the condition from options and applies correlation ID handling
-      # if enabled. Generates or retrieves correlation IDs based on the :id option
-      # and stores them in task result metadata.
-      #
-      # @param task [Task] The task being executed
-      # @param options [Hash] Configuration options for correlation
-      # @option options [Symbol, Proc, Object, nil] :id The correlation ID source
-      # @option options [Symbol, Proc, Object, nil] :if Condition to enable correlation
-      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable correlation
-      #
-      # @yield The task execution block
-      #
-      # @return [Object] The result of task execution
-      #
-      # @example Basic usage with automatic ID generation
-      #   Correlate.call(task, &block)
-      # @example Use custom correlation ID
-      #   Correlate.call(task, id: "custom-123", &block)
-      # @example Use task method for ID
-      #   Correlate.call(task, id: :correlation_id, &block)
-      # @example Use proc for dynamic ID generation
-      #   Correlate.call(task, id: -> { "dynamic-#{Time.now.to_i}" }, &block)
-      # @example Conditional correlation
-      #   Correlate.call(task, if: :enable_correlation, &block)
-      #
-      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
-      def call(task, **options, &)
-        return yield unless Utils::Condition.evaluate(task, options)
-
-        correlation_id = task.result.metadata[:correlation_id] ||=
-          id ||
-          case callable = options[:id]
-          when Symbol then task.send(callable)
-          when Proc then task.instance_eval(&callable)
-          else
-            if callable.respond_to?(:call)
-              callable.call(task)
-            else
-              callable || id || Identifier.generate
-            end
-          end
-
-        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
-      if Fiber.respond_to?(:storage)
-        def thread_or_fiber = Fiber.storage
-      else
-        def thread_or_fiber = Thread.current
-      end
-
-    end
-  end
-end

data/lib/cmdx/middlewares/runtime.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Middlewares
-    # Middleware for measuring task execution runtime.
-    #
-    # The Runtime middleware provides performance monitoring by measuring
-    # the execution time of tasks using monotonic clock for accuracy.
-    # It stores runtime measurements in task result metadata for analysis.
-    module Runtime
-
-      extend self
-
-      # Middleware entry point that measures task execution runtime and
-      # task execution start and end times.
-      #
-      # Evaluates the condition from options and measures execution time
-      # if enabled. Uses monotonic clock for precise timing measurements
-      # and stores the result in task metadata.
-      #
-      # @param task [Task] The task being executed
-      # @param options [Hash] Configuration options for runtime measurement
-      # @option options [Symbol, Proc, Object, nil] :if Condition to enable runtime measurement
-      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable runtime measurement
-      #
-      # @yield The task execution block
-      #
-      # @return [Object] The result of task execution
-      #
-      # @example Basic usage with automatic runtime measurement
-      #   Runtime.call(task, &block)
-      # @example Conditional runtime measurement
-      #   Runtime.call(task, if: :enable_profiling, &block)
-      # @example Disable runtime measurement
-      #   Runtime.call(task, unless: :skip_profiling, &block)
-      #
-      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
-      def call(task, **options)
-        unow = utc_time
-        mnow = monotonic_time
-        return yield unless Utils::Condition.evaluate(task, options)
-
-        result = yield
-        task.result.metadata.merge!(
-          runtime: monotonic_time - mnow,
-          ended_at: utc_time,
-          started_at: unow
-        )
-        result
-      end
-
-      private
-
-      # Gets the current monotonic time in milliseconds.
-      #
-      # Uses Process.clock_gettime with CLOCK_MONOTONIC for consistent
-      # timing measurements that are not affected by system clock changes.
-      #
-      # @return [Integer] Current monotonic time in milliseconds
-      #
-      # @rbs () -> Integer
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-      end
-
-      # Gets the current UTC time in ISO 8601 format.
-      #
-      # @return [String] Current UTC time in ISO 8601 format
-      #
-      # @rbs () -> String
-      def utc_time
-        Time.now.utc.iso8601
-      end
-
-    end
-  end
-end

data/lib/cmdx/middlewares/timeout.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Middlewares
-    # Middleware for enforcing execution time limits on tasks.
-    #
-    # The Timeout middleware provides execution time control by wrapping
-    # task execution with Ruby's Timeout module. It automatically fails
-    # tasks that exceed the configured time limit and provides detailed
-    # error information including the exceeded limit.
-    module Timeout
-
-      extend self
-
-      # Default timeout limit in seconds when none is specified.
-      #
-      # @rbs DEFAULT_LIMIT: Integer
-      DEFAULT_LIMIT = 3
-
-      # Middleware entry point that enforces execution time limits.
-      #
-      # Evaluates the condition from options and applies timeout control
-      # if enabled. Supports various timeout limit configurations including
-      # numeric values, task method calls, and dynamic proc evaluation.
-      #
-      # @param task [Task] The task being executed
-      # @param options [Hash] Configuration options for timeout control
-      # @option options [Numeric, Symbol, Proc, Object] :seconds The timeout limit source
-      # @option options [Symbol, Proc, Object, nil] :if Condition to enable timeout control
-      # @option options [Symbol, Proc, Object, nil] :unless Condition to disable timeout control
-      #
-      # @yield The task execution block
-      #
-      # @return [Object] The result of task execution
-      #
-      # @raise [TimeoutError] When execution exceeds the configured limit
-      #
-      # @example Basic usage with default 3 second timeout
-      #   Timeout.call(task, &block)
-      # @example Custom timeout limit in seconds
-      #   Timeout.call(task, seconds: 10, &block)
-      # @example Use task method for timeout limit
-      #   Timeout.call(task, seconds: :timeout_limit, &block)
-      # @example Use proc for dynamic timeout calculation
-      #   Timeout.call(task, seconds: -> { calculate_timeout }, &block)
-      # @example Conditional timeout control
-      #   Timeout.call(task, if: :enable_timeout, &block)
-      #
-      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
-      def call(task, **options, &)
-        return yield unless Utils::Condition.evaluate(task, options)
-
-        limit =
-          case callable = options[:seconds]
-          when Numeric then callable
-          when Symbol then task.send(callable)
-          when Proc then task.instance_eval(&callable)
-          else callable.respond_to?(:call) ? callable.call(task) : DEFAULT_LIMIT
-          end
-
-        limit = Float(limit)
-        return yield unless limit.positive?
-
-        ::Timeout.timeout(limit, TimeoutError, "execution exceeded #{limit} seconds", &)
-      rescue TimeoutError => e
-        task.result.tap do |r|
-          r.fail!(
-            Utils::Normalize.exception(e),
-            cause: e,
-            source: :timeout,
-            limit:
-          )
-        end
-      end
-
-    end
-  end
-end

data/lib/cmdx/parallelizer.rb

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Bounded thread pool that processes items concurrently.
-  #
-  # Distributes work across a fixed number of threads using a queue,
-  # collecting results in submission order.
-  class Parallelizer
-
-    # Returns the items to process.
-    #
-    # @return [Array] the items to process
-    #
-    # @example
-    #   parallelizer.items # => [1, 2, 3]
-    #
-    # @rbs @items: Array[untyped]
-    attr_reader :items
-
-    # Returns the number of threads in the pool.
-    #
-    # @return [Integer] the thread pool size
-    #
-    # @example
-    #   parallelizer.pool_size # => 4
-    #
-    # @rbs @pool_size: Integer
-    attr_reader :pool_size
-
-    # Creates a new Parallelizer instance.
-    #
-    # @param items [Array] the items to process concurrently
-    # @param pool_size [Integer] number of threads (defaults to item count)
-    #
-    # @return [Parallelizer] a new parallelizer instance
-    #
-    # @example
-    #   Parallelizer.new([1, 2, 3], pool_size: 2)
-    #
-    # @rbs (Array[untyped] items, ?pool_size: Integer) -> void
-    def initialize(items, pool_size: nil)
-      @items = items
-      @pool_size = Integer(pool_size || items.size)
-    end
-
-    # Processes items concurrently and returns results in submission order.
-    #
-    # @param items [Array] the items to process concurrently
-    # @param pool_size [Integer] number of threads (defaults to item count)
-    #
-    # @yield [item] block called for each item in a worker thread
-    # @yieldparam item [Object] an item from the items array
-    # @yieldreturn [Object] the result for this item
-    #
-    # @return [Array] results in the same order as input items
-    #
-    # @example
-    #   Parallelizer.call([1, 2, 3], pool_size: 2) { |n| n * 10 }
-    #   # => [10, 20, 30]
-    #
-    # @rbs [T, R] (Array[T] items, ?pool_size: Integer) { (T) -> R } -> Array[R]
-    def self.call(items, pool_size: nil, &block)
-      new(items, pool_size:).call(&block)
-    end
-
-    # Distributes items across the thread pool and returns results
-    # in submission order.
-    #
-    # @yield [item] block called for each item in a worker thread
-    # @yieldparam item [Object] an item from the items array
-    # @yieldreturn [Object] the result for this item
-    #
-    # @return [Array] results in the same order as input items
-    #
-    # @example
-    #   Parallelizer.new(%w[a b c]).call { |s| s.upcase }
-    #   # => ["A", "B", "C"]
-    #
-    # @rbs [T, R] () { (T) -> R } -> Array[R]
-    def call(&block)
-      results = Array.new(items.size)
-      queue = Queue.new
-
-      items.each_with_index { |item, i| queue << [item, i] }
-      pool_size.times { queue << nil }
-
-      Array.new(pool_size) do
-        Thread.new do
-          while (entry = queue.pop)
-            item, index = entry
-            results[index] = block.call(item) # rubocop:disable Performance/RedundantBlockCall
-          end
-        end
-      end.each(&:join)
-
-      results
-    end
-
-  end
-end

data/lib/cmdx/utils/call.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Utils
-    # Utility module for invoking callable objects with different invocation strategies.
-    #
-    # This module provides a unified interface for calling methods, procs, and other
-    # callable objects on target objects, handling the appropriate invocation method
-    # based on the callable type.
-    module Call
-
-      extend self
-
-      # Invokes a callable object on the target with the given arguments.
-      #
-      # @param target [Object] The target object to invoke the callable on
-      # @param callable [Symbol, Proc, #call] The callable to invoke
-      # @param args [Array] Positional arguments to pass to the callable
-      # @param kwargs [Hash] Keyword arguments to pass to the callable
-      # @option kwargs [Object] :* Any keyword arguments to pass to the callable
-      #
-      # @yield [Object] Block to pass to the callable
-      #
-      # @return [Object] The result of invoking the callable
-      #
-      # @raise [RuntimeError] When the callable cannot be invoked
-      #
-      # @example Invoking a method by symbol
-      #   Call.invoke(user, :name)
-      #   Call.invoke(user, :update, { name: 'John' })
-      # @example Invoking a proc
-      #   proc = ->(name) { "Hello #{name}" }
-      #   Call.invoke(user, proc, 'John')
-      # @example Invoking a callable object
-      #   callable = MyCallable.new
-      #   Call.invoke(user, callable, 'data')
-      #
-      # @rbs (untyped target, (Symbol | Proc | untyped) callable, *untyped args, **untyped kwargs) ?{ () -> untyped } -> untyped
-      def invoke(target, callable, *args, **kwargs, &)
-        if callable.is_a?(Symbol)
-          target.send(callable, *args, **kwargs, &)
-        elsif callable.is_a?(Proc)
-          target.instance_exec(*args, **kwargs, &callable)
-        elsif callable.respond_to?(:call)
-          callable.call(*args, **kwargs, &)
-        else
-          raise "cannot invoke #{callable}"
-        end
-      end
-
-    end
-  end
-end