cmdx 1.1.1 → 1.5.0

data/docs/getting_started.md

@@ -1,47 +1,25 @@
 # Getting Started
 
-CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic parameter validation, structured error handling, comprehensive logging, and intelligent execution flow control that scales from simple tasks to complex multi-step processes.
+CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic attribute validation, structured error handling, comprehensive logging, and intelligent execution flow control.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
 - [Installation](#installation)
-- [Quick Setup](#quick-setup)
-- [Execution](#execution)
-- [Result Handling](#result-handling)
-- [Exception Handling](#exception-handling)
-- [Building Workflows](#building-workflows)
-- [Code Generation](#code-generation)
-
-## TLDR
-
-```ruby
-# Installation
-gem 'cmdx'                    # Add to Gemfile
-rails g cmdx:install          # Generate config
-
-# Basic task
-class ProcessOrderTask < CMDx::Task
-  required :order_id, type: :integer
-  optional :send_email, type: :boolean, default: true
-
-  def call
-    context.order = Order.find(order_id)
-    fail!("Order canceled") if context.order.canceled?
-    skip!("Already processed") if context.order.completed?
-
-    context.order.update!(status: 'completed')
-  end
-end
-
-# Execution
-result = ProcessOrderTask.call(order_id: 123)     # Returns Result
-result = ProcessOrderTask.call!(order_id: 123)    # Raises on failure
-
-# Check outcomes
-result.success? && result.context.order          # Access data
-result.failed? && result.metadata[:reason]       # Error details
-```
+- [Configuration Hierarchy](#configuration-hierarchy)
+- [Global Configuration](#global-configuration)
+  - [Breakpoints](#breakpoints)
+  - [Logging](#logging)
+  - [Middlewares](#middlewares)
+  - [Callbacks](#callbacks)
+  - [Coercions](#coercions)
+  - [Validators](#validators)
+- [Task Configuration](#task-configuration)
+  - [Settings](#settings)
+  - [Registrations](#registrations)
+- [Configuration Management](#configuration-management)
+  - [Access](#access)
+  - [Resetting](#resetting)
+- [Task Generator](#task-generator)
 
 ## Installation
 
@@ -57,236 +35,268 @@ For Rails applications, generate the configuration:
 rails generate cmdx:install
 ```
 
-> [!NOTE]
-> This creates `config/initializers/cmdx.rb` with default settings for logging, error handling, and middleware configuration.
+This creates `config/initializers/cmdx.rb` file.
 
-## Quick Setup
+## Configuration Hierarchy
 
-> [!TIP]
-> Use **present tense verbs** for task names: `ProcessOrderTask`, `SendEmailTask`, `ValidatePaymentTask`
+CMDx follows a two-tier configuration hierarchy:
 
-```ruby
-class ProcessOrderTask < CMDx::Task
-  required :order_id, type: :integer
-  optional :send_email, type: :boolean, default: true
-
-  def call
-    context.order = Order.find(order_id)
-
-    if context.order.canceled?
-      fail!(reason: "Order canceled", canceled_at: context.order.canceled_at)
-    elsif context.order.completed?
-      skip!(reason: "Already processed")
-    else
-      context.order.update!(status: 'completed', completed_at: Time.now)
-      EmailService.send_confirmation(context.order) if send_email
-    end
-  end
-end
-```
+1. **Global Configuration**: Framework-wide defaults
+2. **Task Settings**: Class-level overrides via `settings`
 
-### Parameter Definition
+> [!IMPORTANT]
+> Task-level settings take precedence over global configuration. Settings are inherited from superclasses and can be overridden in subclasses.
 
-Parameters provide automatic type coercion and validation:
+## Global Configuration
 
-```ruby
-class CreateUserTask < CMDx::Task
-  required :email, type: :string
-  required :age, type: :integer
-  required :active, type: :boolean, default: true
-
-  optional :metadata, type: :hash, default: {}
-  optional :tags, type: :array, default: []
-
-  def call
-    context.user = User.create!(
-      email: email,
-      age: age,
-      active: active,
-      metadata: metadata,
-      tags: tags
-    )
-  end
-end
-```
+Global configuration settings apply to all tasks inherited from `CMDx::Task`.
+Globally these settings are initialized with sensible defaults.
 
-## Execution
+### Breakpoints
 
-Execute tasks using class methods that return result objects or raise exceptions:
+Breakpoints control when `execute!` raises faults.
 
 ```ruby
-# Safe execution - returns Result object
-result = ProcessOrderTask.call(order_id: 123)
-
-# Exception-based execution - raises on failure/skip
-result = ProcessOrderTask.call!(order_id: 123, send_email: false)
+CMDx.configure do |config|
+  config.task_breakpoints = "skipped"
+  config.workflow_breakpoints = ["skipped", "failed"]
+end
 ```
 
-> [!IMPORTANT]
-> Use `call` for conditional logic based on results, and `call!` for exception-based control flow where failures should halt execution.
+### Logging
 
-### Input Coercion
+```ruby
+CMDx.configure do |config|
+  config.logger = CustomLogger.new($stdout)
+end
+```
 
-Parameters automatically coerce string inputs to specified types:
+### Middlewares
 
 ```ruby
-# String inputs automatically converted
-ProcessOrderTask.call(
-  order_id: "123",      # → 123 (Integer)
-  send_email: "false"   # → false (Boolean)
-)
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, options)`)
+  config.middlewares.register CMDx::Middlewares::Timeout
+
+  # Via proc or lambda
+  config.middlewares.register proc { |task, options|
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = yield
+    end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    Rails.logger.debug { "task completed in #{((end_time - start_time) * 1000).round(2)}ms" }
+    result
+  }
+
+  # With options
+  config.middlewares.register AuditTrailMiddleware, service_name: "document_processor"
+
+  # Remove middleware
+  config.middlewares.deregister CMDx::Middlewares::Timeout
+end
 ```
 
-## Result Handling
+> [!NOTE]
+> Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
 
-Results provide comprehensive execution information including status, context data, and metadata:
+### Callbacks
 
 ```ruby
-result = ProcessOrderTask.call(order_id: 123)
+CMDx.configure do |config|
+  # Via method
+  config.callbacks.register :before_execution, :initialize_user_session
 
-case result.status
-when 'success'
-  order = result.context.order
-  redirect_to order_path(order), notice: "Order processed successfully!"
+  # Via callable (must respond to `call(task)`)
+  config.callbacks.register :on_success, LogUserActivity
 
-when 'skipped'
-  reason = result.metadata[:reason]
-  redirect_to order_path(123), notice: "Skipped: #{reason}"
+  # Via proc or lambda
+  config.callbacks.register :on_complete, proc { |task|
+    execution_time = task.metadata[:runtime]
+    Metrics.timer("task.execution_time", execution_time, tags: ["task:#{task.class.name.underscore}"])
+  }
 
-when 'failed'
-  error_details = result.metadata[:reason]
-  redirect_to orders_path, alert: "Processing failed: #{error_details}"
-end
+  # With options
+  config.callbacks.register :on_failure, :send_alert_notification, if: :critical_task?
 
-# Access execution metadata
-puts "Runtime: #{result.runtime}ms"
-puts "Task ID: #{result.id}"
-puts "Executed at: #{result.executed_at}"
+  # Remove callback
+  config.callbacks.deregister :on_success, LogUserActivity
+end
 ```
 
-### Result Properties
+### Coercions
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(value, options)`)
+  config.coercions.register :currency, CurrencyCoercion
 
-| Property | Description | Example |
-|----------|-------------|---------|
-| `status` | Execution outcome | `'success'`, `'failed'`, `'skipped'` |
-| `context` | Shared data object | `result.context.order` |
-| `metadata` | Additional details | `result.metadata[:reason]` |
-| `runtime` | Execution time (ms) | `result.runtime` |
-| `id` | Unique task execution ID | `result.id` |
+  # Via method (must match signature `def coordinates_coercion(value, options)`)
+  config.coercions.register :coordinates, :coordinates_coercion
 
-## Exception Handling
+  # Via proc or lambda
+  config.coercions.register :tag_list, proc { |value, options|
+    delimiter = options[:delimiter] || ','
+    max_tags = options[:max_tags] || 50
 
-> [!WARNING]
-> `call!` raises exceptions for failed or skipped tasks. Use this pattern when failures should halt program execution.
+    tags = value.to_s.split(delimiter).map(&:strip).reject(&:empty?)
+    tags.first(max_tags)
+  }
+
+  # Remove coercion
+  config.coercions.deregister :currency
+end
+```
+
+### Validators
 
 ```ruby
-begin
-  result = ProcessOrderTask.call!(order_id: 123)
-  redirect_to order_path(result.context.order), notice: "Order processed!"
+CMDx.configure do |config|
+  # Via callable (must respond to `call(value, options)`)
+  config.validators.register :username, UsernameValidator
+
+  # Via method (must match signature `def url_validator(value, options)`)
+  config.validators.register :url, :url_validator
 
-rescue CMDx::Skipped => e
-  reason = e.result.metadata[:reason]
-  redirect_to orders_path, notice: "Skipped: #{reason}"
+  # Via proc or lambda
+  config.validators.register :access_token, proc { |value, options|
+    expected_prefix = options[:prefix] || "tok_"
+    minimum_length = options[:min_length] || 40
 
-rescue CMDx::Failed => e
-  error_details = e.result.metadata[:reason]
-  redirect_to order_path(123), alert: "Failed: #{error_details}"
+    value.start_with?(expected_prefix) && value.length >= minimum_length
+  }
 
-rescue ActiveRecord::RecordNotFound
-  redirect_to orders_path, alert: "Order not found"
+  # Remove validator
+  config.validators.deregister :username
 end
 ```
 
-### Exception Types
+## Task Configuration
 
-- **`CMDx::Skipped`** - Task was skipped intentionally
-- **`CMDx::Failed`** - Task failed due to business logic or validation errors
-- **Standard exceptions** - Ruby/Rails exceptions (e.g., `ActiveRecord::RecordNotFound`)
+### Settings
 
-## Building Workflows
-
-> [!TIP]
-> Workflows orchestrate multiple tasks with automatic context sharing, error handling, and execution flow control.
+Override global configuration for specific tasks using `settings`:
 
 ```ruby
-class OrderProcessingWorkflow < CMDx::Workflow
-  required :order_id, type: :integer
-  optional :priority, type: :string, default: 'standard'
+class GenerateInvoice < CMDx::Task
+  settings(
+    # Global configuration overrides
+    task_breakpoints: ["failed"],                # Breakpoint override
+    workflow_breakpoints: [],                    # Breakpoint override
+    logger: CustomLogger.new($stdout),           # Custom logger
+
+    # Task configuration settings
+    breakpoints: ["failed"],                     # Contextual pointer for :task_breakpoints and :workflow_breakpoints
+    log_level: :info,                            # Log level override
+    log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
+    tags: ["billing", "financial"],              # Logging tags
+    deprecated: true                             # Task deprecations
+  )
+
+  def work
+    # Your logic here...
+  end
+end
+```
 
-  before_execution :log_workflow_start
-  on_failed :notify_support
-  on_skipped :log_skip_reason
+> [!TIP]
+> Use task-level settings for tasks that require special handling, such as financial reporting, external API integrations, or critical system operations.
 
-  process ValidateOrderTask
-  process ChargePaymentTask
-  process UpdateInventoryTask
-  process SendConfirmationTask, if: proc { context.payment_successful? }
-  process ExpressShippingTask, if: proc { priority == 'express' }
+### Registrations
 
-  private
+Register middlewares, callbacks, coercions, and validators on a specific task.
+Deregister options that should not be available.
 
-  def log_workflow_start
-    Rails.logger.info "Starting order processing for order #{order_id}"
+```ruby
+class SendCampaignEmail < CMDx::Task
+  # Middlewares
+  register :middleware, CMDx::Middlewares::Timeout
+  deregister :middleware, AuditTrailMiddleware
+
+  # Callbacks
+  register :callback, :on_complete, proc { |task|
+    runtime = task.metadata[:runtime]
+    Analytics.track("email_campaign.sent", runtime, tags: ["task:#{task.class.name}"])
+  }
+  deregister :callback, :before_execution, :initialize_user_session
+
+  # Coercions
+  register :coercion, :currency, CurrencyCoercion
+  deregister :coercion, :coordinates
+
+  # Validators
+  register :validator, :username, :username_validator
+  deregister :validator, :url
+
+  def work
+    # Your logic here...
   end
+end
+```
 
-  def notify_support
-    SupportNotifier.alert("Order workflow failed",
-      order_id: order_id,
-      error: result.metadata[:reason]
-    )
-  end
+## Configuration Management
 
-  def log_skip_reason
-    Rails.logger.warn "Workflow skipped: #{result.metadata[:reason]}"
+### Access
+
+```ruby
+# Global configuration access
+CMDx.configuration.logger               #=> <Logger instance>
+CMDx.configuration.task_breakpoints     #=> ["failed"]
+CMDx.configuration.middlewares.registry #=> [<Middleware>, ...]
+
+# Task configuration access
+class ProcessUpload < CMDx::Task
+  settings(tags: ["files", "storage"])
+
+  def work
+    self.class.settings[:logger] #=> Global configuration value
+    self.class.settings[:tags]   #=> Task configuration value => ["files", "storage"]
   end
 end
-
-# Execute workflow
-result = OrderProcessingWorkflow.call(order_id: 123, priority: 'express')
 ```
 
-### Workflow Features
-
-- **Automatic context sharing** - Tasks access shared `context` object
-- **Conditional execution** - Use `:if` conditions for optional tasks
-- **Lifecycle callbacks** - Hook into workflow execution phases
-- **Error propagation** - Failed tasks halt workflow execution
-- **Skip handling** - Graceful handling of skipped tasks
+### Resetting
 
-## Code Generation
-
-Generate properly structured tasks and workflows:
+> [!WARNING]
+> Resetting configuration affects the entire application. Use primarily in test environments or during application initialization.
 
 ```ruby
-# Generate individual task
-rails generate cmdx:task ProcessOrder
-# Creates: app/cmds/process_order_task.rb
+# Reset to framework defaults
+CMDx.reset_configuration!
 
-# Generate workflow
-rails generate cmdx:workflow OrderProcessing
-# Creates: app/cmds/order_processing_workflow.rb
+# Verify reset
+CMDx.configuration.task_breakpoints     #=> ["failed"] (default)
+CMDx.configuration.middlewares.registry #=> Empty registry
 
-# Generate with parameters
-rails generate cmdx:task CreateUser email:string age:integer active:boolean
+# Commonly used in test setup (RSpec example)
+RSpec.configure do |config|
+  config.before(:each) do
+    CMDx.reset_configuration!
+  end
+end
 ```
 
-> [!NOTE]
-> Generators automatically handle naming conventions and inherit from `ApplicationTask`/`ApplicationWorkflow` when available. Generated files include parameter definitions and basic structure.
+## Task Generator
 
-### Generated Task Structure
+Generate new CMDx tasks quickly using the built-in generator:
 
-```ruby
-# app/cmds/process_order_task.rb
-class ProcessOrderTask < ApplicationTask
-  required :order_id, type: :integer
+```bash
+rails generate cmdx:task ModerateBlogPost
+```
 
-  def call
-    # Task implementation
+This creates a new task file with the basic structure:
+
+```ruby
+# app/tasks/moderate_blog_post.rb
+class ModerateBlogPost < CMDx::Task
+  def work
+    # Your logic here...
   end
 end
 ```
 
+> [!TIP]
+> Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`
+
 ---
 
-- **Next:** [Configuration](configuration.md)
-- **See also:** [Parameters - Coercions](parameters/coercions.md) | [Workflows](workflows.md)
+- **Prev:** [Tips and Tricks](tips_and_tricks.md)
+- **Next:** [Basics - Setup](basics/setup.md)