cmdx 1.11.0 → 1.13.0

data/lib/cmdx/result.rb

@@ -95,7 +95,7 @@ module CMDx
     # @rbs @cause: (Exception | nil)
     attr_reader :cause
 
-    def_delegators :task, :context, :chain, :errors
+    def_delegators :task, :context, :chain, :errors, :dry_run?
     alias ctx context
 
     # @param task [CMDx::Task] The task instance this result represents
@@ -118,6 +118,7 @@ module CMDx
       @metadata = {}
       @reason = nil
       @cause = nil
+      @rolled_back = false
     end
 
     STATES.each do |s|
@@ -129,26 +130,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 +152,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 +203,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 +216,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 +226,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 +248,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 +275,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 +331,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
     #
@@ -495,6 +420,27 @@ module CMDx
       failed? && !caused_failure?
     end
 
+    # @return [void]
+    #
+    # @example
+    #   result.rolled_back!
+    #   result.rolled_back? # => true
+    #
+    # @rbs () -> void
+    def rolled_back!
+      @rolled_back = true
+    end
+
+    # @return [Boolean] Whether the result has been rolled back
+    #
+    # @example
+    #   result.rolled_back? # => true
+    #
+    # @rbs () -> bool
+    def rolled_back?
+      !!@rolled_back
+    end
+
     # @return [Integer] Index of this result in the chain
     #
     # @example
@@ -533,6 +479,7 @@ module CMDx
         if interrupted?
           hash[:reason] = reason
           hash[:cause] = cause
+          hash[:rolled_back] = rolled_back?
         end
 
         if failed?
@@ -557,8 +504,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 +515,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

@@ -71,6 +71,7 @@ module CMDx
     attr_reader :chain
 
     def_delegators :result, :skip!, :fail!, :throw!
+    def_delegators :chain, :dry_run?
 
     # @param context [Hash, Context] The initial context for the task
     #
@@ -94,12 +95,13 @@ module CMDx
       @id = Identifier.generate
       @context = Context.build(context)
       @result = Result.new(self)
-      @chain = Chain.build(@result)
+      @chain = Chain.build(@result, dry_run: @context.delete(:dry_run))
     end
 
     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 +138,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 +159,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 +178,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 +188,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 +197,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 +236,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 +255,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 +320,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 +327,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]}"
@@ -344,6 +342,7 @@ module CMDx
         type: self.class.include?(Workflow) ? "Workflow" : "Task",
         tags: self.class.settings[:tags],
         class: self.class.name,
+        dry_run: dry_run?,
         id:
       }
     end

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.13.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")

data/mkdocs.yml

@@ -65,7 +65,11 @@ markdown_extensions:
   - attr_list
   - md_in_html
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.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