cmdx 1.7.0 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8483d78b67a6dfffa6721b39e623ac08d57d443b499287891bfb9c6e06422c89
-  data.tar.gz: 02cb722299d6a97fb4e2d07a84880c7374a8c17b691f42bee995bd4f3ea698ab
+  metadata.gz: 528f3b3b1d4f23045a295cc15c05106c3bd0f9efde6400bb88c01bb2a6455637
+  data.tar.gz: 473ca317fd214b48e4e4988ba4358bdcff4a3fc9f9805300dba292f4401e51c1
 SHA512:
-  metadata.gz: b6600b6d617c11a3ec3b66367a7fa309e191bd2d1f20a3fb1a538565a0c2b45e05f8093f2c3e07edbb155e308e6c90c486f069db171aac68e8658bbe85bd4b34
-  data.tar.gz: 6ad4a1348066d3aa4d0ed2733fc88f94af293835cc970be5986f3c002cf3b3615f474bff774a2b48f7e043920ca01b5f278cd26850b5b4827a70d2a4b0e6ab50
+  metadata.gz: 5b48be81fa184343f76c1891a3b87c25853e0dc859764dbf92946c7b31d69fd4af85b75eee7720470e29949edb395bce668343dbc6b17916079ba9befd1fbc80
+  data.tar.gz: b95fe96f12cf2aeb724782808d80b4ee36e083d0f6c60876edac45a6046c7925437f329dc2f98a42432b4794996c3269f71ba7f93452f161a38f365c6d40afa6

data/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [1.7.2] - 2025-09-03
+
+### Changes
+- Correlation ID is set before continuing to further steps
+
+## [1.7.1] - 2025-08-26
+
+### Added
+- Yield result if block given to `execute` and `execute!` methods
+
 ## [1.7.0] - 2025-08-25
 
 ### Added

data/LLM.md

@@ -11,6 +11,31 @@ url: https://github.com/drexed/cmdx/blob/main/docs/getting_started.md
 
 CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic attribute validation, structured error handling, comprehensive logging, and intelligent execution flow control.
 
+**Common Challenges:**
+
+- Inconsistent patterns across implementations
+- Minimal or no logging, making debugging painful
+- Fragile designs that erode developer confidence
+
+**CMDx Solutions:**
+
+- Establishes a consistent, standardized design
+- Provides flow control and error handling
+- Supports composable, reusable workflows
+- Includes detailed logging for observability
+- Defines input attributes with fallback defaults
+- Adds validations and type coercions
+- Plus many other developer-friendly tools
+
+## Compose, Execute, React, Observe pattern
+
+CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
+
+- **Compose** → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
+- **Execute** → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
+- **React** → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
+- **Observe** → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
+
 ## Installation
 
 Add CMDx to your Gemfile:
@@ -1251,6 +1276,22 @@ result.index #=> 0 (first task in chain)
 result.chain.results[result.index] == result #=> true
 ```
 
+## Block Yield
+
+Implement conditional logic using a block expression that yields a result for complete encapsulation.
+
+```ruby
+BuildApplication.execute(version: "1.2.3") do |result|
+  if result.success?
+    notify_deployment_ready(result)
+  elsif result.failed?
+    handle_build_failure(result)
+  else
+    log_skip_reason(result)
+  end
+end
+```
+
 ## Handlers
 
 Use result handlers for clean, functional-style conditional logic. Handlers return the result object, enabling method chaining and fluent interfaces.
@@ -2727,21 +2768,19 @@ Sample output:
 ```log
 <!-- Success (INFO level) -->
 I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task"
-class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
 
 <!-- Skipped (WARN level) -->
 W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 state="interrupted" status="skipped" reason="Customer already validated"
+index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
 
 <!-- Failed (ERROR level) -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
 
 <!-- Failed Chain -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-caused_failure={index: 2, class: "CalculateTax", status: "failed"}
-threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
+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]

data/README.md

@@ -8,16 +8,24 @@
   <img alt="License" src="https://img.shields.io/github/license/drexed/cmdx">
 </p>
 
-# CMDx
+# 🚀 CMDx — Business logic without the chaos
 
-CMDx is a framework for building maintainable business processes. It simplifies building task objects by offering integrated:
+Stop wrestling with messy service objects. CMDx gives you a clean, consistent way to design business processes:
 
-- Flow controls
-- Composable workflows
-- Comprehensive logging
-- Attribute definition
-- Validations and coercions
-- And much more...
+- Start small with a single `work` method
+- Scale to complex tasks and multi-step workflows
+- Get built-in flow control, logging, validations, and more...
+
+*Build faster. Debug easier. Stay sane.*
+
+## Compose, Execute, React, Observe pattern
+
+CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
+
+- **Compose** → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
+- **Execute** → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
+- **React** → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
+- **Observe** → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
 
 ## Installation
 
@@ -37,11 +45,24 @@ Or install it yourself as:
 
 ## Quick Example
 
-Here's how a quick 3 step process can open up a world of possibilities:
+Here's how a quick 4 step process can open up a world of possibilities:
+
+### 1. Compose
+
+#### Minimum Viable Task
+
+```ruby
+class SendAnalyzedEmail < CMDx::Task
+  def work
+    user = User.find(context.user_id)
+    MetricsMailer.analyzed(user).deliver_now
+  end
+end
+```
+
+#### Fully Featured Task
 
 ```ruby
-# 1. Setup task
-# ---------------------------------
 class AnalyzeMetrics < CMDx::Task
   register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
 
@@ -56,8 +77,10 @@ class AnalyzeMetrics < CMDx::Task
     elsif dataset.unprocessed?
       skip!("Dataset not ready for analysis")
     else
-      context.result = PValueAnalyzer.analyze(dataset, analysis_type)
+      context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
       context.analyzed_at = Time.now
+
+      SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
     end
   end
 
@@ -71,16 +94,20 @@ class AnalyzeMetrics < CMDx::Task
     dataset.update!(analysis_result_id: context.result.id)
   end
 end
+```
 
-# 2. Execute task
-# ---------------------------------
+### 2. Execute
+
+```ruby
 result = AnalyzeMetrics.execute(
   dataset_id: 123,
   "analysis_type" => "advanced"
 )
+```
 
-# 3. Handle result
-# ---------------------------------
+### 3. React
+
+```ruby
 if result.success?
   puts "Metrics analyzed at #{result.context.analyzed_at}"
 elsif result.skipped?
@@ -90,6 +117,16 @@ elsif result.failed?
 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}
+```
+
 ## Table of contents
 
 - [Getting Started](docs/getting_started.md)
@@ -122,12 +159,12 @@ end
 
 ## Ecosystem
 
-- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations
-- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks
+- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
 
-The following gems are currently under development:
+For backwards compatibility of certain functionality:
 
-- `cmdx-testing` - RSpec and Minitest matchers
+- [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`
 
 ## Development
 

data/docs/getting_started.md

@@ -2,8 +2,25 @@
 
 CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic attribute validation, structured error handling, comprehensive logging, and intelligent execution flow control.
 
+**Common Challenges:**
+
+- Inconsistent patterns across implementations
+- Minimal or no logging, making debugging painful
+- Fragile designs that erode developer confidence
+
+**CMDx Solutions:**
+
+- Establishes a consistent, standardized design
+- Provides flow control and error handling
+- Supports composable, reusable workflows
+- Includes detailed logging for observability
+- Defines input attributes with fallback defaults
+- Adds validations and type coercions
+- Plus many other developer-friendly tools
+
 ## Table of Contents
 
+- [Compose, Execute, React, Observe pattern](#compose-execute-react-observe-pattern)
 - [Installation](#installation)
 - [Configuration Hierarchy](#configuration-hierarchy)
 - [Global Configuration](#global-configuration)
@@ -21,6 +38,15 @@ CMDx is a Ruby framework for building maintainable, observable business logic th
   - [Resetting](#resetting)
 - [Task Generator](#task-generator)
 
+## Compose, Execute, React, Observe pattern
+
+CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
+
+- *Compose* → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
+- *Execute* → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
+- *React* → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
+- *Observe* → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
+
 ## Installation
 
 Add CMDx to your Gemfile:

data/docs/logging.md

@@ -25,21 +25,19 @@ Sample output:
 ```log
 <!-- Success (INFO level) -->
 I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task"
-class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
 
 <!-- Skipped (WARN level) -->
 W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 state="interrupted" status="skipped" reason="Customer already validated"
+index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
 
 <!-- Failed (ERROR level) -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
 
 <!-- Failed Chain -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-caused_failure={index: 2, class: "CalculateTax", status: "failed"}
-threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
+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]

data/docs/outcomes/result.md

@@ -9,6 +9,7 @@ The result object is the comprehensive return value of task execution, providing
 - [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)
@@ -113,6 +114,22 @@ result.index #=> 0 (first task in chain)
 result.chain.results[result.index] == result #=> true
 ```
 
+## Block Yield
+
+Implement conditional logic using a block expression that yields a result for complete encapsulation.
+
+```ruby
+BuildApplication.execute(version: "1.2.3") do |result|
+  if result.success?
+    notify_deployment_ready(result)
+  elsif result.failed?
+    handle_build_failure(result)
+  else
+    log_skip_reason(result)
+  end
+end
+```
+
 ## Handlers
 
 Use result handlers for clean, functional-style conditional logic. Handlers return the result object, enabling method chaining and fluent interfaces.

data/lib/cmdx/middlewares/correlate.rb

@@ -95,7 +95,8 @@ module CMDx
       def call(task, **options, &)
         return yield unless Utils::Condition.evaluate(task, options)
 
-        correlation_id =
+        correlation_id = task.result.metadata[:correlation_id] ||=
+          id ||
           case callable = options[:id]
           when Symbol then task.send(callable)
           when Proc then task.instance_eval(&callable)
@@ -107,9 +108,7 @@ module CMDx
             end
           end
 
-        result = use(correlation_id, &)
-        task.result.metadata[:correlation_id] = correlation_id
-        result
+        use(correlation_id, &)
       end
 
     end

data/lib/cmdx/task.rb

@@ -169,10 +169,10 @@ module CMDx
       #   if result.success?
       #     puts "Task completed successfully"
       #   end
-      def execute(...)
-        task = new(...)
+      def execute(*args, **kwargs)
+        task = new(*args, **kwargs)
         task.execute(raise: false)
-        task.result
+        block_given? ? yield(task.result) : task.result
       end
 
       # @param args [Array] Arguments to pass to the task constructor
@@ -184,10 +184,10 @@ module CMDx
       # @example
       #   result = MyTask.execute!(name: "example")
       #   # Will raise an exception if execution fails
-      def execute!(...)
-        task = new(...)
+      def execute!(*args, **kwargs)
+        task = new(*args, **kwargs)
         task.execute(raise: true)
-        task.result
+        block_given? ? yield(task.result) : task.result
       end
 
     end
@@ -201,6 +201,7 @@ module CMDx
     #   result = task.execute(raise: true)
     def execute(raise: false)
       Executor.execute(self, raise:)
+      block_given? ? yield(result) : result
     end
 
     # @raise [UndefinedMethodError] Always raised as this method must be overridden

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.7.0"
+  VERSION = "1.7.2"
 
 end

data/lib/generators/cmdx/locale_generator.rb

@@ -10,7 +10,7 @@ module Cmdx
 
     source_root File.expand_path("../../locales", __dir__)
 
-    desc "Copies the locale with the given alpha-2 code"
+    desc "Copies the locale with the given ISO 639 code"
 
     argument :locale, type: :string, default: "en", banner: "locale: en, es, fr, etc"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.2
 platform: ruby
 authors:
 - Juan Gomez