cmdx 1.8.0 → 1.9.1

data/docs/index.md

@@ -0,0 +1,132 @@
+# CMDx
+
+Build business logic that's powerful, predictable, and maintainable.
+
+[![Version](https://img.shields.io/gem/v/cmdx)](https://rubygems.org/gems/cmdx)
+[![Build](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/drexed/cmdx)](https://github.com/drexed/cmdx/blob/main/LICENSE.txt)
+
+---
+
+Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
+
+!!! note
+
+    Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
+
+## Requirements
+
+- Ruby: MRI 3.1+ or JRuby 9.4+.
+
+CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
+
+## Installation
+
+```sh
+gem install cmdx
+# - or -
+bundle add cmdx
+```
+
+## Quick Example
+
+Build powerful business logic in four simple steps:
+
+### 1. Compose
+
+=== "Full Featured Task"
+
+    ```ruby
+    class AnalyzeMetrics < CMDx::Task
+      register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
+
+      on_success :track_analysis_completion!
+
+      required :dataset_id, type: :integer, numeric: { min: 1 }
+      optional :analysis_type, default: "standard"
+
+      def work
+        if dataset.nil?
+          fail!("Dataset not found", code: 404)
+        elsif dataset.unprocessed?
+          skip!("Dataset not ready for analysis")
+        else
+          context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
+          context.analyzed_at = Time.now
+
+          SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
+        end
+      end
+
+      private
+
+      def dataset
+        @dataset ||= Dataset.find_by(id: dataset_id)
+      end
+
+      def track_analysis_completion!
+        dataset.update!(analysis_result_id: context.result.id)
+      end
+    end
+    ```
+
+=== "Minimum Viable Task"
+
+    ```ruby
+    class SendAnalyzedEmail < CMDx::Task
+      def work
+        user = User.find(context.user_id)
+        MetricsMailer.analyzed(user).deliver_now
+      end
+    end
+    ```
+
+### 2. Execute
+
+```ruby
+result = AnalyzeMetrics.execute(
+  dataset_id: 123,
+  "analysis_type" => "advanced"
+)
+```
+
+### 3. React
+
+```ruby
+if result.success?
+  puts "Metrics analyzed at #{result.context.analyzed_at}"
+elsif result.skipped?
+  puts "Skipping analyzation due to: #{result.reason}"
+elsif result.failed?
+  puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
+end
+```
+
+### 4. Observe
+
+```log
+I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
+index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
+
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
+```
+
+Ready to dive in? Check out the [Getting Started](getting_started.md) guide to learn more.
+
+## Ecosystem
+
+- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
+
+For backwards compatibility of certain functionality:
+
+- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations, `v1.5.0` - `v1.6.2`
+- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks, `v1.6.1` - `v1.6.2`
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/internationalization.md

@@ -1,17 +1,10 @@
 # Internationalization (i18n)
 
-CMDx provides comprehensive internationalization support for all error messages, attribute validation failures, coercion errors, and fault messages. All user-facing text is automatically localized based on the current `I18n.locale`, ensuring your applications can serve global audiences with native-language error reporting.
+CMDx supports 90+ languages out of the box for all error messages, validations, coercions, and faults. Error messages automatically adapt to the current `I18n.locale`, making it easy to build applications for global audiences.
 
-## Table of Contents
+## Usage
 
-- [Localization](#localization)
-- [Configuration](#configuration)
-  - [Local Copies](#local-copies)
-  - [Available Locales](#available-locales)
-
-## Localization
-
-CMDx automatically localizes all error messages based on the `I18n.locale` setting.
+All error messages are automatically localized based on your current locale:
 
 ```ruby
 class ProcessQuote < CMDx::Task
@@ -30,11 +23,11 @@ end
 
 ## Configuration
 
-Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+CMDx uses the `I18n` gem for localization. In Rails, locales load automatically.
 
-### Local Copies
+### Copy Locale Files
 
-Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+Copy locale files to your Rails application's `config/locales` directory:
 
 ```bash
 rails generate cmdx:locale [LOCALE]
@@ -131,8 +124,3 @@ rails generate cmdx:locale fr
 - zh-HK - Chinese (Hong Kong)
 - zh-TW - Chinese (Traditional)
 - zh-YUE - Chinese (Yue)
-
----
-
-- **Prev:** [Logging](logging.md)
-- **Next:** [Deprecation](deprecation.md)

data/docs/interruptions/exceptions.md

@@ -1,21 +1,16 @@
 # Interruptions - Exceptions
 
-CMDx provides robust exception handling that differs between the `execute` and `execute!` methods. Understanding how unhandled exceptions are processed is crucial for building reliable task execution flows and implementing proper error handling strategies.
-
-## Table of Contents
-
-- [Exception Handling](#exception-handling)
-  - [Non-bang execution](#non-bang-execution)
-  - [Bang execution](#bang-execution)
+Exception handling differs between `execute` and `execute!`. Choose the method that matches your error handling strategy.
 
 ## Exception Handling
 
-> [!IMPORTANT]
-> When designing tasks try not to `raise` your own exceptions directly, instead use `skip!` or `fail!` to signal intent clearly.
+!!! warning "Important"
+
+    Prefer `skip!` and `fail!` over raising exceptions—they signal intent more clearly.
 
 ### Non-bang execution
 
-The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
+Captures all exceptions and returns them as failed results:
 
 ```ruby
 class CompressDocument < CMDx::Task
@@ -33,9 +28,13 @@ result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
 result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
+!!! note
+
+    Use `exception_handler` with `execute` to send exceptions to APM tools before they become failed results.
+
 ### Bang execution
 
-The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
+Lets exceptions propagate naturally for standard Ruby error handling:
 
 ```ruby
 class CompressDocument < CMDx::Task
@@ -51,8 +50,3 @@ rescue ActiveRecord::NotFoundError => e
   puts "Handle exception: #{e.message}"
 end
 ```
-
----
-
-- **Prev:** [Interruptions - Faults](faults.md)
-- **Next:** [Outcomes - Result](../outcomes/result.md)

data/docs/interruptions/faults.md

@@ -1,19 +1,6 @@
 # Interruptions - Faults
 
-Faults are exception mechanisms that halt task execution via `skip!` and `fail!` methods. When tasks execute with the `execute!` method, fault exceptions matching the task's interruption status are raised, enabling sophisticated exception handling and control flow patterns.
-
-## Table of Contents
-
-- [Fault Types](#fault-types)
-- [Fault Handling](#fault-handling)
-- [Data Access](#data-access)
-- [Advanced Matching](#advanced-matching)
-  - [Task-Specific Matching](#task-specific-matching)
-  - [Custom Logic Matching](#custom-logic-matching)
-- [Fault Propagation](#fault-propagation)
-  - [Basic Propagation](#basic-propagation)
-  - [Additional Metadata](#additional-metadata)
-- [Chain Analysis](#chain-analysis)
+Faults are exceptions raised by `execute!` when tasks halt. They carry rich context about execution state, enabling sophisticated error handling patterns.
 
 ## Fault Types
 
@@ -23,8 +10,9 @@ Faults are exception mechanisms that halt task execution via `skip!` and `fail!`
 | `CMDx::SkipFault` | `skip!` method | Optional processing, early returns |
 | `CMDx::FailFault` | `fail!` method | Validation errors, processing failures |
 
-> [!IMPORTANT]
-> All fault exceptions inherit from `CMDx::Fault` and provide access to the complete task execution context including result, task, context, and chain information.
+!!! warning "Important"
+
+    All faults inherit from `CMDx::Fault` and expose result, task, context, and chain data.
 
 ## Fault Handling
 
@@ -45,7 +33,7 @@ end
 
 ## Data Access
 
-Faults provide comprehensive access to execution context, eg:
+Access rich execution data from fault exceptions:
 
 ```ruby
 begin
@@ -74,7 +62,7 @@ end
 
 ### Task-Specific Matching
 
-Use `for?` to handle faults only from specific task classes, enabling targeted exception handling in complex workflows.
+Handle faults only from specific tasks using `for?`:
 
 ```ruby
 begin
@@ -104,7 +92,7 @@ end
 
 ## Fault Propagation
 
-Use `throw!` to propagate failures while preserving fault context and maintaining the error chain for debugging.
+Propagate failures with `throw!` to preserve context and maintain the error chain:
 
 ### Basic Propagation
 
@@ -151,7 +139,7 @@ end
 
 ## Chain Analysis
 
-Results provide methods to analyze fault propagation and identify original failure sources in complex execution chains.
+Trace fault origins and propagation through the execution chain:
 
 ```ruby
 result = DocumentWorkflow.execute(invalid_data)
@@ -179,8 +167,3 @@ if result.failed?
   end
 end
 ```
-
----
-
-- **Prev:** [Interruptions - Halt](halt.md)
-- **Next:** [Interruptions - Exceptions](exceptions.md)

data/docs/interruptions/halt.md

@@ -1,25 +1,14 @@
 # Interruptions - Halt
 
-Halting stops task execution with explicit intent signaling. Tasks provide two primary halt methods that control execution flow and result in different outcomes.
-
-## Table of Contents
-
-- [Skipping](#skipping)
-- [Failing](#failing)
-- [Metadata Enrichment](#metadata-enrichment)
-- [State Transitions](#state-transitions)
-- [Execution Behavior](#execution-behavior)
-  - [Non-bang execution](#non-bang-execution)
-  - [Bang execution](#bang-execution)
-- [Best Practices](#best-practices)
-- [Manual Errors](#manual-errors)
+Stop task execution intentionally using `skip!` or `fail!`. Both methods signal clear intent about why execution stopped.
 
 ## Skipping
 
-`skip!` communicates that the task is to be intentionally bypassed. This represents a controlled, intentional interruption where the task determines that execution is not necessary or appropriate.
+Use `skip!` when the task doesn't need to run. It's a no-op, not an error.
+
+!!! warning "Important"
 
-> [!IMPORTANT]
-> Skipping is a no-op, not a failure or error and are considered successful outcomes.
+    Skipped tasks are considered "good" outcomes—they succeeded by doing nothing.
 
 ```ruby
 class ProcessInventory < CMDx::Task
@@ -54,7 +43,7 @@ result.reason #=> "Warehouse closed"
 
 ## Failing
 
-`fail!` communicates that the task encountered an impediment that prevents successful completion. This represents controlled failure where the task explicitly determines that execution cannot continue.
+Use `fail!` when the task can't complete successfully. It signals controlled, intentional failure:
 
 ```ruby
 class ProcessRefund < CMDx::Task
@@ -89,7 +78,7 @@ result.reason #=> "Refund period has expired"
 
 ## Metadata Enrichment
 
-Both halt methods accept metadata to provide additional context about the interruption. Metadata is stored as a hash and becomes available through the result object.
+Enrich halt calls with metadata for better debugging and error handling:
 
 ```ruby
 class ProcessRenewal < CMDx::Task
@@ -189,7 +178,7 @@ end
 
 ## Best Practices
 
-Always try to provide a `reason` when using halt methods. This provides clear context for debugging and creates meaningful exception messages.
+Always provide a reason for better debugging and clearer exception messages:
 
 ```ruby
 # Good: Clear, specific reason
@@ -207,10 +196,11 @@ fail! #=> "Unspecified"
 
 ## Manual Errors
 
-There are rare cases where you need to manually assign errors.
+For rare cases, manually add errors before halting:
 
-> [!IMPORTANT]
-> Keep in mind you will still need to initiate a fault if a stoppage of work is required.
+!!! warning "Important"
+
+    Manual errors don't stop execution—you still need to call `fail!` or `skip!`.
 
 ```ruby
 class ProcessRenewal < CMDx::Task
@@ -224,8 +214,3 @@ class ProcessRenewal < CMDx::Task
   end
 end
 ```
-
----
-
-- **Prev:** [Basics - Chain](../basics/chain.md)
-- **Next:** [Interruptions - Faults](faults.md)

data/docs/logging.md

@@ -1,16 +1,10 @@
 # Logging
 
-CMDx provides comprehensive automatic logging for task execution with structured data, customizable formatters, and intelligent severity mapping. All task results are logged after completion with rich metadata for debugging and monitoring.
-
-## Table of Contents
-
-- [Formatters](#formatters)
-- [Structure](#structure)
-- [Usage](#usage)
+CMDx automatically logs every task execution with structured data, making debugging and monitoring effortless. Choose from multiple formatters to match your logging infrastructure.
 
 ## Formatters
 
-CMDx supports multiple log formatters to integrate with various logging systems:
+Choose the format that works best for your logging system:
 
 | Formatter | Use Case | Output Style |
 |-----------|----------|--------------|
@@ -40,12 +34,13 @@ E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
 index=3 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="BillingWorkflow"  state="interrupted" status="failed" caused_failure={index: 2, class: "CalculateTax", status: "failed"} threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
 ```
 
-> [!TIP]
-> Logging can be used as low-level eventing system, ingesting all tasks performed within a small action or long running request. This ie where correlation is especially handy.
+!!! tip
+
+    Use logging as a low-level event stream to track all tasks in a request. Combine with correlation for powerful distributed tracing.
 
 ## Structure
 
-All log entries include comprehensive execution metadata. Field availability depends on execution context and outcome.
+Every log entry includes rich metadata. Available fields depend on execution context and outcome.
 
 ### Core Fields
 
@@ -86,7 +81,7 @@ All log entries include comprehensive execution metadata. Field availability dep
 
 ## Usage
 
-Tasks have access to the frameworks logger.
+Access the framework logger directly within tasks:
 
 ```ruby
 class ProcessSubscription < CMDx::Task
@@ -97,8 +92,3 @@ class ProcessSubscription < CMDx::Task
   end
 end
 ```
-
----
-
-- **Prev:** [Middlewares](middlewares.md)
-- **Next:** [Internationalization (i18n)](internationalization.md)

data/docs/middlewares.md

@@ -1,27 +1,16 @@
 # Middlewares
 
-Middleware provides Rack-style wrappers around task execution for cross-cutting concerns like authentication, logging, caching, and error handling.
+Wrap task execution with middleware for cross-cutting concerns like authentication, caching, timeouts, and monitoring. Think Rack middleware, but for your business logic.
 
-Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#middlewares) docs for global configuration.
+See [Global Configuration](getting_started.md#middlewares) for framework-wide setup.
 
-## Table of Contents
+## Execution Order
 
-- [Order](#order)
-- [Declarations](#declarations)
-  - [Proc or Lambda](#proc-or-lambda)
-  - [Class or Module](#class-or-module)
-- [Removals](#removals)
-- [Built-in](#built-in)
-  - [Timeout](#timeout)
-  - [Correlate](#correlate)
-  - [Runtime](#runtime)
+Middleware wraps task execution in layers, like an onion:
 
-## Order
+!!! note
 
-Middleware executes in a nested fashion, creating an onion-like execution pattern:
-
-> [!NOTE]
-> Middleware executes in the order they are registered, with the first registered middleware being the outermost wrapper.
+    First registered = outermost wrapper. They execute in registration order.
 
 ```ruby
 class ProcessCampaign < CMDx::Task
@@ -97,10 +86,11 @@ end
 
 ## Removals
 
-Class and Module based declarations can be removed at a global and task level.
+Remove class or module-based middleware globally or per-task:
+
+!!! warning
 
-> [!WARNING]
-> Only one removal operation is allowed per `deregister` call. Multiple removals require separate calls.
+    Each `deregister` call removes one middleware. Use multiple calls for batch removals.
 
 ```ruby
 class ProcessCampaign < CMDx::Task
@@ -113,7 +103,7 @@ end
 
 ### Timeout
 
-Ensures task execution doesn't exceed a specified time limit:
+Prevent tasks from running too long:
 
 ```ruby
 class ProcessReport < CMDx::Task
@@ -149,7 +139,7 @@ result.metadata #=> { limit: 3 }
 
 ### Correlate
 
-Tags tasks with a global correlation ID for distributed tracing:
+Add correlation IDs for distributed tracing and request tracking:
 
 ```ruby
 class ProcessExport < CMDx::Task
@@ -179,8 +169,7 @@ result.metadata #=> { correlation_id: "550e8400-e29b-41d4-a716-446655440000" }
 
 ### Runtime
 
-The runtime middleware tags tasks with how long it took to execute the task.
-The calculation uses a monotonic clock and the time is returned in milliseconds.
+Track task execution time in milliseconds using a monotonic clock:
 
 ```ruby
 class PerformanceMonitoringCheck
@@ -200,8 +189,3 @@ end
 result = ProcessExport.execute
 result.metadata #=> { runtime: 1247 } (ms)
 ```
-
----
-
-- **Prev:** [Callbacks](callbacks.md)
-- **Next:** [Logging](logging.md)

data/docs/outcomes/result.md

@@ -1,27 +1,14 @@
 # Outcomes - Result
 
-The result object is the comprehensive return value of task execution, providing complete information about the execution outcome, state, timing, and any data produced during the task lifecycle. Results serve as the primary interface for inspecting task execution outcomes and chaining task operations.
-
-## Table of Contents
-
-- [Result Attributes](#result-attributes)
-- [Lifecycle Information](#lifecycle-information)
-- [Outcome Analysis](#outcome-analysis)
-- [Chain Analysis](#chain-analysis)
-- [Index and Position](#index-and-position)
-- [Block Yield](#block-yield)
-- [Handlers](#handlers)
-- [Pattern Matching](#pattern-matching)
-  - [Array Pattern](#array-pattern)
-  - [Hash Pattern](#hash-pattern)
-  - [Pattern Guards](#pattern-guards)
+Results are your window into task execution. They expose everything: outcome, state, timing, context, and metadata.
 
 ## Result Attributes
 
-Every result provides access to essential execution information:
+Access essential execution information:
 
-> [!IMPORTANT]
-> Result objects are immutable after task execution completes and reflect the final state.
+!!! warning "Important"
+
+    Results are immutable after execution completes.
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
@@ -43,7 +30,7 @@ result.metadata #=> { error_code: "BUILD_TOOL.NOT_FOUND" }
 
 ## Lifecycle Information
 
-Results provide comprehensive methods for checking execution state and status:
+Check execution state and status with predicate methods:
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
@@ -65,7 +52,7 @@ result.bad?         #=> false (skipped or failed)
 
 ## Outcome Analysis
 
-Results provide unified outcome determination depending on the fault causal chain:
+Get a unified outcome string combining state and status:
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
@@ -75,7 +62,7 @@ result.outcome #=> "success" (state and status)
 
 ## Chain Analysis
 
-Use these methods to trace the root cause of faults or trace the cause points.
+Trace fault origins and propagation:
 
 ```ruby
 result = DeploymentWorkflow.execute(app_name: "webapp")
@@ -116,7 +103,7 @@ result.chain.results[result.index] == result #=> true
 
 ## Block Yield
 
-Implement conditional logic using a block expression that yields a result for complete encapsulation.
+Execute code with direct result access:
 
 ```ruby
 BuildApplication.execute(version: "1.2.3") do |result|
@@ -132,34 +119,35 @@ end
 
 ## Handlers
 
-Use result handlers for clean, functional-style conditional logic. Handlers return the result object, enabling method chaining and fluent interfaces.
+Handle outcomes with functional-style methods. Handlers return the result for chaining:
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
 
 # Status-based handlers
 result
-  .on_success { |result| notify_deployment_ready(result) }
-  .on_failed { |result| handle_build_failure(result) }
-  .on_skipped { |result| log_skip_reason(result) }
+  .handle_success { |result| notify_deployment_ready(result) }
+  .handle_failed { |result| handle_build_failure(result) }
+  .handle_skipped { |result| log_skip_reason(result) }
 
 # State-based handlers
 result
-  .on_complete { |result| update_build_status(result) }
-  .on_interrupted { |result| cleanup_partial_artifacts(result) }
+  .handle_complete { |result| update_build_status(result) }
+  .handle_interrupted { |result| cleanup_partial_artifacts(result) }
 
 # Outcome-based handlers
 result
-  .on_good { |result| increment_success_counter(result) }
-  .on_bad { |result| alert_operations_team(result) }
+  .handle_good { |result| increment_success_counter(result) }
+  .handle_bad { |result| alert_operations_team(result) }
 ```
 
 ## Pattern Matching
 
-Results support Ruby's pattern matching through array and hash deconstruction:
+Use Ruby 3.0+ pattern matching for elegant outcome handling:
+
+!!! warning "Important"
 
-> [!IMPORTANT]
-> Pattern matching requires Ruby 3.0+
+    Pattern matching works with both array and hash deconstruction.
 
 ### Array Pattern
 
@@ -203,8 +191,3 @@ in { runtime: time } if time > performance_threshold
   investigate_build_performance(result)
 end
 ```
-
----
-
-- **Prev:** [Interruptions - Exceptions](../interruptions/exceptions.md)
-- **Next:** [Outcomes - States](states.md)