cmdx 1.6.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8b62e944f3c8fdb0f69dba9e33e3aad9f62d90b6a7487b18e9c0104392c4a8d
-  data.tar.gz: a032133acd6f0e6d5999d8336a179df495fd4460fbf632385a8dbcd4ee31fd66
+  metadata.gz: 8483d78b67a6dfffa6721b39e623ac08d57d443b499287891bfb9c6e06422c89
+  data.tar.gz: 02cb722299d6a97fb4e2d07a84880c7374a8c17b691f42bee995bd4f3ea698ab
 SHA512:
-  metadata.gz: 05a82e75e96e364df809f158a791a015ce22cff03b10f1ae255ba2e116d602fadd741d0a82638c5feabcbbdf96e3e61e9a9ae54be8c3220253d542f0d8a303d5
-  data.tar.gz: 881fe8149e8a029fbb79a1164faced4406f4f28d1e206659e09ee460129d9246a9a074aef76a61cbd94a38ed4f1a39612753a6842460e3a3827b3bd1c5301cc1
+  metadata.gz: b6600b6d617c11a3ec3b66367a7fa309e191bd2d1f20a3fb1a538565a0c2b45e05f8093f2c3e07edbb155e308e6c90c486f069db171aac68e8658bbe85bd4b34
+  data.tar.gz: 6ad4a1348066d3aa4d0ed2733fc88f94af293835cc970be5986f3c002cf3b3615f474bff774a2b48f7e043920ca01b5f278cd26850b5b4827a70d2a4b0e6ab50

data/CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [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

@@ -2830,8 +2830,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 +3267,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/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/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.6.2"
+  VERSION = "1.7.0"
 
 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

data/lib/locales/af.yml

@@ -0,0 +1,49 @@
+af:
+  cmdx:
+    attributes:
+      required: "moet toeganklik wees via die bron"
+      undefined: "delegeer na ongedefinieerde metode %{method}"
+    coercions:
+      into_a: "kon nie na %{type} omskep word nie"
+      into_an: "kon nie na %{type} omskep word nie"
+      into_any: "kon nie na een van: %{types} omskep word nie"
+      unknown: "onbekende %{type} omskep tipe"
+    faults:
+      unspecified: "geen rede gegee nie"
+    types:
+      array: "skikking"
+      big_decimal: "groot desimale"
+      boolean: "booleaanse"
+      complex: "kompleks"
+      date_time: "datum en tyd"
+      date: "datum"
+      float: "drywende punt"
+      hash: "hash"
+      integer: "heelgetal"
+      rational: "rasionaal"
+      string: "string"
+      symbol: "simbool"
+      time: "tyd"
+    validators:
+      exclusion:
+        of: "moet nie een van wees nie: %{values}"
+        within: "moet nie binne %{min} en %{max} wees nie"
+      format: "is 'n ongeldige formaat"
+      inclusion:
+        of: "moet een van wees: %{values}"
+        within: "moet binne %{min} en %{max} wees"
+      length:
+        is: "lengte moet %{is} wees"
+        is_not: "lengte moet nie %{is_not} wees nie"
+        min: "lengte moet ten minste %{min} wees"
+        max: "lengte kan maksimum %{max} wees"
+        not_within: "lengte moet nie binne %{min} en %{max} wees nie"
+        within: "lengte moet binne %{min} en %{max} wees"
+      numeric:
+        is: "moet %{is} wees"
+        is_not: "moet nie %{is_not} wees nie"
+        min: "moet ten minste %{min} wees"
+        max: "kan maksimum %{max} wees"
+        not_within: "moet nie binne %{min} en %{max} wees nie"
+        within: "moet binne %{min} en %{max} wees"
+      presence: "kan nie leeg wees nie"

data/lib/locales/ar.yml

@@ -0,0 +1,49 @@
+ar:
+  cmdx:
+    attributes:
+      required: "يجب أن يكون قابلاً للوصول عبر المصدر"
+      undefined: "يفوض إلى طريقة غير معرفة %{method}"
+    coercions:
+      into_a: "لا يمكن تحويله إلى %{type}"
+      into_an: "لا يمكن تحويله إلى %{type}"
+      into_any: "لا يمكن تحويله إلى واحد من: %{types}"
+      unknown: "نوع تحويل %{type} غير معروف"
+    faults:
+      unspecified: "لم يتم تقديم سبب"
+    types:
+      array: "مصفوفة"
+      big_decimal: "عدد عشري كبير"
+      boolean: "منطقي"
+      complex: "مركب"
+      date_time: "التاريخ والوقت"
+      date: "التاريخ"
+      float: "رقم عشري"
+      hash: "جدول تجزئة"
+      integer: "عدد صحيح"
+      rational: "عدد نسبي"
+      string: "سلسلة نصية"
+      symbol: "رمز"
+      time: "الوقت"
+    validators:
+      exclusion:
+        of: "يجب ألا يكون واحداً من: %{values}"
+        within: "يجب ألا يكون بين %{min} و %{max}"
+      format: "تنسيق غير صالح"
+      inclusion:
+        of: "يجب أن يكون واحداً من: %{values}"
+        within: "يجب أن يكون بين %{min} و %{max}"
+      length:
+        is: "يجب أن يكون الطول %{is}"
+        is_not: "يجب ألا يكون الطول %{is_not}"
+        min: "يجب أن يكون الطول على الأقل %{min}"
+        max: "يجب أن يكون الطول على الأكثر %{max}"
+        not_within: "يجب ألا يكون الطول بين %{min} و %{max}"
+        within: "يجب أن يكون الطول بين %{min} و %{max}"
+      numeric:
+        is: "يجب أن يكون %{is}"
+        is_not: "يجب ألا يكون %{is_not}"
+        min: "يجب أن يكون على الأقل %{min}"
+        max: "يجب أن يكون على الأكثر %{max}"
+        not_within: "يجب ألا يكون بين %{min} و %{max}"
+        within: "يجب أن يكون بين %{min} و %{max}"
+      presence: "لا يمكن أن يكون فارغاً"