cmdx 1.8.0 → 1.9.0

data/docs/outcomes/states.md

@@ -1,16 +1,6 @@
 # Outcomes - States
 
-States represent the execution lifecycle condition of task execution, tracking
-the progress of tasks through their complete execution journey. States provide
-insight into where a task is in its lifecycle and enable lifecycle-based
-decision making and monitoring.
-
-## Table of Contents
-
-- [Definitions](#definitions)
-- [Transitions](#transitions)
-- [Predicates](#predicates)
-- [Handlers](#handlers)
+States track where a task is in its execution lifecycle—from creation through completion or interruption.
 
 ## Definitions
 
@@ -34,8 +24,9 @@ State-Status combinations:
 
 ## Transitions
 
-> [!CAUTION]
-> States are automatically managed during task execution and should **never** be modified manually. State transitions are handled internally by the CMDx framework.
+!!! danger "Caution"
+
+    States are managed automatically—never modify them manually.
 
 ```ruby
 # Valid state transition flow
@@ -62,19 +53,14 @@ result.executed?    #=> true (complete OR interrupted)
 
 ## Handlers
 
-Use state-based handlers for lifecycle event handling. The `on_executed` handler is particularly useful for cleanup operations that should run regardless of success, skipped, or failure.
+Handle lifecycle events with state-based handlers. Use `handle_executed` for cleanup that runs regardless of outcome:
 
 ```ruby
 result = ProcessVideoUpload.execute
 
 # Individual state handlers
 result
-  .on_complete { |result| send_upload_notification(result) }
-  .on_interrupted { |result| cleanup_temp_files(result) }
-  .on_executed { |result| log_upload_metrics(result) }
+  .handle_complete { |result| send_upload_notification(result) }
+  .handle_interrupted { |result| cleanup_temp_files(result) }
+  .handle_executed { |result| log_upload_metrics(result) }
 ```
-
----
-
-- **Prev:** [Outcomes - Result](result.md)
-- **Next:** [Outcomes - Statuses](statuses.md)

data/docs/outcomes/statuses.md

@@ -1,13 +1,6 @@
 # Outcomes - Statuses
 
-Statuses represent the business outcome of task execution logic, indicating how the task's business logic concluded. Statuses differ from execution states by focusing on the business outcome rather than the technical execution lifecycle. Understanding statuses is crucial for implementing proper business logic branching and error handling.
-
-## Table of Contents
-
-- [Definitions](#definitions)
-- [Transitions](#transitions)
-- [Predicates](#predicates)
-- [Handlers](#handlers)
+Statuses represent the business outcome—did the task succeed, skip, or fail? This differs from state, which tracks the execution lifecycle.
 
 ## Definitions
 
@@ -19,8 +12,9 @@ Statuses represent the business outcome of task execution logic, indicating how
 
 ## Transitions
 
-> [!IMPORTANT]
-> Status transitions are unidirectional and final. Once a task is marked as skipped or failed, it cannot return to success status. Design your business logic accordingly.
+!!! warning "Important"
+
+    Status transitions are final and unidirectional. Once skipped or failed, tasks can't return to success.
 
 ```ruby
 # Valid status transitions
@@ -53,24 +47,19 @@ result.bad?     #=> true if skipped OR failed (not success)
 
 ## Handlers
 
-Use status-based handlers for business logic branching. The `on_good` and `on_bad` handlers are particularly useful for handling success/skip vs failed outcomes respectively.
+Branch business logic with status-based handlers. Use `handle_good` and `handle_bad` for success/skip vs failed outcomes:
 
 ```ruby
 result = ProcessNotification.execute
 
 # Individual status handlers
 result
-  .on_success { |result| mark_notification_sent(result) }
-  .on_skipped { |result| log_notification_skipped(result) }
-  .on_failed { |result| queue_retry_notification(result) }
+  .handle_success { |result| mark_notification_sent(result) }
+  .handle_skipped { |result| log_notification_skipped(result) }
+  .handle_failed { |result| queue_retry_notification(result) }
 
 # Outcome-based handlers
 result
-  .on_good { |result| update_message_stats(result) }
-  .on_bad { |result| track_delivery_failure(result) }
+  .handle_good { |result| update_message_stats(result) }
+  .handle_bad { |result| track_delivery_failure(result) }
 ```
-
----
-
-- **Prev:** [Outcomes - States](states.md)
-- **Next:** [Attributes - Definitions](../attributes/definitions.md)

data/docs/stylesheets/extra.css

@@ -0,0 +1,42 @@
+:root  > * {
+  /* Primary color shades */
+  --md-primary-fg-color:        #fe1817;
+  --md-primary-fg-color--light: #fe1817;
+  --md-primary-fg-color--dark:  #fe1817;
+
+  /* Accent color shades */
+  --md-accent-fg-color:                hsla(#{hex2hsl(#fe1817)}, 1);
+  --md-accent-fg-color--transparent:   hsla(#{hex2hsl(#fe1817)}, 0.1);
+}
+
+/* Atom One Light Pro syntax highlighting */
+[data-md-color-scheme="default"] {
+  --md-code-hl-color:            #2c3036;
+  --md-code-hl-keyword-color:    #a626a4;
+  --md-code-hl-string-color:     #50a14f;
+  --md-code-hl-name-color:       #e4564a;
+  --md-code-hl-function-color:   #4078f2;
+  --md-code-hl-number-color:     #ca7601;
+  --md-code-hl-constant-color:   #c18401;
+  --md-code-hl-comment-color:    #9ca0a4;
+  --md-code-hl-operator-color:   #0184bc;
+  --md-code-hl-punctuation-color:#383a42;
+  --md-code-hl-variable-color:   #e4564a;
+  --md-code-hl-generic-color:    #e4564a;
+}
+
+/* Atom One Dark Pro syntax highlighting */
+[data-md-color-scheme="slate"] {
+  --md-code-hl-color:            #e5e5e6;
+  --md-code-hl-keyword-color:    #c678dd;
+  --md-code-hl-string-color:     #98c379;
+  --md-code-hl-name-color:       #e06c75;
+  --md-code-hl-function-color:   #61afef;
+  --md-code-hl-number-color:     #d19a66;
+  --md-code-hl-constant-color:   #d19a66;
+  --md-code-hl-comment-color:    #7f848e;
+  --md-code-hl-operator-color:   #56b6c2;
+  --md-code-hl-punctuation-color:#abb2bf;
+  --md-code-hl-variable-color:   #e06c75;
+  --md-code-hl-generic-color:    #e06c75;
+}

data/docs/tips_and_tricks.md

@@ -1,16 +1,6 @@
 # Tips and Tricks
 
-This guide covers advanced patterns and optimization techniques for getting the most out of CMDx in production applications.
-
-## Table of Contents
-
-- [Project Organization](#project-organization)
-  - [Directory Structure](#directory-structure)
-  - [Naming Conventions](#naming-conventions)
-  - [Story Telling](#story-telling)
-  - [Style Guide](#style-guide)
-- [Attribute Options](#attribute-options)
-- [ActiveRecord Query Tagging](#activerecord-query-tagging)
+Best practices, patterns, and techniques to build maintainable CMDx applications.
 
 ## Project Organization
 
@@ -54,7 +44,7 @@ class TokenGeneration < CMDx::Task; end    # ❌ Avoid
 
 ### Story Telling
 
-Consider using descriptive methods to express the task’s flow, rather than concentrating all logic inside the `work` method.
+Break down complex logic into descriptive methods that read like a narrative:
 
 ```ruby
 class ProcessOrder < CMDx::Task
@@ -86,7 +76,7 @@ end
 
 ### Style Guide
 
-Follow a style pattern for consistent task design:
+Follow this order for consistent, readable tasks:
 
 ```ruby
 class ExportReport < CMDx::Task
@@ -129,7 +119,7 @@ end
 
 ## Attribute Options
 
-Use Rails `with_options` to reduce duplication and improve readability:
+Use `with_options` to reduce duplication:
 
 ```ruby
 class ConfigureCompany < CMDx::Task
@@ -155,36 +145,7 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## ActiveRecord Query Tagging
-
-Automatically tag SQL queries for better debugging:
-
-```ruby
-# config/application.rb
-config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags << :cmdx_task_class
-config.active_record.query_log_tags << :cmdx_chain_id
-
-# app/tasks/application_task.rb
-class ApplicationTask < CMDx::Task
-  before_execution :set_execution_context
-
-  private
-
-  def set_execution_context
-    # NOTE: This could easily be made into a middleware
-    ActiveSupport::ExecutionContext.set(
-      cmdx_task_class: self.class.name,
-      cmdx_chain_id: chain.id
-    )
-  end
-end
-
-# SQL queries will now include comments like:
-# /*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
-```
-
----
+## Advanced Examples
 
-- **Prev:** [Workflows](workflows.md)
-- **Next:** [Getting Started](getting_started.md)
+- [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
+- [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)

data/docs/workflows.md

@@ -1,26 +1,14 @@
 # Workflows
 
-Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business logic from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
-
-## Table of Contents
-
-- [Declarations](#declarations)
-  - [Task](#task)
-  - [Group](#group)
-  - [Conditionals](#conditionals)
-- [Halt Behavior](#halt-behavior)
-  - [Task Configuration](#task-configuration)
-  - [Group Configuration](#group-configuration)
-- [Nested Workflows](#nested-workflows)
-- [Parallel Execution](#parallel-execution)
-- [Task Generator](#task-generator)
+Compose multiple tasks into powerful, sequential pipelines. Workflows provide a declarative way to build complex business processes with conditional execution, shared context, and flexible error handling.
 
 ## Declarations
 
-Tasks execute sequentially in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
+Tasks run in declaration order (FIFO), sharing a common context across the pipeline.
 
-> [!IMPORTANT]
-> Do **NOT** define a `work` method in workflow tasks. The included module automatically provides the execution logic.
+!!! warning
+
+    Don't define a `work` method in workflows—the module handles execution automatically.
 
 ### Task
 
@@ -35,15 +23,17 @@ class OnboardingWorkflow < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
+!!! tip
+
+    Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
 
 ### Group
 
-Group related tasks for better organization and shared configuration:
+Group related tasks to share configuration:
 
-> [!IMPORTANT]
-> Settings and conditionals for a group apply to all tasks within that group.
+!!! warning "Important"
+
+    Settings and conditionals apply to all tasks in the group.
 
 ```ruby
 class ContentModerationWorkflow < CMDx::Task
@@ -78,10 +68,10 @@ class OnboardingWorkflow < CMDx::Task
   task SendWelcomeEmail, if: :email_configured?, unless: :email_disabled?
 
   # Proc
-  task SendWelcomeEmail, if: ->(workflow) { Rails.env.production? && workflow.class.name.include?("Premium") }
+  task SendWelcomeEmail, if: -> { Rails.env.production? && self.class.name.include?("Premium") }
 
   # Lambda
-  task SendWelcomeEmail, if: proc { |workflow| workflow.context.features_enabled? }
+  task SendWelcomeEmail, if: proc { context.features_enabled? }
 
   # Class or Module
   task SendWelcomeEmail, unless: ContentAccessCheck
@@ -95,7 +85,7 @@ class OnboardingWorkflow < CMDx::Task
   private
 
   def email_configured?
-    context.user.email_address.present?
+    context.user.email_address == true
   end
 
   def email_disabled?
@@ -106,9 +96,7 @@ end
 
 ## Halt Behavior
 
-By default skipped tasks are considered no-op executions and does not stop workflow execution.
-This is configurable via global and task level breakpoint settings. Task and group configurations
-can be used together within a workflow.
+By default, skipped tasks don't stop the workflow—they're treated as no-ops. Configure breakpoints globally or per-task to customize this behavior.
 
 ```ruby
 class AnalyticsWorkflow < CMDx::Task
@@ -164,7 +152,7 @@ end
 
 ## Nested Workflows
 
-Workflows can task other workflows for hierarchical composition:
+Build hierarchical workflows by composing workflows within workflows:
 
 ```ruby
 class EmailPreparationWorkflow < CMDx::Task
@@ -191,10 +179,11 @@ end
 
 ## Parallel Execution
 
-Parallel task execution leverages the [Parallel](https://github.com/grosser/parallel) gem, which automatically detects the number of available processors to maximize concurrent task execution.
+Run tasks concurrently using the [Parallel](https://github.com/grosser/parallel) gem. It automatically uses all available processors for maximum throughput.
+
+!!! warning
 
-> [!IMPORTANT]
-> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+    Context is read-only during parallel execution. Load all required data beforehand.
 
 ```ruby
 class SendWelcomeNotifications < CMDx::Task
@@ -232,10 +221,6 @@ class SendNotifications < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
-
----
+!!! tip
 
-- **Prev:** [Deprecation](deprecation.md)
-- **Next:** [Tips and Tricks](tips_and_tricks.md)
+    Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`

data/examples/active_record_query_tagging.md

@@ -0,0 +1,46 @@
+# Active Record Query Tagging
+
+Add a comment to every query indicating some context to help you track down where that query came from, eg:
+
+```sh
+/*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
+```
+
+### Setup
+
+```ruby
+# config/application.rb
+config.active_record.query_log_tags_enabled = true
+config.active_record.query_log_tags += [
+  :cmdx_correlation_id,
+  :cmdx_chain_id,
+  :cmdx_task_class,
+  :cmdx_task_id
+]
+
+# lib/cmdx_query_tagging_middleware.rb
+class CmdxQueryTaggingMiddleware
+  def self.call(task, **options, &)
+    ActiveSupport::ExecutionContext.set(
+      cmdx_correlation_id: task.result.metadata[:correlation_id],
+      cmdx_chain_id: task.chain.id,
+      cmdx_task_class: task.class.name,
+      cmdx_task_id: task.id,
+      &
+    )
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxQueryTaggingMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/examples/paper_trail_whatdunnit.md

@@ -0,0 +1,39 @@
+# Paper Trail Whatdunnit
+
+Tag paper trail version records with which service made a change with a custom `whatdunnit` attribute.
+
+<https://github.com/paper-trail-gem/paper_trail?tab=readme-ov-file#4c-storing-metadata>
+
+### Setup
+
+```ruby
+# lib/cmdx_paper_trail_middleware.rb
+class CmdxPaperTrailMiddleware
+  def self.call(task, **options, &)
+    # This makes sure to reset the whatdunnit value to the previous
+    # value for nested task calls
+
+    begin
+      PaperTrail.request.controller_info ||= {}
+      old_whatdunnit = PaperTrail.request.controller_info[:whatdunnit]
+      PaperTrail.request.controller_info[:whatdunnit] = task.class.name
+      yield
+    ensure
+      PaperTrail.request.controller_info[:whatdunnit] = old_whatdunnit
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxPaperTrailMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/lib/cmdx/attribute.rb

@@ -66,7 +66,7 @@ module CMDx
         if names.none?
           raise ArgumentError, "no attributes given"
         elsif (names.size > 1) && options.key?(:as)
-          raise ArgumentError, ":as option only supports one attribute per definition"
+          raise ArgumentError, "the :as option only supports one attribute per definition"
         end
 
         names.filter_map { |name| new(name, **options, &) }
@@ -213,10 +213,11 @@ module CMDx
     # @raise [RuntimeError] When the method name is already defined on the task
     def define_and_verify
       if task.respond_to?(method_name, true)
-        raise <<~MESSAGE.gsub!(/[[:space:]]+/, " ").strip!
-          #{task.class.name}##{method_name} already defined.
-          Use :as, :prefix, or :suffix option to avoid
-          conflicts with existing methods
+        raise <<~MESSAGE
+          The method #{method_name.inspect} is already defined on the #{task.class.name} task.
+          This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+          Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
         MESSAGE
       end
 

data/lib/cmdx/attribute_value.rb

@@ -51,9 +51,10 @@ module CMDx
       return if errors.for?(method_name)
 
       coerced_value = coerce_value(derived_value)
+      transformed_value = transform_value(coerced_value)
       return if errors.for?(method_name)
 
-      attributes[method_name] = coerced_value
+      attributes[method_name] = transformed_value
     end
 
     # Validates the current attribute value against configured validators.
@@ -113,7 +114,7 @@ module CMDx
     #
     # @example
     #   # Default can be symbol, proc, or direct value
-    #   default_value # => "default_value"
+    #   -> { rand(100) } # => 23
     def default_value
       default = options[:default]
 
@@ -138,7 +139,7 @@ module CMDx
     #
     # @example
     #   # Derives from hash key, method call, or proc execution
-    #   derive_value({user_id: 42}) # => 42
+    #   context.user_id # => 42
     def derive_value(source_value)
       derived_value =
         case source_value
@@ -154,9 +155,29 @@ module CMDx
       nil
     end
 
+    # Transforms the derived value using the transform option.
+    #
+    # @param derived_value [Object] The value to transform
+    #
+    # @return [Object, nil] The transformed value or nil if transformation failed
+    #
+    # @example
+    #   :downcase # => "hello"
+    def transform_value(derived_value)
+      transform = options[:transform]
+
+      if transform.is_a?(Symbol) && derived_value.respond_to?(transform, true)
+        derived_value.send(transform)
+      elsif transform.respond_to?(:call)
+        transform.call(derived_value)
+      else
+        derived_value
+      end
+    end
+
     # Coerces the derived value to the expected type(s) using the coercion registry.
     #
-    # @param derived_value [Object] The value to coerce
+    # @param transformed_value [Object] The value to coerce
     #
     # @return [Object, nil] The coerced value or nil if coercion failed
     #
@@ -165,14 +186,14 @@ module CMDx
     # @example
     #   # Coerces "42" to Integer, "true" to Boolean, etc.
     #   coerce_value("42") # => 42
-    def coerce_value(derived_value)
-      return derived_value if attribute.types.empty?
+    def coerce_value(transformed_value)
+      return transformed_value if types.empty?
 
       registry = task.class.settings[:coercions]
-      last_idx = attribute.types.size - 1
+      last_idx = types.size - 1
 
-      attribute.types.find.with_index do |type, i|
-        break registry.coerce(type, task, derived_value, options)
+      types.find.with_index do |type, i|
+        break registry.coerce(type, task, transformed_value, options)
       rescue CoercionError => e
         next if i != last_idx
 
@@ -180,7 +201,7 @@ module CMDx
           if last_idx.zero?
             e.message
           else
-            tl = attribute.types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
+            tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
             Locale.t("cmdx.coercions.into_any", types: tl)
           end
 

data/lib/cmdx/callback_registry.rb

@@ -95,9 +95,19 @@ module CMDx
       raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
 
       Array(registry[type]).each do |callables, options|
-        next unless Utils::Condition.evaluate(task, options, task)
+        next unless Utils::Condition.evaluate(task, options)
 
-        Array(callables).each { |callable| Utils::Call.invoke(task, callable, task) }
+        Array(callables).each do |callable|
+          if callable.is_a?(Symbol)
+            task.send(callable)
+          elsif callable.is_a?(Proc)
+            task.instance_exec(&callable)
+          elsif callable.respond_to?(:call)
+            callable.call(task)
+          else
+            raise "cannot invoke #{callable}"
+          end
+        end
       end
     end
 

data/lib/cmdx/coercions/hash.rb

@@ -39,6 +39,8 @@ module CMDx
           ::Hash[*value]
         elsif value.is_a?(::String) && value.start_with?("{")
           JSON.parse(value)
+        elsif value.respond_to?(:to_h)
+          value.to_h
         else
           raise_coercion_error!
         end

data/lib/cmdx/configuration.rb

@@ -3,13 +3,14 @@
 module CMDx
 
   # Configuration class that manages global settings for CMDx including middlewares,
-  # callbacks, coercions, validators, breakpoints, and logging.
+  # callbacks, coercions, validators, breakpoints, backtraces, and logging.
   class Configuration
 
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
     attr_accessor :middlewares, :callbacks, :coercions, :validators,
-                  :task_breakpoints, :workflow_breakpoints, :logger
+                  :task_breakpoints, :workflow_breakpoints, :logger,
+                  :backtrace, :backtrace_cleaner, :exception_handler
 
     # Initializes a new Configuration instance with default values.
     #
@@ -31,6 +32,10 @@ module CMDx
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
 
+      @backtrace = false
+      @backtrace_cleaner = nil
+      @exception_handler = nil
+
       @logger = Logger.new(
         $stdout,
         progname: "cmdx",
@@ -55,6 +60,9 @@ module CMDx
         validators: @validators,
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
+        backtrace: @backtrace,
+        backtrace_cleaner: @backtrace_cleaner,
+        exception_handler: @exception_handler,
         logger: @logger
       }
     end

data/lib/cmdx/deprecator.rb

@@ -44,15 +44,15 @@ module CMDx
     #     settings(deprecate: :warn)
     #   end
     #
-    #   MyTask.new # => [MyTask] DEPRECATED: migrate to replacement or discontinue use
+    #   MyTask.new # => [MyTask] DEPRECATED: migrate to a replacement or discontinue use
     def restrict(task)
       type = EVAL.call(task, task.class.settings[:deprecate])
 
       case type
       when NilClass, FalseClass # Do nothing
       when TrueClass, /raise/ then raise DeprecationError, "#{task.class.name} usage prohibited"
-      when /log/ then task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
-      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
+      when /log/ then task.logger.warn { "DEPRECATED: migrate to a replacement or discontinue use" }
+      when /warn/ then warn("[#{task.class.name}] DEPRECATED: migrate to a replacement or discontinue use", category: :deprecated)
       else raise "unknown deprecation type #{type.inspect}"
       end
     end