cmdx 1.11.0 → 1.12.0

data/lib/cmdx/callback_registry.rb

@@ -53,9 +53,9 @@ module CMDx
     # @param type [Symbol] The callback type from TYPES
     # @param callables [Array<#call>] Callable objects to register
     # @param options [Hash] Options to pass to the callback
+    # @param block [Proc] Optional block to register as a callable
     # @option options [Hash] :if Condition hash for conditional execution
     # @option options [Hash] :unless Inverse condition hash for conditional execution
-    # @param block [Proc] Optional block to register as a callable
     #
     # @return [CallbackRegistry] self for method chaining
     #
@@ -83,6 +83,7 @@ module CMDx
     # @param callables [Array<#call>] Callable objects to remove
     # @param options [Hash] Options that were used during registration
     # @param block [Proc] Optional block to remove
+    # @option options [Object] :* Any option key-value pairs
     #
     # @return [CallbackRegistry] self for method chaining
     #

data/lib/cmdx/chain.rb

@@ -114,12 +114,11 @@ module CMDx
 
     # Converts the chain to a hash representation.
     #
-    # @return [Hash] Hash containing chain id and serialized results
-    #
     # @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]

data/lib/cmdx/coercion_registry.rb

@@ -20,7 +20,7 @@ module CMDx
 
     # Initialize a new coercion registry.
     #
-    # @param registry [Hash<Symbol, Class>, nil] optional initial registry hash
+    # @param registry [Hash{Symbol => Class}, nil] optional initial registry hash
     #
     # @example
     #   registry = CoercionRegistry.new
@@ -95,6 +95,7 @@ module CMDx
     # @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
     #

data/lib/cmdx/coercions/boolean.rb

@@ -11,10 +11,10 @@ module CMDx
       extend self
 
       # @rbs FALSEY: Regexp
-      FALSEY = /^(false|f|no|n|0)$/i
+      FALSEY = /\A(false|f|no|n|0)\z/i
 
       # @rbs TRUTHY: Regexp
-      TRUTHY = /^(true|t|yes|y|1)$/i
+      TRUTHY = /\A(true|t|yes|y|1)\z/i
 
       # Converts a value to a Boolean
       #
@@ -40,7 +40,7 @@ module CMDx
       #
       # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> bool
       def call(value, options = {})
-        case value.to_s.downcase
+        case value.to_s
         when FALSEY then false
         when TRUTHY then true
         else

data/lib/cmdx/coercions/complex.rb

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

data/lib/cmdx/coercions/string.rb

@@ -15,6 +15,7 @@ module CMDx
       #
       # @param value [Object] The value to coerce to a string
       # @param options [Hash] Optional configuration parameters (unused in this coercion)
+      # @option options [Object] :* Any configuration option (unused)
       #
       # @return [String] The coerced string value
       #

data/lib/cmdx/coercions/symbol.rb

@@ -15,6 +15,7 @@ module CMDx
       #
       # @param value [Object] The value to coerce to a symbol
       # @param options [Hash] Optional configuration parameters (unused in this coercion)
+      # @option options [Object] :* Any configuration option (unused)
       #
       # @return [Symbol] The coerced symbol value
       #

data/lib/cmdx/configuration.rb

@@ -160,7 +160,7 @@ module CMDx
 
     # Converts the configuration to a hash representation.
     #
-    # @return [Hash<Symbol, Object>] hash containing all configuration values
+    # @return [Hash{Symbol => Object}] hash containing all configuration values
     #
     # @example
     #   config = Configuration.new
@@ -205,8 +205,6 @@ module CMDx
 
   # Configures CMDx using a block that receives the configuration instance.
   #
-  # @param block [Proc] the configuration block
-  #
   # @yield [Configuration] the configuration instance to configure
   #
   # @return [Configuration] the configured configuration instance

data/lib/cmdx/context.rb

@@ -109,7 +109,6 @@ module CMDx
     # Fetches a value from the context by key, with optional default value.
     #
     # @param key [String, Symbol] the key to fetch
-    # @param default [Object] the default value if key is not found
     #
     # @yield [key] a block to compute the default value
     #
@@ -255,6 +254,7 @@ module CMDx
     # @param method_name [Symbol] the method name that was called
     # @param args [Array<Object>] arguments passed to the method
     # @param _kwargs [Hash] keyword arguments (unused)
+    # @option _kwargs [Object] :* Any keyword arguments (unused)
     #
     # @yield [Object] optional block
     #
@@ -263,7 +263,8 @@ module CMDx
     # @rbs (Symbol method_name, *untyped args, **untyped _kwargs) ?{ () -> untyped } -> untyped
     def method_missing(method_name, *args, **_kwargs, &)
       fetch(method_name) do
-        store(method_name[0..-2], args.first) if method_name.end_with?("=")
+        str_name = method_name.to_s
+        store(str_name.chop, args.first) if str_name.end_with?("=")
       end
     end
 

data/lib/cmdx/middleware_registry.rb

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

data/lib/cmdx/result.rb

@@ -129,26 +129,6 @@ module CMDx
       #
       # @rbs () -> bool
       define_method(:"#{s}?") { state == s }
-
-      # @param block [Proc] Block to execute conditionally
-      #
-      # @yield [self] Executes the block if result is in specified state
-      #
-      # @return [self] Returns self for method chaining
-      #
-      # @raise [ArgumentError] When no block is provided
-      #
-      # @example
-      #   result.handle_initialized { |r| puts "Starting execution" }
-      #   result.handle_complete { |r| puts "Task completed" }
-      #
-      # @rbs () { (Result) -> void } -> self
-      define_method(:"handle_#{s}") do |&block|
-        raise ArgumentError, "block required" unless block
-
-        block.call(self) if send(:"#{s}?")
-        self
-      end
     end
 
     # @return [self] Returns self for method chaining
@@ -171,25 +151,6 @@ module CMDx
       complete? || interrupted?
     end
 
-    # @param block [Proc] Block to execute conditionally
-    #
-    # @yield [self] Executes the block if task has been executed
-    #
-    # @return [self] Returns self for method chaining
-    #
-    # @raise [ArgumentError] When no block is provided
-    #
-    # @example
-    #   result.handle_executed { |r| puts "Task finished: #{r.outcome}" }
-    #
-    # @rbs () { (Result) -> void } -> self
-    def handle_executed(&)
-      raise ArgumentError, "block required" unless block_given?
-
-      yield(self) if executed?
-      self
-    end
-
     # @raise [RuntimeError] When attempting to transition from invalid state
     #
     # @example
@@ -241,26 +202,6 @@ module CMDx
       #
       # @rbs () -> bool
       define_method(:"#{s}?") { status == s }
-
-      # @param block [Proc] Block to execute conditionally
-      #
-      # @yield [self] Executes the block if result has specified status
-      #
-      # @return [self] Returns self for method chaining
-      #
-      # @raise [ArgumentError] When no block is provided
-      #
-      # @example
-      #   result.handle_success { |r| puts "Task succeeded" }
-      #   result.handle_failed { |r| puts "Task failed: #{r.reason}" }
-      #
-      # @rbs () { (Result) -> void } -> self
-      define_method(:"handle_#{s}") do |&block|
-        raise ArgumentError, "block required" unless block
-
-        block.call(self) if send(:"#{s}?")
-        self
-      end
     end
 
     # @return [Boolean] Whether the task execution was successful (not failed)
@@ -274,25 +215,6 @@ module CMDx
     end
     alias ok? good?
 
-    # @param block [Proc] Block to execute conditionally
-    #
-    # @yield [self] Executes the block if task execution was successful
-    #
-    # @return [self] Returns self for method chaining
-    #
-    # @raise [ArgumentError] When no block is provided
-    #
-    # @example
-    #   result.handle_good { |r| puts "Task completed successfully" }
-    #
-    # @rbs () { (Result) -> void } -> self
-    def handle_good(&)
-      raise ArgumentError, "block required" unless block_given?
-
-      yield(self) if good?
-      self
-    end
-
     # @return [Boolean] Whether the task execution was unsuccessful (not success)
     #
     # @example
@@ -303,22 +225,21 @@ module CMDx
       !success?
     end
 
-    # @param block [Proc] Block to execute conditionally
-    #
-    # @yield [self] Executes the block if task execution was unsuccessful
+    # @yield [self] Executes the block if task status or state matches
     #
     # @return [self] Returns self for method chaining
     #
     # @raise [ArgumentError] When no block is provided
     #
     # @example
-    #   result.handle_bad { |r| puts "Task had issues: #{r.reason}" }
+    #   result.on(:bad) { |r| puts "Task had issues: #{r.reason}" }
+    #   result.on(:success, :complete) { |r| puts "Task completed successfully" }
     #
     # @rbs () { (Result) -> void } -> self
-    def handle_bad(&)
+    def on(*states_or_statuses, &)
       raise ArgumentError, "block required" unless block_given?
 
-      yield(self) if bad?
+      yield(self) if states_or_statuses.any? { |s| send(:"#{s}?") }
       self
     end
 
@@ -326,6 +247,7 @@ module CMDx
     # @param halt [Boolean] Whether to halt execution after skipping
     # @param cause [Exception, nil] Exception that caused the skip
     # @param metadata [Hash] Additional metadata about the skip
+    # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
     # @raise [RuntimeError] When attempting to skip from invalid status
     #
@@ -352,6 +274,7 @@ module CMDx
     # @param halt [Boolean] Whether to halt execution after failure
     # @param cause [Exception, nil] Exception that caused the failure
     # @param metadata [Hash] Additional metadata about the failure
+    # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
     # @raise [RuntimeError] When attempting to fail from invalid status
     #
@@ -407,6 +330,7 @@ module CMDx
     # @param halt [Boolean] Whether to halt execution after throwing
     # @param cause [Exception, nil] Exception that caused the throw
     # @param metadata [Hash] Additional metadata to merge
+    # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
     # @raise [TypeError] When result is not a CMDx::Result instance
     #
@@ -557,8 +481,6 @@ module CMDx
       end
     end
 
-    # @param keys [Array] Array of keys to deconstruct
-    #
     # @return [Array] Array containing state, status, reason, cause, and metadata
     #
     # @example
@@ -570,8 +492,6 @@ module CMDx
       [state, status, reason, cause, metadata]
     end
 
-    # @param keys [Array] Array of keys to deconstruct
-    #
     # @return [Hash] Hash with key-value pairs for pattern matching
     #
     # @example

data/lib/cmdx/task.rb

@@ -100,6 +100,7 @@ module CMDx
     class << self
 
       # @param options [Hash] Configuration options to merge with existing settings
+      # @option options [Object] :* Any configuration option key-value pairs
       #
       # @return [Hash] The merged settings hash
       #
@@ -136,7 +137,6 @@ module CMDx
 
       # @param type [Symbol] The type of registry to register with
       # @param object [Object] The object to register
-      # @param args [Array] Additional arguments for registration
       #
       # @raise [RuntimeError] If the registry type is unknown
       #
@@ -158,7 +158,6 @@ module CMDx
 
       # @param type [Symbol] The type of registry to deregister from
       # @param object [Object] The object to deregister
-      # @param args [Array] Additional arguments for deregistration
       #
       # @raise [RuntimeError] If the registry type is unknown
       #
@@ -178,8 +177,6 @@ module CMDx
         end
       end
 
-      # @param args [Array] Arguments to build the attribute with
-      #
       # @example
       #   attributes :name, :email
       #   attributes :age, type: Integer, default: 18
@@ -190,8 +187,6 @@ module CMDx
       end
       alias attribute attributes
 
-      # @param args [Array] Arguments to build the optional attribute with
-      #
       # @example
       #   optional :description, :notes
       #   optional :priority, type: Symbol, default: :normal
@@ -201,8 +196,6 @@ module CMDx
         register(:attribute, Attribute.optional(...))
       end
 
-      # @param args [Array] Arguments to build the required attribute with
-      #
       # @example
       #   required :name, :email
       #   required :age, type: Integer, min: 0
@@ -242,6 +235,8 @@ module CMDx
       end
 
       # @param args [Array] Arguments to pass to the task constructor
+      # @param kwargs [Hash] Keyword arguments to pass to the task constructor
+      # @option kwargs [Object] :* Any key-value pairs to pass to the task constructor
       #
       # @return [Result] The execution result
       #
@@ -259,6 +254,8 @@ module CMDx
       end
 
       # @param args [Array] Arguments to pass to the task constructor
+      # @param kwargs [Hash] Keyword arguments to pass to the task constructor
+      # @option kwargs [Object] :* Any key-value pairs to pass to the task constructor
       #
       # @return [Result] The execution result
       #
@@ -322,8 +319,6 @@ module CMDx
       end
     end
 
-    # @return [Hash] A hash representation of the task
-    #
     # @option return [Integer] :index The result index
     # @option return [String] :chain_id The chain identifier
     # @option return [String] :type The task type ("Task" or "Workflow")
@@ -331,6 +326,8 @@ module CMDx
     # @option return [String] :class The task class name
     # @option return [String] :id The task identifier
     #
+    # @return [Hash] A hash representation of the task
+    #
     # @example
     #   task_hash = task.to_h
     #   puts "Task type: #{task_hash[:type]}"

data/lib/cmdx/utils/call.rb

@@ -17,7 +17,9 @@ module CMDx
       # @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
-      # @param &block [Proc, nil] Block 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
       #

data/lib/cmdx/utils/condition.rb

@@ -34,9 +34,6 @@ module CMDx
       # @param options [Hash] Conditional options hash
       # @option options [Object] :if Condition that must be true for evaluation to succeed
       # @option options [Object] :unless Condition that must be false for evaluation to succeed
-      # @param args [Array] Additional arguments passed to condition evaluation
-      # @param kwargs [Hash] Additional keyword arguments passed to condition evaluation
-      # @param block [Proc, nil] Optional block passed to condition evaluation
       #
       # @return [Boolean] true if conditions are met, false otherwise
       #

data/lib/cmdx/utils/format.rb

@@ -32,7 +32,7 @@ module CMDx
       #
       # @rbs (untyped message) -> untyped
       def to_log(message)
-        if message.respond_to?(:to_h) && message.class.ancestors.any? { |a| a.to_s.start_with?("CMDx") }
+        if message.respond_to?(:to_h) && message.class.ancestors.any? { |a| a.name&.start_with?("CMDx::") }
           message.to_h
         else
           message

data/lib/cmdx/validators/exclusion.rb

@@ -50,6 +50,7 @@ module CMDx
       #
       # @param values [Array] The forbidden values that caused the error
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       def raise_of_validation_error!(values, options)
@@ -65,6 +66,7 @@ module CMDx
       # @param min [Object] The minimum value of the forbidden range
       # @param max [Object] The maximum value of the forbidden range
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       def raise_within_validation_error!(min, max, options)

data/lib/cmdx/validators/inclusion.rb

@@ -52,6 +52,7 @@ module CMDx
       #
       # @param values [Array] The allowed values that caused the error
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       def raise_of_validation_error!(values, options)
@@ -67,6 +68,7 @@ module CMDx
       # @param min [Object] The minimum value of the allowed range
       # @param max [Object] The maximum value of the allowed range
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       def raise_within_validation_error!(min, max, options)

data/lib/cmdx/validators/length.rb

@@ -87,6 +87,7 @@ module CMDx
       # @param min [Integer] Minimum length value
       # @param max [Integer] Maximum length value
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #
@@ -103,6 +104,7 @@ module CMDx
       # @param min [Integer] Minimum length value
       # @param max [Integer] Maximum length value
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #
@@ -118,6 +120,7 @@ module CMDx
       #
       # @param min [Integer] Minimum required length
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #
@@ -133,6 +136,7 @@ module CMDx
       #
       # @param max [Integer] Maximum allowed length
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #
@@ -148,6 +152,7 @@ module CMDx
       #
       # @param is [Integer] Required exact length
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #
@@ -163,6 +168,7 @@ module CMDx
       #
       # @param is_not [Integer] Length that is not allowed
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] Always raised with appropriate message
       #

data/lib/cmdx/validators/numeric.rb

@@ -82,6 +82,7 @@ module CMDx
       # @param min [Numeric] The minimum value of the allowed range
       # @param max [Numeric] The maximum value of the allowed range
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #
@@ -98,6 +99,7 @@ module CMDx
       # @param min [Numeric] The minimum value of the excluded range
       # @param max [Numeric] The maximum value of the excluded range
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #
@@ -113,6 +115,7 @@ module CMDx
       #
       # @param min [Numeric] The minimum allowed value
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #
@@ -128,6 +131,7 @@ module CMDx
       #
       # @param max [Numeric] The maximum allowed value
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #
@@ -143,6 +147,7 @@ module CMDx
       #
       # @param is [Numeric] The exact value that was expected
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #
@@ -158,6 +163,7 @@ module CMDx
       #
       # @param is_not [Numeric] The value that was not allowed
       # @param options [Hash] Validation options containing custom messages
+      # @option options [Object] :* Any validation option key-value pairs
       #
       # @raise [ValidationError] With appropriate error message
       #

data/lib/cmdx/version.rb

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

data/lib/generators/cmdx/locale_generator.rb

@@ -22,13 +22,14 @@ module Cmdx
     #
     # @return [void]
     #
-    # @example
-    #   # Copy default (English) locale file
-    #   rails generate cmdx:locale
+    # @example Copy default (English) locale file
+    #   generator = Cmdx::LocaleGenerator.new(["en"])
+    #   generator.copy_locale_files
     #   # => Creates config/locales/en.yml
     #
-    #   # Copy Spanish locale file
-    #   rails generate cmdx:locale es
+    # @example Copy Spanish locale file
+    #   generator = Cmdx::LocaleGenerator.new(["es"])
+    #   generator.copy_locale_files
     #   # => Creates config/locales/es.yml
     def copy_locale_files
       copy_file("#{locale}.yml", "config/locales/#{locale}.yml")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -205,6 +205,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: CMDx is a framework for building maintainable business processes.
 email:
 - drexed@users.noreply.github.com
@@ -222,6 +236,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yard-lint.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -259,8 +274,12 @@ files:
 - docs/stylesheets/extra.css
 - docs/tips_and_tricks.md
 - docs/workflows.md
+- examples/active_record_database_transaction.md
 - examples/active_record_query_tagging.md
+- examples/flipper_feature_flags.md
 - examples/paper_trail_whatdunnit.md
+- examples/redis_idempotency.md
+- examples/sentry_error_tracking.md
 - examples/sidekiq_async_execution.md
 - examples/stoplight_circuit_breaker.md
 - lib/cmdx.rb