cmdx 1.8.0 → 1.9.0

data/lib/cmdx/executor.rb

@@ -46,14 +46,16 @@ module CMDx
     #   result = executor.execute
     def execute
       task.class.settings[:middlewares].call!(task) do
-        pre_execution!
+        pre_execution! unless @pre_execution
         execution!
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
         task.result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
+        retry if retry_execution?(e)
         task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        task.class.settings[:exception_handler]&.call(task, e)
       ensure
         task.result.executed!
         post_execution!
@@ -73,7 +75,7 @@ module CMDx
     #   result = executor.execute!
     def execute!
       task.class.settings[:middlewares].call!(task) do
-        pre_execution!
+        pre_execution! unless @pre_execution
         execution!
       rescue UndefinedMethodError => e
         raise_exception(e)
@@ -81,6 +83,7 @@ module CMDx
         task.result.throw!(e.result, halt: false, cause: e)
         halt_execution?(e) ? raise_exception(e) : post_execution!
       rescue StandardError => e
+        retry if retry_execution?(e)
         task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         raise_exception(e)
       else
@@ -108,6 +111,38 @@ module CMDx
       breakpoints.include?(exception.result.status)
     end
 
+    # Determines if execution should be retried based on retry configuration.
+    #
+    # @param exception [Exception] The exception that occurred
+    #
+    # @return [Boolean] Whether execution should be retried
+    #
+    # @example
+    #   retry_execution?(standard_error)
+    def retry_execution?(exception)
+      available_retries = (task.class.settings[:retries] || 0).to_i
+      return false unless available_retries.positive?
+
+      current_retries = (task.result.metadata[:retries] ||= 0).to_i
+      remaining_retries = available_retries - current_retries
+      return false unless remaining_retries.positive?
+
+      exceptions = Array(task.class.settings[:retry_on] || StandardError)
+      return false unless exceptions.any? { |e| exception.class <= e }
+
+      task.result.metadata[:retries] += 1
+
+      task.logger.warn do
+        reason = "[#{exception.class}] #{exception.message}"
+        task.to_h.merge!(reason:, remaining_retries:)
+      end
+
+      jitter = task.class.settings[:retry_jitter].to_f * current_retries
+      sleep(jitter) if jitter.positive?
+
+      true
+    end
+
     # Raises an exception and clears the chain.
     #
     # @param exception [Exception] The exception to raise
@@ -118,6 +153,7 @@ module CMDx
     #   raise_exception(standard_error)
     def raise_exception(exception)
       Chain.clear
+
       raise(exception)
     end
 
@@ -135,8 +171,15 @@ module CMDx
 
     private
 
+    # Lazy loaded repeator instance to handle retries.
+    def repeator
+      @repeator ||= Repeator.new(task)
+    end
+
     # Performs pre-execution tasks including validation and attribute verification.
     def pre_execution!
+      @pre_execution = true
+
       invoke_callbacks(:before_validation)
 
       task.class.settings[:attributes].define_and_verify(task)
@@ -171,13 +214,56 @@ module CMDx
 
     # Finalizes execution by freezing the task and logging results.
     def finalize_execution!
-      task.logger.tap do |logger|
-        logger.with_level(:info) do
-          logger.info { task.result.to_h }
-        end
+      log_execution!
+      log_backtrace! if task.class.settings[:backtrace]
+
+      freeze_execution!
+      clear_chain!
+    end
+
+    # Logs the execution result at the configured log level.
+    def log_execution!
+      task.logger.info { task.result.to_h }
+    end
+
+    # Logs the backtrace of the exception if the task failed.
+    def log_backtrace!
+      return unless task.result.failed?
+
+      exception = task.result.caused_failure.cause
+      return if exception.is_a?(Fault)
+
+      task.logger.error do
+        "[#{exception.class}] #{exception.message}\n" <<
+          if (cleaner = task.class.settings[:backtrace_cleaner])
+            cleaner.call(exception.backtrace).join("\n\t")
+          else
+            exception.full_message(highlight: false)
+          end
       end
+    end
+
+    # Freezes the task and its associated objects to prevent modifications.
+    def freeze_execution!
+      # Stubbing on frozen objects is not allowed in most test environments.
+      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
+      return if Coercions::Boolean.call(skip_freezing)
+
+      task.freeze
+      task.result.freeze
+
+      # Freezing the context and chain can only be done
+      # once the outer-most task has completed.
+      return unless task.result.index.zero?
 
-      Freezer.immute(task)
+      task.context.freeze
+      task.chain.freeze
+    end
+
+    def clear_chain!
+      return unless task.result.index.zero?
+
+      Chain.clear
     end
 
   end

data/lib/cmdx/pipeline.rb

@@ -42,7 +42,7 @@ module CMDx
     #   pipeline.execute
     def execute
       workflow.class.pipeline.each do |group|
-        next unless Utils::Condition.evaluate(workflow, group.options, workflow)
+        next unless Utils::Condition.evaluate(workflow, group.options)
 
         breakpoints = group.options[:breakpoints] ||
                       workflow.class.settings[:breakpoints] ||
@@ -108,18 +108,18 @@ module CMDx
     # @example
     #   execute_tasks_in_parallel(group, ["failed"])
     def execute_tasks_in_parallel(group, breakpoints)
-      raise "install the `parallel` gem to use this feature" unless defined?(::Parallel)
+      raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
 
       parallel_options = group.options.slice(:in_threads, :in_processes)
       throwable_result = nil
 
-      ::Parallel.each(group.tasks, **parallel_options) do |task|
+      Parallel.each(group.tasks, **parallel_options) do |task|
         Chain.current = workflow.chain
 
         task_result = task.execute(workflow.context)
         next unless breakpoints.include?(task_result.status)
 
-        raise ::Parallel::Break, throwable_result = task_result
+        raise Parallel::Break, throwable_result = task_result
       end
 
       return if throwable_result.nil?

data/lib/cmdx/railtie.rb

@@ -32,5 +32,14 @@ module CMDx
       ::I18n.reload!
     end
 
+    # Configures the backtrace cleaner for CMDx in a Rails environment.
+    #
+    # Sets the backtrace cleaner to the Rails backtrace cleaner.
+    initializer("cmdx.backtrace_cleaner") do
+      CMDx.configuration.backtrace_cleaner = lambda do |backtrace|
+        Rails.backtrace_cleaner.clean(backtrace)
+      end
+    end
+
   end
 end

data/lib/cmdx/result.rb

@@ -291,7 +291,16 @@ module CMDx
 
       # Strip the first two frames (this method and the delegator)
       frames = caller_locations(3..-1)
-      fault.set_backtrace(frames.map(&:to_s)) unless frames.empty?
+
+      unless frames.empty?
+        frames = frames.map(&:to_s)
+
+        if (cleaner = task.class.settings[:backtrace_cleaner])
+          cleaner.call(frames)
+        end
+
+        fault.set_backtrace(frames)
+      end
 
       raise(fault)
     end

data/lib/cmdx/task.rb

@@ -40,9 +40,6 @@ module CMDx
     class << self
 
       # @param options [Hash] Configuration options to merge with existing settings
-      # @option options [AttributeRegistry] :attributes Registry for task attributes
-      # @option options [Boolean] :deprecate Whether the task is deprecated
-      # @option options [Array<Symbol>] :tags Tags associated with the task
       #
       # @return [Hash] The merged settings hash
       #
@@ -54,13 +51,21 @@ module CMDx
         @settings ||= begin
           hash =
             if superclass.respond_to?(:settings)
-              superclass.settings
+              parent = superclass.settings
+              parent
+                .except(:backtrace_cleaner, :exception_handler, :logger, :deprecate)
+                .transform_values!(&:dup)
+                .merge!(
+                  backtrace_cleaner: parent[:backtrace_cleaner] || CMDx.configuration.backtrace_cleaner,
+                  exception_handler: parent[:exception_handler] || CMDx.configuration.exception_handler,
+                  logger: parent[:logger] || CMDx.configuration.logger,
+                  deprecate: parent[:deprecate]
+                )
             else
-              CMDx.configuration.to_h.except(:logger)
-            end.transform_values(&:dup)
+              CMDx.configuration.to_h
+            end
 
           hash[:attributes] ||= AttributeRegistry.new
-          hash[:deprecate] ||= false
           hash[:tags] ||= []
 
           hash.merge!(options)

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 
 end

data/lib/cmdx.rb

@@ -5,6 +5,7 @@ require "date"
 require "forwardable"
 require "json"
 require "logger"
+require "pathname"
 require "securerandom"
 require "set"
 require "time"

data/lib/generators/cmdx/templates/install.rb

@@ -32,6 +32,15 @@ CMDx.configure do |config|
     level: Logger::INFO
   )
 
+  # Backtrace configuration - controls whether to log backtraces on faults and exceptions
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
+  # config.backtrace = false
+  # config.backtrace_cleaner = nil
+
+  # Exception handler configuration - called when non-fault exceptions are raised
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#exception-handler
+  # config.exception_handler = nil
+
   # Additional global configurations - automatically applied to all tasks
   #
   # Middlewares - https://github.com/drexed/cmdx/blob/main/docs/middlewares.md

data/mkdocs.yml

@@ -0,0 +1,122 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: CMDx
+site_url: https://drexed.github.io/cmdx/
+site_description: Build business logic that's powerful, predictable, and chaos-free.
+site_author: drexed
+repo_name: drexed/cmdx
+repo_url: https://github.com/drexed/cmdx
+edit_uri: edit/main/docs/
+copyright: Drexed, Inc. © 2025 - EoT
+
+theme:
+  name: material
+  logo: assets/favicon.svg
+  favicon: assets/favicon.ico
+  icon:
+    repo: fontawesome/brands/github
+  font:
+    text: Inter
+    code: IBM Plex Mono
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  features:
+    - navigation.footer
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - search.share
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - Basics:
+    - Setup: basics/setup.md
+    - Execution: basics/execution.md
+    - Context: basics/context.md
+    - Chain: basics/chain.md
+  - Interruptions:
+    - Halt: interruptions/halt.md
+    - Faults: interruptions/faults.md
+    - Exceptions: interruptions/exceptions.md
+  - Outcomes:
+    - Result: outcomes/result.md
+    - States: outcomes/states.md
+    - Statuses: outcomes/statuses.md
+  - Attributes:
+    - Definitions: attributes/definitions.md
+    - Naming: attributes/naming.md
+    - Coercions: attributes/coercions.md
+    - Validations: attributes/validations.md
+    - Defaults: attributes/defaults.md
+    - Transformations: attributes/transformations.md
+  - Callbacks: callbacks.md
+  - Middlewares: middlewares.md
+  - Logging: logging.md
+  - Internationalization: internationalization.md
+  - Deprecation: deprecation.md
+  - Workflows: workflows.md
+  - Tips and Tricks: tips_and_tricks.md
+
+extra:
+  generator: false
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/drexed/cmdx
+
+extra_css:
+  - stylesheets/extra.css

data/src/cmdx-favicon.svg

@@ -0,0 +1 @@
+<svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"/></svg>

data/src/cmdx-logo.svg

@@ -0,0 +1 @@
+<svg width="352.2" height="112.266" viewBox="0 0 203 64.708" xmlns="http://www.w3.org/2000/svg" xmlSpace="preserve"><path d="M172.908 17.723 169.4 23.17 156.385 3.323h3.507l9.508 14.77 1.938-3.139L161.738 0h-11.446L169.4 29.262 188.046 0h-3.97L173 17.54zm-20.677 43.57h-3.139l18.646-29.447L147.431.093h-3.97l20.308 31.846L143 64.708l10.985-.092 39.138-61.2h3.323L174.57 37.754l13.662 21.415h3.969l-13.754-21.415L202.538.093H191.37zm29.63-23.262 15.047 23.262h-10.523l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H203l-18.83-29.262-.278-.461z" fill="#fe1817"/><path d="M41.667 14v12.8h-23.42c-3.214.272-5.665 3.05-5.665 6.318s2.45 5.937 5.664 6.318H33.17v4.248H18.246a10.65 10.65 0 0 1-9.858-10.62c0-5.447 4.194-10.077 9.64-10.512h19.39v-4.303H18.246v.054A14.823 14.823 0 0 0 4.248 33.118c0 7.898 6.21 14.38 13.998 14.815h19.172v-8.497h4.249v12.745h-23.42A19.063 19.063 0 0 1 0 33.118a19.033 19.033 0 0 1 18.246-19.063zM75 35.623 87.2 14h13.508v38.181H87.963v-14.27l-8.116 14.27h-9.749L57.734 30.504v-8.007l14.87 25.436h4.792l14.815-25.436v25.436h4.249V18.249H89.65l-14.76 25.49-14.542-25.49H53.54v29.684h4.194v-8.007l4.249 7.299v4.956H49.292v-38.18H62.8zM108.333 14h23.42C141.94 14.436 150 22.824 150 33.064c0 10.294-8.061 18.681-18.246 19.117h-23.42V22.497h23.42a10.65 10.65 0 0 1 9.858 10.621c0 5.447-4.194 10.13-9.64 10.566H116.83V30.286h4.248v9.15l10.676-.054c3.213-.273 5.664-3.05 5.664-6.264 0-2.778-1.743-5.065-4.194-5.991-.926-.382-1.47-.382-2.94-.382h-17.702v21.188h19.172a14.84 14.84 0 0 0 13.998-14.87c0-7.897-6.21-14.379-13.998-14.814h-23.42z"/></svg>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -214,10 +214,14 @@ files:
 - LLM.md
 - README.md
 - Rakefile
+- docs/.DS_Store
+- docs/assets/favicon.ico
+- docs/assets/favicon.svg
 - docs/attributes/coercions.md
 - docs/attributes/defaults.md
 - docs/attributes/definitions.md
 - docs/attributes/naming.md
+- docs/attributes/transformations.md
 - docs/attributes/validations.md
 - docs/basics/chain.md
 - docs/basics/context.md
@@ -226,6 +230,7 @@ files:
 - docs/callbacks.md
 - docs/deprecation.md
 - docs/getting_started.md
+- docs/index.md
 - docs/internationalization.md
 - docs/interruptions/exceptions.md
 - docs/interruptions/faults.md
@@ -235,8 +240,11 @@ files:
 - docs/outcomes/result.md
 - docs/outcomes/states.md
 - docs/outcomes/statuses.md
+- docs/stylesheets/extra.css
 - docs/tips_and_tricks.md
 - docs/workflows.md
+- examples/active_record_query_tagging.md
+- examples/paper_trail_whatdunnit.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
 - lib/cmdx/attribute.rb
@@ -265,7 +273,6 @@ files:
 - lib/cmdx/exceptions.rb
 - lib/cmdx/executor.rb
 - lib/cmdx/faults.rb
-- lib/cmdx/freezer.rb
 - lib/cmdx/identifier.rb
 - lib/cmdx/locale.rb
 - lib/cmdx/log_formatters/json.rb
@@ -386,7 +393,11 @@ files:
 - lib/locales/zh-HK.yml
 - lib/locales/zh-TW.yml
 - lib/locales/zh-YUE.yml
-- src/cmdx-logo.png
+- mkdocs.yml
+- src/cmdx-dark-logo.png
+- src/cmdx-favicon.svg
+- src/cmdx-light-logo.png
+- src/cmdx-logo.svg
 homepage: https://github.com/drexed/cmdx
 licenses:
 - MIT

data/lib/cmdx/freezer.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Provides freezing functionality for CMDx tasks and their associated objects.
-  #
-  # The Freezer module is responsible for making task objects immutable after execution
-  # to prevent accidental modifications and ensure data integrity. It can be disabled
-  # via environment variable for testing or debugging purposes.
-  module Freezer
-
-    extend self
-
-    # Freezes a task and its associated objects to prevent modifications.
-    #
-    # This method makes the task, result, context, and chain immutable after execution.
-    # Freezing can be skipped by setting the SKIP_CMDX_FREEZING environment variable.
-    #
-    # @param task [Task] The task instance to freeze
-    # @option ENV["SKIP_CMDX_FREEZING"] [String, Boolean] Set to "true" or true to skip freezing
-    #
-    # @raise [RuntimeError] If attempting to stub on frozen objects
-    #
-    # @example Freeze a completed task
-    #   task = MyTask.new
-    #   task.execute
-    #   CMDx::Freezer.immute(task)
-    #   # task, result, context, and chain are now frozen
-    # @example Skip freezing for testing
-    #   ENV["SKIP_CMDX_FREEZING"] = "true"
-    #   CMDx::Freezer.immute(task)
-    #   # No freezing occurs
-    def immute(task)
-      # Stubbing on frozen objects is not allowed
-      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
-      return if Coercions::Boolean.call(skip_freezing)
-
-      task.freeze
-      task.result.freeze
-
-      # Freezing the context and chain can only be done
-      # once the outer-most task has completed.
-      return unless task.result.index.zero?
-
-      task.context.freeze
-      task.chain.freeze
-
-      Chain.clear
-    end
-
-  end
-end