cmdx 1.1.0 → 1.1.1

data/lib/cmdx/validators/numeric.rb

@@ -40,7 +40,7 @@ module CMDx
       #
       # @example Range validation
       #   Validators::Numeric.call(5, numeric: { within: 1..10 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Range exclusion
       #   Validators::Numeric.call(5, numeric: { not_within: 1..10 })
@@ -48,7 +48,7 @@ module CMDx
       #
       # @example Min/max validation
       #   Validators::Numeric.call(15, numeric: { min: 10, max: 20 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Minimum value validation
       #   Validators::Numeric.call(5, numeric: { min: 10 })
@@ -56,7 +56,7 @@ module CMDx
       #
       # @example Exact value validation
       #   Validators::Numeric.call(42, numeric: { is: 42 })
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Custom error message
       #   Validators::Numeric.call(5, numeric: { min: 10, message: "Age must be at least %{min}" })

data/lib/cmdx/validators/presence.rb

@@ -23,7 +23,7 @@ module CMDx
       #
       # @example Validating a non-empty string
       #   Validators::Presence.call("hello", presence: {})
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Validating an empty string
       #   Validators::Presence.call("", presence: {})
@@ -35,7 +35,7 @@ module CMDx
       #
       # @example Validating a non-empty array
       #   Validators::Presence.call([1, 2, 3], presence: {})
-      #   # => nil (no error raised)
+      #   #=> nil (no error raised)
       #
       # @example Validating an empty array
       #   Validators::Presence.call([], presence: {})

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 
 end

data/lib/cmdx/workflow.rb

@@ -1,63 +1,86 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Orchestrates sequential execution of multiple tasks and workflows.
+  # Sequential task execution orchestration system for CMDx framework.
   #
-  # Workflow provides a way to chain multiple tasks together with conditional
-  # execution logic and halt behavior. Tasks are organized into groups that can
-  # be conditionally executed based on options, and execution can be halted
-  # based on task results.
+  # Workflow provides declarative composition of multiple tasks into linear pipelines
+  # with conditional execution, context propagation, and configurable halt behavior.
+  # Workflows inherit from Task, gaining all task capabilities including callbacks,
+  # parameter validation, result tracking, and configuration while coordinating
+  # other tasks rather than implementing business logic directly.
   class Workflow < Task
 
-    # Container for holding a group of tasks and their execution options.
+    # Data structure containing a group of tasks and their execution options.
     #
     # @!attribute [r] tasks
-    #   @return [Array<Task>] the tasks in this group
+    #   @return [Array<Class>] array of Task or Workflow classes to execute
     # @!attribute [r] options
-    #   @return [Hash] the execution options for this group
+    #   @return [Hash] execution options including conditional and halt configuration
     Group = Struct.new(:tasks, :options)
 
     class << self
 
-      # Returns the collection of workflow groups defined for this workflow.
+      # Returns the array of workflow groups defined for this workflow class.
       #
-      # @return [Array<Group>] array of workflow groups to be executed
+      # Each group contains tasks and their execution options. Groups are processed
+      # sequentially during workflow execution, with each group's tasks executing
+      # in order unless halted by a result status.
+      #
+      # @return [Array<Group>] array of workflow groups containing tasks and options
       #
       # @example Access workflow groups
-      #   MyWorkflow.workflow_groups #=> [#<Group:...>, #<Group:...>]
+      #   class MyWorkflow < CMDx::Workflow
+      #     process TaskA, TaskB
+      #     process TaskC, if: :condition_met?
+      #   end
+      #
+      #   MyWorkflow.workflow_groups.size #=> 2
+      #   MyWorkflow.workflow_groups.first.tasks #=> [TaskA, TaskB]
       def workflow_groups
         @workflow_groups ||= []
       end
 
-      # Defines a group of tasks to be executed as part of this workflow.
+      # Declares a group of tasks to execute sequentially with optional conditions.
+      #
+      # Tasks are executed in the order specified, with shared context propagated
+      # between executions. Groups support conditional execution and configurable
+      # halt behavior to control workflow flow based on task results.
       #
-      # @param tasks [Array<Task>] tasks to include in this workflow group
-      # @param options [Hash] execution options for this group
-      # @option options [Symbol, Array<Symbol>] :workflow_halt status values that will halt workflow execution
-      # @option options [Proc] :if conditional proc that determines if this group should execute
-      # @option options [Proc] :unless conditional proc that determines if this group should be skipped
+      # @param tasks [Array<Class>] Task or Workflow classes to execute in sequence
+      # @param options [Hash] execution configuration options
+      #
+      # @option options [Proc, Symbol, String] :if condition that must be truthy for group execution
+      # @option options [Proc, Symbol, String] :unless condition that must be falsy for group execution
+      # @option options [String, Array<String>] :workflow_halt result statuses that halt workflow execution
       #
       # @return [void]
       #
-      # @raise [TypeError] if any task is not a Task or Workflow subclass
+      # @raise [TypeError] when tasks contain objects that are not Task or Workflow classes
       #
-      # @example Define a simple workflow group
-      #   MyWorkflow.process CreateUserTask, SendEmailTask
+      # @example Declare sequential tasks
+      #   class UserRegistrationWorkflow < CMDx::Workflow
+      #     process CreateUserTask, SendWelcomeEmailTask
+      #   end
       #
-      # @example Define a conditional workflow group
-      #   MyWorkflow.process NotifyAdminTask, if: ->(workflow) { workflow.context.admin.active? }
+      # @example Declare conditional task group
+      #   class OrderProcessingWorkflow < CMDx::Workflow
+      #     process ValidateOrderTask
+      #     process ChargePaymentTask, if: ->(workflow) { workflow.context.payment_required? }
+      #     process ShipOrderTask, unless: :digital_product?
+      #     process NotifyAdminTask, if: proc { context.admin.active? }
+      #   end
       #
-      # @example Define a workflow group with halt behavior
-      #   MyWorkflow.process ValidateInputTask, ProcessDataTask, workflow_halt: :failed
+      # @example Configure halt behavior per group
+      #   class DataProcessingWorkflow < CMDx::Workflow
+      #     process LoadDataTask, ValidateDataTask, workflow_halt: %w[failed skipped]
+      #     process OptionalCleanupTask, workflow_halt: []
+      #   end
       def process(*tasks, **options)
         workflow_groups << Group.new(
           tasks.flatten.map do |task|
-            unless task.is_a?(Class) && (task <= Task)
-              raise TypeError,
-                    "must be a Task or Workflow"
-            end
+            next task if task.is_a?(Class) && (task <= Task)
 
-            task
+            raise TypeError, "must be a Task or Workflow"
           end,
           options
         )
@@ -65,8 +88,6 @@ module CMDx
 
     end
 
-    # Executes all workflow groups in sequence.
-    #
     # Each group is evaluated for conditional execution, and if the group should
     # execute, all tasks in the group are called in sequence. If any task returns
     # a status that matches the workflow halt criteria, execution is halted and
@@ -76,9 +97,9 @@ module CMDx
     #
     # @raise [Fault] if a task fails and its status matches the workflow halt criteria
     #
-    # @example Execute workflow with halt on failure
+    # @example Execute workflow
     #   workflow = MyWorkflow.new(user_id: 123)
-    #   workflow.call # Executes all groups until halt condition is met
+    #   workflow.call
     def call
       self.class.workflow_groups.each do |group|
         next unless cmdx_eval(group.options)

data/lib/generators/cmdx/task_generator.rb

@@ -24,11 +24,11 @@ module Cmdx
     #
     # @example Generate a user task
     #   rails generate cmdx:task user
-    #   # => Creates app/cmds/user_task.rb
+    #   #=> Creates app/cmds/user_task.rb
     #
     # @example Generate a nested task
     #   rails generate cmdx:task admin/users
-    #   # => Creates app/cmds/admin/users_task.rb
+    #   #=> Creates app/cmds/admin/users_task.rb
     def copy_files
       name = file_name.sub(/_?task$/i, "")
       path = File.join("app/cmds", class_path, "#{name}_task.rb")
@@ -47,11 +47,11 @@ module Cmdx
     #
     # @example Class name without suffix
     #   # Given name: "User"
-    #   class_name # => "UserTask"
+    #   class_name #=> "UserTask"
     #
     # @example Class name with suffix
     #   # Given name: "UserTask"
-    #   class_name # => "UserTask"
+    #   class_name #=> "UserTask"
     def class_name
       @class_name ||= super.end_with?("Task") ? super : "#{super}Task"
     end
@@ -68,10 +68,10 @@ module Cmdx
     # @raise [StandardError] if neither ApplicationTask nor CMDx::Task are available
     #
     # @example With ApplicationTask defined
-    #   parent_class_name # => ApplicationTask
+    #   parent_class_name #=> ApplicationTask
     #
     # @example Without ApplicationTask
-    #   parent_class_name # => CMDx::Task
+    #   parent_class_name #=> CMDx::Task
     def parent_class_name
       ApplicationTask
     rescue StandardError

data/lib/generators/cmdx/workflow_generator.rb

@@ -26,11 +26,11 @@ module Cmdx
     #
     # @example Generate a user workflow
     #   rails generate cmdx:workflow user
-    #   # => Creates app/cmds/user_workflow.rb
+    #   #=> Creates app/cmds/user_workflow.rb
     #
     # @example Generate a nested workflow
     #   rails generate cmdx:workflow admin/users
-    #   # => Creates app/cmds/admin/users_workflow.rb
+    #   #=> Creates app/cmds/admin/users_workflow.rb
     def copy_files
       name = file_name.sub(/_?workflow$/i, "")
       path = File.join("app/cmds", class_path, "#{name}_workflow.rb")
@@ -49,11 +49,11 @@ module Cmdx
     #
     # @example Class name without suffix
     #   # Given name: "User"
-    #   class_name # => "UserWorkflow"
+    #   class_name #=> "UserWorkflow"
     #
     # @example Class name with suffix
     #   # Given name: "UserWorkflow"
-    #   class_name # => "UserWorkflow"
+    #   class_name #=> "UserWorkflow"
     def class_name
       @class_name ||= super.end_with?("Workflow") ? super : "#{super}Workflow"
     end
@@ -70,10 +70,10 @@ module Cmdx
     # @raise [StandardError] if neither ApplicationWorkflow nor CMDx::Workflow are available
     #
     # @example With ApplicationWorkflow defined
-    #   parent_class_name # => ApplicationWorkflow
+    #   parent_class_name #=> ApplicationWorkflow
     #
     # @example Without ApplicationWorkflow
-    #   parent_class_name # => CMDx::Workflow
+    #   parent_class_name #=> CMDx::Workflow
     def parent_class_name
       ApplicationWorkflow
     rescue StandardError

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Juan Gomez
@@ -186,6 +186,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".cursor/prompts/docs.md"
 - ".cursor/prompts/rspec.md"
 - ".cursor/prompts/yardoc.md"
 - ".cursor/rules/cursor-instructions.mdc"
@@ -204,6 +205,7 @@ files:
 - docs/basics/setup.md
 - docs/callbacks.md
 - docs/configuration.md
+- docs/deprecation.md
 - docs/getting_started.md
 - docs/internationalization.md
 - docs/interruptions/exceptions.md