cmdx 1.0.0 → 1.1.0

data/docs/parameters/validations.md

@@ -4,6 +4,7 @@ Parameter values can be validated using built-in validators or custom validation
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Common Options](#common-options)
 - [Presence](#presence)
 - [Format](#format)
@@ -11,9 +12,14 @@ Parameter values can be validated using built-in validators or custom validation
 - [Inclusion](#inclusion)
 - [Length](#length)
 - [Numeric](#numeric)
-- [Custom](#custom)
 - [Validation Results](#validation-results)
-- [Internationalization (i18n)](#internationalization-i18n)
+
+## TLDR
+
+- **Built-in validators** - `presence`, `format`, `inclusion`, `exclusion`, `length`, `numeric`
+- **Common options** - All support `:allow_nil`, `:if`, `:unless`, `:message`
+- **Usage** - Add to parameter definitions: `required :email, presence: true, format: { with: /@/ }`
+- **Conditional** - Use `:if` and `:unless` for conditional validation
 
 ## Common Options
 
@@ -239,43 +245,6 @@ end
 | `:is_message`         | "must be %{is}" |
 | `:is_not_message`     | "must not be %{is_not}" |
 
-## Custom
-
-Validates using custom logic. Accepts any callable object (class, proc, lambda) implementing a `call` method that returns truthy for valid values.
-
-```ruby
-class EmailDomainValidator
-  def self.call(value, options)
-    allowed_domains = options.dig(:custom, :allowed_domains) || ['example.com']
-    domain = value.split('@').last
-    allowed_domains.include?(domain)
-  end
-end
-
-class CreateAccountTask < CMDx::Task
-  required :work_email, custom: {
-    validator: EmailDomainValidator,
-    allowed_domains: ['company.com', 'partner.org'],
-    message: "must be from an approved domain"
-  }
-
-  required :age, custom: {
-    validator: ->(value, options) { value.between?(18, 120) },
-    message: "must be a valid age"
-  }
-
-  def call
-    create_user_account
-  end
-end
-```
-
-**Options:**
-
-| Option       | Description |
-| ------------ | ----------- |
-| `:validator` | Callable object returning true/false. Receives value and options as parameters |
-
 ## Validation Results
 
 When validation fails, tasks enter a failed state with detailed error information:
@@ -303,34 +272,6 @@ result.metadata[:messages][:email]    #=> ["format is invalid"]
 result.metadata[:messages][:username] #=> ["cannot be empty"]
 ```
 
-## Internationalization (i18n)
-
-All validators support internationalization through Rails i18n. Customize error messages in your locale files:
-
-```yaml
-# config/locales/en.yml
-en:
-  cmdx:
-    validators:
-      presence: "is required"
-      format: "has invalid format"
-      inclusion:
-        of: "must be one of: %{values}"
-        in: "must be within %{min} and %{max}"
-      exclusion:
-        of: "must not be one of: %{values}"
-        in: "must not be within %{min} and %{max}"
-      length:
-        within: "must be between %{min} and %{max} characters"
-        min: "must be at least %{min} characters"
-        max: "must be at most %{max} characters"
-      numeric:
-        within: "must be between %{min} and %{max}"
-        min: "must be at least %{min}"
-        max: "must be at most %{max}"
-      custom: "is invalid"
-```
-
 ---
 
 - **Prev:** [Parameters - Coercions](coercions.md)

data/docs/testing.md

@@ -4,6 +4,7 @@ CMDx provides a comprehensive suite of custom RSpec matchers designed for expres
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [External Project Setup](#external-project-setup)
 - [Matcher Organization](#matcher-organization)
 - [Result Matchers](#result-matchers)
@@ -20,23 +21,31 @@ CMDx provides a comprehensive suite of custom RSpec matchers designed for expres
 - [Composable Testing](#composable-testing)
 - [Best Practices](#best-practices)
 
-## Using RSpec matchers
+## TLDR
+
+- **Custom matchers** - 40+ specialized RSpec matchers for testing CMDx tasks and results
+- **Setup** - Require `cmdx/rspec/matchers`
+- **Result matchers** - `be_successful_task`, `be_failed_task`, `be_skipped_task` with chainable metadata
+- **Task matchers** - Parameter validation, lifecycle, exception handling, and configuration testing
+- **Composable** - Chain matchers for complex validation scenarios
+- **YARD documented** - Complete documentation with examples for all matchers
+
+## External Project Setup
 
 To use CMDx's custom matchers in an external RSpec-based project update your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
 
 ```ruby
-require "cmdx/rspec/result_matchers"
-require "cmdx/rspec/task_matchers"
+require "cmdx/rspec/matchers"
 ```
 
 ## Matcher Organization
 
 CMDx matchers are organized into two primary files with comprehensive YARD documentation:
 
-| File | Purpose | Matcher Count |
-|------|---------|---------------|
-| `result_matchers.rb` | Task execution outcomes and side effects | 25+ matchers |
-| `task_matchers.rb` | Task behavior, validation, and lifecycle | 15+ matchers |
+| Purpose | Matcher Count |
+|---------|---------------|
+| Task execution outcomes and side effects | 15+ matchers |
+| Task behavior, validation, and lifecycle | 5+ matchers |
 
 All matchers include:
 - Complete parameter descriptions
@@ -427,15 +436,15 @@ expect(SimpleTask).not_to have_middleware(ComplexMiddleware)
 
 ```ruby
 # Test setting presence
-expect(ConfiguredTask).to have_task_setting(:timeout)
-expect(CustomTask).to have_task_setting(:priority)
+expect(ConfiguredTask).to have_cmd_setting(:timeout)
+expect(CustomTask).to have_cmd_setting(:priority)
 
 # Test setting with specific value
-expect(TimedTask).to have_task_setting(:timeout, 30)
-expect(PriorityTask).to have_task_setting(:priority, "high")
+expect(TimedTask).to have_cmd_setting(:timeout, 30)
+expect(PriorityTask).to have_cmd_setting(:priority, "high")
 
 # Negated usage
-expect(SimpleTask).not_to have_task_setting(:complex_setting)
+expect(SimpleTask).not_to have_cmd_setting(:complex_setting)
 ```
 
 ## Composable Testing
@@ -546,5 +555,5 @@ end
 
 ---
 
-- **Prev:** [Logging](logging.md)
+- **Prev:** [Internationalization (i18n)](internationalization.md)
 - **Next:** [AI Prompts](ai_prompts.md)

data/docs/tips_and_tricks.md

@@ -4,6 +4,7 @@ This guide covers advanced patterns and optimization techniques for getting the
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Project Organization](#project-organization)
   - [Directory Structure](#directory-structure)
   - [Naming Conventions](#naming-conventions)
@@ -12,6 +13,14 @@ This guide covers advanced patterns and optimization techniques for getting the
 - [Monitoring and Observability](#monitoring-and-observability)
   - [ActiveRecord Query Tagging](#activerecord-query-tagging)
 
+## TLDR
+
+- **Organization** - Group commands by domain in `/app/commands` with descriptive subdirectories
+- **Naming** - Tasks use "Verb + Noun + Task", workflows use "Noun + Verb + Workflow"
+- **Parameter optimization** - Use `with_options` to reduce duplication in parameter definitions
+- **Monitoring** - Enable ActiveRecord query tagging for better debugging and observability
+- **Base classes** - Create `ApplicationTask` and `ApplicationWorkflow` for shared configuration
+
 ## Project Organization
 
 ### Directory Structure

data/docs/workflows.md

@@ -6,6 +6,7 @@ Workflows inherit from Task, gaining all task capabilities including callbacks,
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Basic Usage](#basic-usage)
 - [Task Declaration](#task-declaration)
 - [Context Propagation](#context-propagation)
@@ -21,6 +22,15 @@ Workflows inherit from Task, gaining all task capabilities including callbacks,
 - [Task Settings Integration](#task-settings-integration)
 - [Generator](#generator)
 
+## TLDR
+
+- **Purpose** - Orchestrate sequential execution of multiple tasks in linear pipeline
+- **Declaration** - Use `process` method to declare tasks in execution order
+- **Context sharing** - Context object shared across all tasks for data pipeline
+- **Conditional execution** - Support `:if` and `:unless` options for conditional tasks
+- **Halt behavior** - Configurable stopping on failed/skipped results (default: halt on failed only)
+- **No call method** - Workflows automatically provide execution logic, don't define `call`
+
 ## Basic Usage
 
 > [!WARNING]
@@ -143,12 +153,12 @@ end
 
 ### Class-Level Configuration
 
-Configure halt behavior for the entire workflow using `task_settings!`:
+Configure halt behavior for the entire workflow using `cmd_settings!`:
 
 ```ruby
 class CriticalDataProcessingWorkflow < CMDx::Workflow
   # Halt on both failed and skipped results
-  task_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  cmd_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
   process LoadCriticalDataTask
   process ValidateCriticalDataTask
@@ -156,7 +166,7 @@ end
 
 class OptionalDataProcessingWorkflow < CMDx::Workflow
   # Never halt, always continue
-  task_settings!(workflow_halt: [])
+  cmd_settings!(workflow_halt: [])
 
   process TryLoadDataTask
   process TryValidateDataTask
@@ -264,7 +274,7 @@ Workflows support all task settings and can be configured like regular tasks:
 ```ruby
 class PaymentProcessingWorkflow < CMDx::Workflow
   # Configure workflow-specific settings
-  task_settings!(
+  cmd_settings!(
     workflow_halt: [CMDx::Result::FAILED],
     log_level: :debug,
     tags: [:critical, :payment]

data/lib/cmdx/callback.rb

@@ -1,67 +1,47 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Base class for CMDx callbacks that provides lifecycle execution points.
+  # Base class for implementing callback functionality in task execution.
   #
-  # Callback components can wrap or observe task execution at specific lifecycle
-  # points like before validation, on success, after execution, etc.
-  # Each callback must implement the `call` method which receives the
-  # task instance and callback context.
-  #
-  # @example Basic callback implementation
-  #   class LoggingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       puts "Executing #{callback_type} callback for #{task.class.name}"
-  #       task.logger.info("Callback executed: #{callback_type}")
-  #     end
-  #   end
-  #
-  # @example Callback with initialization parameters
-  #   class NotificationCallback < CMDx::Callback
-  #     def initialize(channels)
-  #       @channels = channels
-  #     end
-  #
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_success
-  #
-  #       @channels.each do |channel|
-  #         NotificationService.send(channel, "Task #{task.class.name} completed")
-  #       end
-  #     end
-  #   end
-  #
-  # @example Conditional callback execution
-  #   class ErrorReportingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_failure
-  #       return unless task.result.failed?
-  #
-  #       ErrorReporter.notify(
-  #         task.errors.full_messages.join(", "),
-  #         context: task.context.to_h
-  #       )
-  #     end
-  #   end
-  #
-  # @see CallbackRegistry Callback management
-  # @see Task Callback integration
-  # @since 1.0.0
+  # Callbacks are executed at specific points during task lifecycle to
+  # provide hooks for custom behavior, logging, validation, or cleanup.
+  # All callback implementations must inherit from this class and implement
+  # the abstract call method.
   class Callback
 
-    ##
-    # Executes the callback logic.
+    # Executes a callback by creating a new instance and calling it.
+    #
+    # @param task [Task] the task instance executing the callback
+    # @param type [Symbol] the callback type identifier
+    #
+    # @return [Object] the result of the callback execution
+    #
+    # @raise [UndefinedCallError] when the callback subclass doesn't implement call
+    #
+    # @example Execute a callback on a task
+    #   MyCallback.call(task, :before)
+    def self.call(task, type)
+      new.call(task, type)
+    end
+
+    # Abstract method that must be implemented by callback subclasses.
+    #
+    # This method contains the actual callback logic to be executed.
+    # Subclasses must override this method to provide their specific
+    # callback implementation.
+    #
+    # @param _task [Task] the task instance executing the callback
+    # @param _type [Symbol] the callback type identifier
+    #
+    # @return [Object] the result of the callback execution
     #
-    # This method must be implemented by subclasses to define the callback
-    # behavior. The method receives the task instance and the callback type
-    # being executed.
+    # @raise [UndefinedCallError] always raised in the base class
     #
-    # @param task [Task] the task instance being executed
-    # @param callback_type [Symbol] the type of callback being executed
-    # @return [void]
-    # @abstract Subclasses must implement this method
-    def call(_task, _callback_type)
+    # @example Implement in a subclass
+    #   def call(task, type)
+    #     puts "Executing #{type} callback for #{task.class.name}"
+    #   end
+    def call(_task, _type)
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 

data/lib/cmdx/callback_registry.rb

@@ -1,106 +1,115 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # The CallbackRegistry collection provides a lifecycle callback system that executes
-  # registered callbacks at specific points during task execution. Callbacks can be
-  # conditionally executed based on task state and support both method references
-  # and callable objects.
+  # Registry for managing callback definitions and execution within tasks.
   #
-  # The CallbackRegistry collection extends Hash to provide specialized functionality for
-  # managing collections of callback definitions within CMDx tasks. It handles
-  # callback registration, conditional execution, and inspection.
-  #
-  # @example Basic callback usage
-  #   callback_registry = CallbackRegistry.new
-  #   callback_registry.register(:before_validation, :check_permissions)
-  #   callback_registry.register(:on_success, :log_success, if: :important?)
-  #   callback_registry.register(:on_failure, proc { alert_admin }, unless: :test_env?)
-  #
-  #   callback_registry.call(task, :before_validation)
-  #
-  # @example Hash-like operations
-  #   callback_registry[:before_validation] = [[:check_permissions, {}]]
-  #   callback_registry.keys  # => [:before_validation]
-  #   callback_registry.empty?  # => false
-  #   callback_registry.each { |callback_name, callbacks| puts "#{callback_name}: #{callbacks}" }
-  #
-  # @see Callback Base callback execution class
-  # @see Task Task lifecycle callbacks
-  # @since 1.0.0
-  class CallbackRegistry < Hash
+  # This registry handles the registration and execution of callbacks at various
+  # points in the task lifecycle, including validation, execution, and outcome
+  # handling phases.
+  class CallbackRegistry
+
+    TYPES = [
+      :before_validation,
+      :after_validation,
+      :before_execution,
+      :after_execution,
+      :on_executed,
+      :on_good,
+      :on_bad,
+      *Result::STATUSES.map { |s| :"on_#{s}" },
+      *Result::STATES.map { |s| :"on_#{s}" }
+    ].freeze
 
-    ##
-    # Initializes a new CallbackRegistry.
+    # The internal hash storing callback definitions.
     #
-    # @param registry [CallbackRegistry, Hash, nil] Optional registry to copy from
+    # @return [Hash] hash containing callback type keys and callback definition arrays
+    attr_reader :registry
+
+    # Initializes a new callback registry.
     #
-    # @example Initialize empty registry
-    #   registry = CallbackRegistry.new
+    # @param registry [Hash] initial registry hash with callback definitions
     #
-    # @example Initialize with existing registry
-    #   global_callbacks = CallbackRegistry.new
-    #   task_callbacks = CallbackRegistry.new(global_callbacks)
-    def initialize(registry = nil)
-      super()
-
-      registry&.each do |callback_type, callback_definitions|
-        self[callback_type] = callback_definitions.dup
-      end
+    # @return [CallbackRegistry] a new callback registry instance
+    #
+    # @example Creating an empty registry
+    #   CallbackRegistry.new
+    #
+    # @example Creating a registry with initial callbacks
+    #   CallbackRegistry.new(before_execution: [[:my_callback, {}]])
+    def initialize(registry = {})
+      @registry = registry.to_h
     end
 
-    # Registers a callback for the given callback type.
+    # Registers one or more callbacks for a specific type.
     #
-    # @param callback [Symbol] The callback type (e.g., :before_validation, :on_success)
-    # @param callables [Array<Symbol, Proc, #call>] Methods or callables to execute
-    # @param options [Hash] Conditions for callback execution
-    # @option options [Symbol, Proc, #call] :if condition that must be truthy
-    # @option options [Symbol, Proc, #call] :unless condition that must be falsy
-    # @param block [Proc] Block to execute as part of the callback
-    # @return [CallbackRegistry] self for method chaining
+    # @param type [Symbol] the callback type to register
+    # @param callables [Array<Object>] callable objects to register
+    # @param options [Hash] options for conditional callback execution
+    # @param block [Proc] optional block to register as a callback
     #
-    # @example Register method callback
-    #   registry.register(:before_validation, :check_permissions)
+    # @return [CallbackRegistry] returns self for method chaining
     #
-    # @example Register conditional callback
-    #   registry.register(:on_failure, :alert_admin, if: :critical?)
+    # @example Registering a symbol callback
+    #   registry.register(:before_execution, :setup_database)
     #
-    # @example Register proc callback
-    #   registry.register(:on_success, proc { log_completion })
-    def register(callback, *callables, **options, &block)
+    # @example Registering a Proc callback
+    #   registry.register(:on_good, ->(task) { puts "Task completed: #{task.name}" })
+    #
+    # @example Registering a Callback class
+    #   registry.register(:after_validation, NotificationCallback)
+    #
+    # @example Registering multiple callbacks with options
+    #   registry.register(:on_good, :send_notification, :log_success, if: -> { Rails.env.production? })
+    #
+    # @example Registering a block callback
+    #   registry.register(:after_validation) { |task| puts "Validation complete" }
+    def register(type, *callables, **options, &block)
       callables << block if block_given?
-      (self[callback] ||= []).push([callables, options]).uniq!
+      (registry[type] ||= []).push([callables, options]).uniq!
       self
     end
 
-    # Executes all callbacks registered for a specific callback type on the given task.
-    # Each callback is evaluated for its conditions (if/unless) before execution.
+    # Executes all registered callbacks for a specific type.
+    #
+    # @param task [Task] the task instance to execute callbacks on
+    # @param type [Symbol] the callback type to execute
     #
-    # @param task [Task] The task instance to execute callbacks on
-    # @param callback [Symbol] The callback type to execute (e.g., :before_validation, :on_success)
     # @return [void]
     #
-    # @example Execute callbacks
+    # @raise [UnknownCallbackError] when the callback type is not recognized
+    #
+    # @example Executing before_validation callbacks
     #   registry.call(task, :before_validation)
     #
-    # @example Execute conditional callbacks
-    #   # Only executes if task.critical? returns true
-    #   registry.call(task, :on_failure) # where registry has on_failure :alert, if: :critical?
-    def call(task, callback)
-      return unless key?(callback)
+    # @example Executing outcome callbacks
+    #   registry.call(task, :on_good)
+    def call(task, type)
+      raise UnknownCallbackError, "unknown callback #{type}" unless TYPES.include?(type)
 
-      Array(self[callback]).each do |callables, options|
-        next unless task.__cmdx_eval(options)
+      Array(registry[type]).each do |callables, options|
+        next unless task.cmdx_eval(options)
 
-        Array(callables).each do |c|
-          if c.is_a?(Callback)
-            c.call(task, callback)
+        Array(callables).each do |callable|
+          case callable
+          when Symbol, String, Proc
+            task.cmdx_try(callable)
           else
-            task.__cmdx_try(c)
+            callable.call(task)
           end
         end
       end
     end
 
+    # Returns a hash representation of the registry.
+    #
+    # @return [Hash] a deep copy of the registry hash
+    #
+    # @example Getting registry contents
+    #   registry.to_h
+    #   # => { before_execution: [[:setup, {}]], on_good: [[:notify, { if: -> { true } }]] }
+    def to_h
+      registry.transform_values(&:dup)
+    end
+
   end
 end