cmdx 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd6e2321faffcce3015989a0e58df96c87be1dbdc4755cc7b783546bc5ecbc4f
-  data.tar.gz: cc5f262ac3f329a308e8a0c25a0f200830830d09c3560c913f8a80ff5997aab8
+  metadata.gz: ef05af7473358890c311d872369f870fbaa7ff7bf2fd6d6d14cddd9c9dc80aec
+  data.tar.gz: 8e1c20c5991d453f947ed5aea44099c9c05861ad11637b27eb02bb5baea4e4f2
 SHA512:
-  metadata.gz: 71e5f8a864f91b10ca26985bfbd7502fcc751e70117562bee62f606f340468bd517e329a05de5f80d495ff7bb0aaf0195564ceaa95267b9bfdba6d3c424c0698
-  data.tar.gz: 2d560416d0838761e481952a5d759e05db859fef027e74a5c6c5bb65e49756ab041a35f7725d88ba40746b93f2726bee65e317b7c89d5e56291dd9767c99603f
+  metadata.gz: c59da9cc99292e6241bf9d7fabb91cc00887a6b8a4cd18950c22a495a1adfdc32a769194818944726da0e732e8fb23c842c7086d67ea451f2556a31c4f3a5ef2
+  data.tar.gz: 89d64b25f51d583605960e19d9b08b366dc4269b5c2ca07cddf562714aaf2cc4c0d9f1a06bbae42ed0ba9ed536715030c4d79dbf8c486305bd4891c331a5107d

data/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [1.6.0] - 2025-08-22
+
+### Changes
+- Rename `Worker` class to `Executor`
+- Move workflow `work` logic into `Pipeline`
+- Add workflow task `:breakpoints`
+
+## [1.5.2] - 2025-08-22
+
+### Changes
+- Rename workflow `execution_groups` attribute to `pipeline`
+
 ## [1.5.1] - 2025-08-21
 
 ### Changes

data/LLM.md

@@ -44,11 +44,20 @@ Globally these settings are initialized with sensible defaults.
 
 ### Breakpoints
 
-Breakpoints control when `execute!` raises faults.
+Raise `CMDx::Fault` when a task called with `execute!` returns a matching status.
 
 ```ruby
 CMDx.configure do |config|
-  config.task_breakpoints = "skipped"
+  # String or Array[String]
+  config.task_breakpoints = "failed"
+end
+```
+
+Workflow breakpoints stops execution and of workflow pipeline on the first task that returns a matching status and throws its `CMDx::Fault`.
+
+```ruby
+CMDx.configure do |config|
+  # String or Array[String]
   config.workflow_breakpoints = ["skipped", "failed"]
 end
 ```
@@ -2785,8 +2794,7 @@ CMDx provides comprehensive internationalization support for all error messages,
 
 ## Localization
 
-> [!NOTE]
-> CMDx automatically localizes all error messages based on the `I18n.locale` setting.
+CMDx automatically localizes all error messages based on the `I18n.locale` setting.
 
 ```ruby
 class ProcessQuote < CMDx::Task
@@ -2803,6 +2811,9 @@ I18n.with_locale(:fr) do
 end
 ```
 
+> [!TIP]
+> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+
 ---
 
 url: https://github.com/drexed/cmdx/blob/main/docs/deprecation.md
@@ -2964,7 +2975,7 @@ Workflow orchestrates sequential execution of multiple tasks in a linear pipelin
 
 ## Declarations
 
-Tasks execute in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
+Tasks execute sequentially in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
 
 > [!IMPORTANT]
 > Do **NOT** define a `work` method in workflow tasks. The included module automatically provides the execution logic.

data/README.md

@@ -122,13 +122,12 @@ end
 
 ## Ecosystem
 
+- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations
+
 The following gems are currently under development:
 
-- `cmdx-i18n` I18n locales
-- `cmdx-rspec` RSpec matchers
-- `cmdx-minitest` Minitest matchers
-- `cmdx-jobs` Background job integrations
-- `cmdx-parallel` Parallel workflow task execution
+- `cmdx-testing` - RSpec and Minitest matchers
+- `cmdx-parallel` - Parallel workflow task execution
 
 ## Development
 

data/docs/getting_started.md

@@ -54,11 +54,20 @@ Globally these settings are initialized with sensible defaults.
 
 ### Breakpoints
 
-Breakpoints control when `execute!` raises faults.
+Raise `CMDx::Fault` when a task called with `execute!` returns a matching status.
 
 ```ruby
 CMDx.configure do |config|
-  config.task_breakpoints = "skipped"
+  # String or Array[String]
+  config.task_breakpoints = "failed"
+end
+```
+
+Workflow breakpoints stops execution and of workflow pipeline on the first task that returns a matching status and throws its `CMDx::Fault`.
+
+```ruby
+CMDx.configure do |config|
+  # String or Array[String]
   config.workflow_breakpoints = ["skipped", "failed"]
 end
 ```

data/docs/internationalization.md

@@ -8,8 +8,7 @@ CMDx provides comprehensive internationalization support for all error messages,
 
 ## Localization
 
-> [!NOTE]
-> CMDx automatically localizes all error messages based on the `I18n.locale` setting.
+CMDx automatically localizes all error messages based on the `I18n.locale` setting.
 
 ```ruby
 class ProcessQuote < CMDx::Task
@@ -26,6 +25,9 @@ I18n.with_locale(:fr) do
 end
 ```
 
+> [!TIP]
+> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+
 ---
 
 - **Prev:** [Logging](logging.md)

data/docs/workflows.md

@@ -15,7 +15,7 @@ Workflow orchestrates sequential execution of multiple tasks in a linear pipelin
 
 ## Declarations
 
-Tasks execute in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
+Tasks execute sequentially in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
 
 > [!IMPORTANT]
 > Do **NOT** define a `work` method in workflow tasks. The included module automatically provides the execution logic.

data/lib/cmdx/{worker.rb → executor.rb}

@@ -3,19 +3,19 @@
 module CMDx
   # Executes CMDx tasks with middleware support, error handling, and lifecycle management.
   #
-  # The Worker class is responsible for orchestrating task execution, including
+  # The Executor class is responsible for orchestrating task execution, including
   # pre-execution validation, execution with middleware, post-execution callbacks,
   # and proper error handling for different types of failures.
-  class Worker
+  class Executor
 
     attr_reader :task
 
     # @param task [CMDx::Task] The task to execute
     #
-    # @return [CMDx::Worker] A new worker instance
+    # @return [CMDx::Executor] A new executor instance
     #
     # @example
-    #   worker = CMDx::Worker.new(my_task)
+    #   executor = CMDx::Executor.new(my_task)
     def initialize(task)
       @task = task
     end
@@ -30,8 +30,8 @@ module CMDx
     # @raise [StandardError] When raise is true and execution fails
     #
     # @example
-    #   CMDx::Worker.execute(my_task)
-    #   CMDx::Worker.execute(my_task, raise: true)
+    #   CMDx::Executor.execute(my_task)
+    #   CMDx::Executor.execute(my_task, raise: true)
     def self.execute(task, raise: false)
       instance = new(task)
       raise ? instance.execute! : instance.execute
@@ -42,8 +42,8 @@ module CMDx
     # @return [CMDx::Result] The execution result
     #
     # @example
-    #   worker = CMDx::Worker.new(my_task)
-    #   result = worker.execute
+    #   executor = CMDx::Executor.new(my_task)
+    #   result = executor.execute
     def execute
       task.class.settings[:middlewares].call!(task) do
         pre_execution!
@@ -69,8 +69,8 @@ module CMDx
     # @raise [StandardError] When execution fails
     #
     # @example
-    #   worker = CMDx::Worker.new(my_task)
-    #   result = worker.execute!
+    #   executor = CMDx::Executor.new(my_task)
+    #   result = executor.execute!
     def execute!
       task.class.settings[:middlewares].call!(task) do
         pre_execution!

data/lib/cmdx/pipeline.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Executes workflows by processing task groups with conditional logic and breakpoint handling.
+  # The Pipeline class manages the execution flow of workflow tasks, evaluating conditions
+  # and handling breakpoints that can interrupt execution at specific task statuses.
+  class Pipeline
+
+    # @return [Workflow] The workflow instance being executed
+    attr_reader :workflow
+
+    # @param workflow [Workflow] The workflow to execute
+    #
+    # @return [Pipeline] A new pipeline instance
+    #
+    # @example
+    #   pipeline = Pipeline.new(my_workflow)
+    def initialize(workflow)
+      @workflow = workflow
+    end
+
+    # Executes a workflow using a new pipeline instance.
+    #
+    # @param workflow [Workflow] The workflow to execute
+    #
+    # @return [void]
+    #
+    # @example
+    #   Pipeline.execute(my_workflow)
+    def self.execute(workflow)
+      new(workflow).execute
+    end
+
+    # Executes the workflow by processing all task groups in sequence.
+    # Each group is evaluated against its conditions, and breakpoints are checked
+    # after each task execution to determine if workflow should continue or halt.
+    #
+    # @return [void]
+    #
+    # @example
+    #   pipeline = Pipeline.new(my_workflow)
+    #   pipeline.execute
+    def execute
+      workflow.class.pipeline.each do |group|
+        next unless Utils::Condition.evaluate(workflow, group.options, workflow)
+
+        breakpoints = group.options[:breakpoints] ||
+                      workflow.class.settings[:breakpoints] ||
+                      workflow.class.settings[:workflow_breakpoints]
+        breakpoints = Array(breakpoints).map(&:to_s).uniq
+
+        execute_group_tasks(group, breakpoints)
+      end
+    end
+
+    private
+
+    # Executes tasks within a group using the configured execution strategy.
+    # Override this method to implement custom execution strategies like parallel
+    # processing or conditional task execution.
+    #
+    # @param group [ExecutionGroup] The group of tasks to execute
+    # @param breakpoints [Array<String>] Breakpoint statuses that trigger workflow interruption
+    #
+    # @return [void]
+    #
+    # @example
+    #   def execute_group_tasks(group, breakpoints)
+    #     # Custom parallel execution strategy
+    #     group.tasks.map { |task| Thread.new { task.execute(workflow.context) } }
+    #   end
+    def execute_group_tasks(group, breakpoints)
+      # NOTE: Override this method to introduce alternative execution strategies
+      execute_tasks_sequentially(group, breakpoints)
+    end
+
+    # Executes tasks sequentially within a group, checking breakpoints after each task.
+    # If a task result status matches a breakpoint, the workflow is interrupted.
+    #
+    # @param group [ExecutionGroup] The group of tasks to execute
+    # @param breakpoints [Array<String>] Breakpoint statuses that trigger workflow interruption
+    #
+    # @return [void]
+    #
+    # @raise [HaltError] When a task result status matches a breakpoint
+    #
+    # @example
+    #   execute_tasks_sequentially(group, ["failed", "skipped"])
+    def execute_tasks_sequentially(group, breakpoints)
+      group.tasks.each do |task|
+        task_result = task.execute(workflow.context)
+        next unless breakpoints.include?(task_result.status)
+
+        workflow.throw!(task_result)
+      end
+    end
+
+  end
+end

data/lib/cmdx/task.rb

@@ -200,7 +200,7 @@ module CMDx
     #   result = task.execute
     #   result = task.execute(raise: true)
     def execute(raise: false)
-      Worker.execute(self, raise:)
+      Executor.execute(self, raise:)
     end
 
     # @raise [UndefinedMethodError] Always raised as this method must be overridden

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.5.1"
+  VERSION = "1.6.0"
 
 end

data/lib/cmdx/workflow.rb

@@ -35,10 +35,10 @@ module CMDx
       #     include CMDx::Workflow
       #     task Task1
       #     task Task2
-      #     puts execution_groups.size # => 2
+      #     puts pipeline.size # => 2
       #   end
-      def execution_groups
-        @execution_groups ||= []
+      def pipeline
+        @pipeline ||= []
       end
 
       # Adds multiple tasks to the workflow with optional configuration.
@@ -56,7 +56,7 @@ module CMDx
       #     tasks ValidateTask, ProcessTask, NotifyTask, breakpoints: [:failure, :halt]
       #   end
       def tasks(*tasks, **options)
-        execution_groups << ExecutionGroup.new(
+        pipeline << ExecutionGroup.new(
           tasks.map do |task|
             next task if task.is_a?(Class) && (task <= Task)
 
@@ -87,39 +87,21 @@ module CMDx
       base.extend(ClassMethods)
     end
 
-    # Executes the workflow by processing each execution group sequentially.
-    # Tasks within each group are executed based on conditional logic and breakpoint handling.
+    # Executes the workflow by processing all tasks in the pipeline.
+    # This method delegates execution to the Pipeline class which handles
+    # the processing of tasks with proper error handling and context management.
     #
-    # @return [void]
-    #
-    # @raise [CMDx::Fault] If a breakpoint is encountered during execution
-    #
-    # @example
-    #   workflow = MyWorkflow.new
-    #   workflow.work # Executes all tasks in the workflow
     # @example
-    #   class DataProcessingWorkflow
+    #   class MyWorkflow
     #     include CMDx::Workflow
-    #     task ValidateDataTask, breakpoints: [:failure]
-    #     task ProcessDataTask, breakpoints: [:halt]
-    #     task NotifyCompletionTask
+    #     task ValidateTask
+    #     task ProcessTask
     #   end
-    #   workflow = DataProcessingWorkflow.new
-    #   workflow.work # Stops on first breakpoint encountered
+    #
+    #   workflow = MyWorkflow.new
+    #   result = workflow.work
     def work
-      self.class.execution_groups.each do |group|
-        next unless Utils::Condition.evaluate(self, group.options, self)
-
-        breakpoints = group.options[:breakpoints] || self.class.settings[:workflow_breakpoints]
-        breakpoints = Array(breakpoints).map(&:to_s).uniq
-
-        group.tasks.each do |task|
-          task_result = task.execute(context)
-          next unless breakpoints.include?(task_result.status)
-
-          throw!(task_result)
-        end
-      end
+      Pipeline.execute(self)
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -163,9 +163,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A framework that provides structured command execution, attribute management,
-  validation, coercion, callbacks, and workflow orchestration for building maintainable
-  business processes.
+description: CMDx is a framework for building maintainable business processes.
 email:
 - drexed@users.noreply.github.com
 executables: []
@@ -237,6 +235,7 @@ files:
 - lib/cmdx/deprecator.rb
 - lib/cmdx/errors.rb
 - lib/cmdx/exceptions.rb
+- lib/cmdx/executor.rb
 - lib/cmdx/faults.rb
 - lib/cmdx/freezer.rb
 - lib/cmdx/identifier.rb
@@ -250,6 +249,7 @@ files:
 - lib/cmdx/middlewares/correlate.rb
 - lib/cmdx/middlewares/runtime.rb
 - lib/cmdx/middlewares/timeout.rb
+- lib/cmdx/pipeline.rb
 - lib/cmdx/railtie.rb
 - lib/cmdx/result.rb
 - lib/cmdx/task.rb
@@ -264,7 +264,6 @@ files:
 - lib/cmdx/validators/numeric.rb
 - lib/cmdx/validators/presence.rb
 - lib/cmdx/version.rb
-- lib/cmdx/worker.rb
 - lib/cmdx/workflow.rb
 - lib/generators/cmdx/install_generator.rb
 - lib/generators/cmdx/task_generator.rb