cmdx 1.6.2 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8b62e944f3c8fdb0f69dba9e33e3aad9f62d90b6a7487b18e9c0104392c4a8d
-  data.tar.gz: a032133acd6f0e6d5999d8336a179df495fd4460fbf632385a8dbcd4ee31fd66
+  metadata.gz: 9bbf1d8db7665b82da9af2dd5e017977945bbd550700177368b1363a8e63275e
+  data.tar.gz: 0f1720432a999ff31399d67c602e5277ee8cb1a8062117165c425a39233eb81c
 SHA512:
-  metadata.gz: 05a82e75e96e364df809f158a791a015ce22cff03b10f1ae255ba2e116d602fadd741d0a82638c5feabcbbdf96e3e61e9a9ae54be8c3220253d542f0d8a303d5
-  data.tar.gz: 881fe8149e8a029fbb79a1164faced4406f4f28d1e206659e09ee460129d9246a9a074aef76a61cbd94a38ed4f1a39612753a6842460e3a3827b3bd1c5301cc1
+  metadata.gz: 144c01abf663258e34b40eaa9e1deba09b59347b97773237f9bd84f5d82474825aca38f21b6ad0c052f1b058f6a5550e24ef8f3598da4cdecad94da1689bea5c
+  data.tar.gz: 25220966f85607b73740107b5af5da7889e75592055ad17156bc48f157550e2d030f542b7f279ec731cbb78ef732be1c6507b8e448a97a8324749d4746549d95

data/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [1.7.1] - 2025-08-26
+
+### Added
+- Yield result if block given to `execute` and `execute!` methods
+
+## [1.7.0] - 2025-08-25
+
+### Added
+- Workflow generator
+
+### Changes
+- Port over `cmdx-parallel` changes
+- Port over `cmdx-i18n` changes
+
 ## [1.6.2] - 2025-08-24
 
 ### Changes

data/LLM.md

@@ -1251,6 +1251,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.
@@ -2830,8 +2846,109 @@ I18n.with_locale(:fr) do
 end
 ```
 
-> [!TIP]
-> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+## Configuration
+
+Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+
+### Local Copies
+
+Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+
+```bash
+rails generate cmdx:locale [LOCALE]
+
+# Eg: generate french locale
+rails generate cmdx:locale fr
+```
+
+### Available Locales
+
+- af - Afrikaans
+- ar - Arabic
+- az - Azerbaijani
+- be - Belarusian
+- bg - Bulgarian
+- bn - Bengali
+- bs - Bosnian
+- ca - Catalan
+- cnr - Montenegrin
+- cs - Czech
+- cy - Welsh
+- da - Danish
+- de - German
+- dz - Dzongkha
+- el - Greek
+- en - English
+- eo - Esperanto
+- es - Spanish
+- et - Estonian
+- eu - Basque
+- fa - Persian
+- fi - Finnish
+- fr - French
+- fy - Western Frisian
+- gd - Scottish Gaelic
+- gl - Galician
+- he - Hebrew
+- hi - Hindi
+- hr - Croatian
+- hu - Hungarian
+- hy - Armenian
+- id - Indonesian
+- is - Icelandic
+- it - Italian
+- ja - Japanese
+- ka - Georgian
+- kk - Kazakh
+- km - Khmer
+- kn - Kannada
+- ko - Korean
+- lb - Luxembourgish
+- lo - Lao
+- lt - Lithuanian
+- lv - Latvian
+- mg - Malagasy
+- mk - Macedonian
+- ml - Malayalam
+- mn - Mongolian
+- mr-IN - Marathi (India)
+- ms - Malay
+- nb - Norwegian Bokmål
+- ne - Nepali
+- nl - Dutch
+- nn - Norwegian Nynorsk
+- oc - Occitan
+- or - Odia
+- pa - Punjabi
+- pl - Polish
+- pt - Portuguese
+- rm - Romansh
+- ro - Romanian
+- ru - Russian
+- sc - Sardinian
+- sk - Slovak
+- sl - Slovenian
+- sq - Albanian
+- sr - Serbian
+- st - Southern Sotho
+- sv - Swedish
+- sw - Swahili
+- ta - Tamil
+- te - Telugu
+- th - Thai
+- tl - Tagalog
+- tr - Turkish
+- tt - Tatar
+- ug - Uyghur
+- uk - Ukrainian
+- ur - Urdu
+- uz - Uzbek
+- vi - Vietnamese
+- wo - Wolof
+- zh-CN - Chinese (Simplified)
+- zh-HK - Chinese (Hong Kong)
+- zh-TW - Chinese (Traditional)
+- zh-YUE - Chinese (Yue)
 
 ---
 
@@ -3166,6 +3283,52 @@ class CompleteEmailWorkflow < CMDx::Task
 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.
+
+> [!IMPORTANT]
+> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+
+```ruby
+class SendWelcomeNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  # Default options (dynamically calculated to available processors)
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
+
+  # Fix number of threads
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
+
+  # Fix number of forked processes
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
+
+  # NOTE: Reactors are not supported
+end
+```
+
+## Task Generator
+
+Generate new CMDx workflow tasks quickly using the built-in generator:
+
+```bash
+rails generate cmdx:workflow SendNotifications
+```
+
+This creates a new workflow task file with the basic structure:
+
+```ruby
+# app/tasks/send_notifications.rb
+class SendNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  tasks Task1, Task2
+end
+```
+
+> [!TIP]
+> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
+
 ---
 
 url: https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md

data/docs/internationalization.md

@@ -5,6 +5,9 @@ CMDx provides comprehensive internationalization support for all error messages,
 ## Table of Contents
 
 - [Localization](#localization)
+- [Configuration](#configuration)
+  - [Local Copies](#local-copies)
+  - [Available Locales](#available-locales)
 
 ## Localization
 
@@ -25,8 +28,109 @@ I18n.with_locale(:fr) do
 end
 ```
 
-> [!TIP]
-> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+## Configuration
+
+Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+
+### Local Copies
+
+Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+
+```bash
+rails generate cmdx:locale [LOCALE]
+
+# Eg: generate french locale
+rails generate cmdx:locale fr
+```
+
+### Available Locales
+
+- af - Afrikaans
+- ar - Arabic
+- az - Azerbaijani
+- be - Belarusian
+- bg - Bulgarian
+- bn - Bengali
+- bs - Bosnian
+- ca - Catalan
+- cnr - Montenegrin
+- cs - Czech
+- cy - Welsh
+- da - Danish
+- de - German
+- dz - Dzongkha
+- el - Greek
+- en - English
+- eo - Esperanto
+- es - Spanish
+- et - Estonian
+- eu - Basque
+- fa - Persian
+- fi - Finnish
+- fr - French
+- fy - Western Frisian
+- gd - Scottish Gaelic
+- gl - Galician
+- he - Hebrew
+- hi - Hindi
+- hr - Croatian
+- hu - Hungarian
+- hy - Armenian
+- id - Indonesian
+- is - Icelandic
+- it - Italian
+- ja - Japanese
+- ka - Georgian
+- kk - Kazakh
+- km - Khmer
+- kn - Kannada
+- ko - Korean
+- lb - Luxembourgish
+- lo - Lao
+- lt - Lithuanian
+- lv - Latvian
+- mg - Malagasy
+- mk - Macedonian
+- ml - Malayalam
+- mn - Mongolian
+- mr-IN - Marathi (India)
+- ms - Malay
+- nb - Norwegian Bokmål
+- ne - Nepali
+- nl - Dutch
+- nn - Norwegian Nynorsk
+- oc - Occitan
+- or - Odia
+- pa - Punjabi
+- pl - Polish
+- pt - Portuguese
+- rm - Romansh
+- ro - Romanian
+- ru - Russian
+- sc - Sardinian
+- sk - Slovak
+- sl - Slovenian
+- sq - Albanian
+- sr - Serbian
+- st - Southern Sotho
+- sv - Swedish
+- sw - Swahili
+- ta - Tamil
+- te - Telugu
+- th - Thai
+- tl - Tagalog
+- tr - Turkish
+- tt - Tatar
+- ug - Uyghur
+- uk - Ukrainian
+- ur - Urdu
+- uz - Uzbek
+- vi - Vietnamese
+- wo - Wolof
+- zh-CN - Chinese (Simplified)
+- zh-HK - Chinese (Hong Kong)
+- zh-TW - Chinese (Traditional)
+- zh-YUE - Chinese (Yue)
 
 ---
 

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/docs/workflows.md

@@ -12,6 +12,8 @@ Workflow orchestrates sequential execution of multiple tasks in a linear pipelin
   - [Task Configuration](#task-configuration)
   - [Group Configuration](#group-configuration)
 - [Nested Workflows](#nested-workflows)
+- [Parallel Execution](#parallel-execution)
+- [Task Generator](#task-generator)
 
 ## Declarations
 
@@ -187,6 +189,52 @@ class CompleteEmailWorkflow < CMDx::Task
 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.
+
+> [!IMPORTANT]
+> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+
+```ruby
+class SendWelcomeNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  # Default options (dynamically calculated to available processors)
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
+
+  # Fix number of threads
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
+
+  # Fix number of forked processes
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
+
+  # NOTE: Reactors are not supported
+end
+```
+
+## Task Generator
+
+Generate new CMDx workflow tasks quickly using the built-in generator:
+
+```bash
+rails generate cmdx:workflow SendNotifications
+```
+
+This creates a new workflow task file with the basic structure:
+
+```ruby
+# app/tasks/send_notifications.rb
+class SendNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  tasks Task1, Task2
+end
+```
+
+> [!TIP]
+> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
+
 ---
 
 - **Prev:** [Deprecation](deprecation.md)

data/lib/cmdx/pipeline.rb

@@ -55,23 +55,22 @@ module CMDx
 
     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.
+    # Executes a group of tasks using the specified execution strategy.
     #
-    # @param group [ExecutionGroup] The group of tasks to execute
-    # @param breakpoints [Array<String>] Breakpoint statuses that trigger workflow interruption
+    # @param group [CMDx::Group] The task group to execute
+    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
+    # @option group.options [Symbol, String] :strategy Execution strategy (:sequential, :parallel, or nil for default)
     #
     # @return [void]
     #
     # @example
-    #   def execute_group_tasks(group, breakpoints)
-    #     # Custom parallel execution strategy
-    #     group.tasks.map { |task| Thread.new { task.execute(workflow.context) } }
-    #   end
+    #   execute_group_tasks(group, ["failed", "skipped"])
     def execute_group_tasks(group, breakpoints)
-      # NOTE: Override this method to introduce alternative execution strategies
-      execute_tasks_in_sequence(group, breakpoints)
+      case strategy = group.options[:strategy]
+      when NilClass, /sequential/ then execute_tasks_in_sequence(group, breakpoints)
+      when /parallel/ then execute_tasks_in_parallel(group, breakpoints)
+      else raise "unknown execution strategy #{strategy.inspect}"
+      end
     end
 
     # Executes tasks sequentially within a group, checking breakpoints after each task.
@@ -95,5 +94,38 @@ module CMDx
       end
     end
 
+    # Executes tasks in parallel using the parallel gem.
+    #
+    # @param group [CMDx::Group] The task group to execute in parallel
+    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
+    # @option group.options [Integer] :in_threads Number of threads to use
+    # @option group.options [Integer] :in_processes Number of processes to use
+    #
+    # @return [void]
+    #
+    # @raise [HaltError] When a task result status matches a breakpoint
+    #
+    # @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)
+
+      parallel_options = group.options.slice(:in_threads, :in_processes)
+      throwable_result = nil
+
+      ::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
+      end
+
+      return if throwable_result.nil?
+
+      workflow.throw!(throwable_result)
+    end
+
   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.6.2"
+  VERSION = "1.7.1"
 
 end

data/lib/cmdx.rb

@@ -48,7 +48,9 @@ require_relative "cmdx/faults"
 # Conditionally load Rails components if Rails is available
 if defined?(Rails::Generators)
   require_relative "generators/cmdx/install_generator"
+  require_relative "generators/cmdx/locale_generator"
   require_relative "generators/cmdx/task_generator"
+  require_relative "generators/cmdx/workflow_generator"
 end
 
 # Load the Railtie last after everything else is required so we don't

data/lib/generators/cmdx/locale_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cmdx
+  # Generates CMDx locale files for Rails applications
+  #
+  # Rails generator that copies CMDx locale files into the application's
+  # config/locales directory. This allows applications to customize and extend
+  # the default CMDx locale files.
+  class LocaleGenerator < Rails::Generators::Base
+
+    source_root File.expand_path("../../locales", __dir__)
+
+    desc "Copies the locale with the given alpha-2 code"
+
+    argument :locale, type: :string, default: "en", banner: "locale: en, es, fr, etc"
+
+    # Copies the locale template to the Rails application
+    #
+    # Copies the specified locale file from the gem's locales directory to the
+    # application's config/locales directory. If the locale file doesn't exist
+    # in the gem, the generator will fail gracefully.
+    #
+    # @return [void]
+    #
+    # @example
+    #   # Copy default (English) locale file
+    #   rails generate cmdx:locale
+    #   # => Creates config/locales/en.yml
+    #
+    #   # Copy Spanish locale file
+    #   rails generate cmdx:locale es
+    #   # => Creates config/locales/es.yml
+    #
+    def copy_locale_files
+      copy_file("#{locale}.yml", "config/locales/#{locale}.yml")
+    end
+
+  end
+end

data/lib/generators/cmdx/templates/workflow.rb.tt

@@ -0,0 +1,8 @@
+<% module_namespacing do -%>
+  class <%= class_name %> < <%= parent_class_name %>
+    include CMDx::Workflow
+
+    tasks Task1, Task2
+    # Docs: https://github.com/drexed/cmdx/docs/workflows.md
+  end
+<% end -%>

data/lib/generators/cmdx/workflow_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Cmdx
+  # Generates CMDx workflow files for Rails applications
+  #
+  # This generator creates task classes that inherit from either ApplicationTask
+  # (if defined) or CMDx::Task. It generates the task file in the standard
+  # Rails tasks directory structure.
+  class WorkflowGenerator < Rails::Generators::NamedBase
+
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates a workflow with the given NAME"
+
+    # Copies the task template to the Rails application
+    #
+    # Creates a new task file at `app/tasks/[class_path]/[file_name].rb` using
+    # the task template. The file is placed in the standard Rails tasks directory
+    # structure, maintaining proper namespacing if the task is nested.
+    #
+    # @return [void]
+    #
+    # @example Basic usage
+    #   rails generate cmdx:workflow SendNotifications
+    #   # => Creates app/tasks/send_notifications.rb
+    #
+    # @example Nested task
+    #   rails generate cmdx:workflow Admin::SendNotifications
+    #   # => Creates app/tasks/admin/send_notifications.rb
+    def copy_files
+      path = File.join("app/tasks", class_path, "#{file_name}.rb")
+      template("workflow.rb.tt", path)
+    end
+
+    private
+
+    # Determines the appropriate parent class name for the generated task
+    #
+    # Attempts to use ApplicationTask if it exists in the application, otherwise
+    # falls back to CMDx::Task. This allows applications to define their own
+    # base task class while maintaining compatibility.
+    #
+    # @return [Class] The parent class for the generated task
+    #
+    # @example
+    #   parent_class_name # => ApplicationTask
+    #
+    # @example Fallback behavior
+    #   parent_class_name # => CMDx::Task
+    def parent_class_name
+      ApplicationTask
+    rescue NameError
+      CMDx::Task
+    end
+
+  end
+end