cmdx 1.13.0 → 1.14.0

data/docs/attributes/validations.md

@@ -1,336 +0,0 @@
-# Attributes - Validations
-
-Ensure inputs meet requirements before execution. Validations run after coercions, giving you declarative data integrity checks.
-
-See [Global Configuration](../getting_started.md#validators) for custom validator setup.
-
-## Usage
-
-Define validation rules on attributes to enforce data requirements:
-
-```ruby
-class ProcessSubscription < CMDx::Task
-  # Required field with presence validation
-  attribute :user_id, presence: true
-
-  # String with length constraints
-  optional :preferences, length: { minimum: 10, maximum: 500 }
-
-  # Numeric range validation
-  required :tier_level, inclusion: { in: 1..5 }
-
-  # Format validation for email
-  attribute :contact_email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
-
-  def work
-    user_id       #=> "98765"
-    preferences   #=> "Send weekly digest emails"
-    tier_level    #=> 3
-    contact_email #=> "user@company.com"
-  end
-end
-
-ProcessSubscription.execute(
-  user_id: "98765",
-  preferences: "Send weekly digest emails",
-  tier_level: 3,
-  contact_email: "user@company.com"
-)
-```
-
-!!! tip
-
-    Validations run after coercions, so you can validate the final coerced values rather than raw input.
-
-## Built-in Validators
-
-### Common Options
-
-```ruby
-class ProcessProduct < CMDx::Task
-  # Allow nil
-  attribute :tier_level, inclusion: {
-    in: 1..5,
-    allow_nil: true
-  }
-
-  # Conditionals
-  optional :contact_email, format: {
-    with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
-    if: ->(value) { value.includes?("@") }
-  }
-  required :status, exclusion: {
-    in: %w[recalled archived],
-    unless: :product_sunsetted?
-  }
-
-  # Custom message
-  attribute :title, length: {
-    within: 5..100,
-    message: "must be in optimal size"
-  }
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def product_defunct?(value)
-    context.company.out_of_business? || value == "deprecated"
-  end
-end
-```
-
-This list of options is available to all validators:
-
-| Option | Description |
-|--------|-------------|
-| `:allow_nil` | Skip validation when value is `nil` |
-| `:if` | Symbol, proc, lambda, or callable determining when to validate |
-| `:unless` | Symbol, proc, lambda, or callable determining when to skip validation |
-| `:message` | Custom error message for validation failures |
-
-### Exclusion
-
-```ruby
-class ProcessProduct < CMDx::Task
-  attribute :status, exclusion: { in: %w[recalled archived] }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `:in` | The collection of forbidden values or range |
-| `:within` | Alias for :in option |
-| `:of_message` | Custom message for discrete value exclusions |
-| `:in_message` | Custom message for range-based exclusions |
-| `:within_message` | Alias for :in_message option |
-
-### Format
-
-```ruby
-class ProcessProduct < CMDx::Task
-  attribute :sku, format: /\A[A-Z]{3}-[0-9]{4}\z/
-
-  attribute :sku, format: { with: /\A[A-Z]{3}-[0-9]{4}\z/ }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `regexp` | Alias for :with option |
-| `:with` | Regex pattern that the value must match |
-| `:without` | Regex pattern that the value must not match |
-
-### Inclusion
-
-```ruby
-class ProcessProduct < CMDx::Task
-  attribute :availability, inclusion: { in: %w[available limited] }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `:in` | The collection of allowed values or range |
-| `:within` | Alias for :in option |
-| `:of_message` | Custom message for discrete value inclusions |
-| `:in_message` | Custom message for range-based inclusions |
-| `:within_message` | Alias for :in_message option |
-
-### Length
-
-```ruby
-class CreateBlogPost < CMDx::Task
-  attribute :title, length: { within: 5..100 }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `:within` | Range that the length must fall within (inclusive) |
-| `:not_within` | Range that the length must not fall within |
-| `:in` | Alias for :within |
-| `:not_in` | Range that the length must not fall within |
-| `:min` | Minimum allowed length |
-| `:max` | Maximum allowed length |
-| `:is` | Exact required length |
-| `:is_not` | Length that is not allowed |
-| `:within_message` | Custom message for within/range validations |
-| `:in_message` | Custom message for :in validation |
-| `:not_within_message` | Custom message for not_within validation |
-| `:not_in_message` | Custom message for not_in validation |
-| `:min_message` | Custom message for minimum length validation |
-| `:max_message` | Custom message for maximum length validation |
-| `:is_message` | Custom message for exact length validation |
-| `:is_not_message` | Custom message for is_not validation |
-
-### Numeric
-
-```ruby
-class CreateBlogPost < CMDx::Task
-  attribute :word_count, numeric: { min: 100 }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `:within` | Range that the value must fall within (inclusive) |
-| `:not_within` | Range that the value must not fall within |
-| `:in` | Alias for :within option |
-| `:not_in` | Alias for :not_within option |
-| `:min` | Minimum allowed value (inclusive, >=) |
-| `:max` | Maximum allowed value (inclusive, <=) |
-| `:is` | Exact value that must match |
-| `:is_not` | Value that must not match |
-| `:within_message` | Custom message for range validations |
-| `:not_within_message` | Custom message for exclusion validations |
-| `:min_message` | Custom message for minimum validation |
-| `:max_message` | Custom message for maximum validation |
-| `:is_message` | Custom message for exact match validation |
-| `:is_not_message` | Custom message for exclusion validation |
-
-### Presence
-
-```ruby
-class CreateBlogPost < CMDx::Task
-  attribute :content, presence: true
-
-  attribute :content, presence: { message: "cannot be blank" }
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-| Options | Description |
-|---------|-------------|
-| `true` | Ensures value is not nil, empty string, or whitespace |
-
-## Declarations
-
-!!! warning "Important"
-
-    Custom validators must raise `CMDx::ValidationError` with a descriptive message.
-
-### Proc or Lambda
-
-Use anonymous functions for simple validation logic:
-
-```ruby
-class SetupApplication < CMDx::Task
-  # Proc
-  register :validator, :api_key, proc do |value, options = {}|
-    unless value.match?(/\A[a-zA-Z0-9]{32}\z/)
-      raise CMDx::ValidationError, "invalid API key format"
-    end
-  end
-
-  # Lambda
-  register :validator, :api_key, ->(value, options = {}) {
-    unless value.match?(/\A[a-zA-Z0-9]{32}\z/)
-      raise CMDx::ValidationError, "invalid API key format"
-    end
-  }
-end
-```
-
-### Class or Module
-
-Register custom validation logic for specialized requirements:
-
-```ruby
-class ApiKeyValidator
-  def self.call(value, options = {})
-    unless value.match?(/\A[a-zA-Z0-9]{32}\z/)
-      raise CMDx::ValidationError, "invalid API key format"
-    end
-  end
-end
-
-class SetupApplication < CMDx::Task
-  register :validator, :api_key, ApiKeyValidator
-
-  attribute :access_key, api_key: true
-end
-```
-
-## Removals
-
-Remove unwanted validators:
-
-!!! warning
-
-    Each `deregister` call removes one validator. Use multiple calls for batch removals.
-
-```ruby
-class SetupApplication < CMDx::Task
-  deregister :validator, :api_key
-end
-```
-
-## Error Handling
-
-Validation failures provide detailed, structured error messages:
-
-```ruby
-class CreateProject < CMDx::Task
-  attribute :project_name,
-    presence: true,
-    length: { minimum: 3, maximum: 50 }
-  optional :budget,
-    numeric: { greater_than: 1000, less_than: 1000000 }
-  required :priority,
-    inclusion: { in: [:low, :medium, :high] }
-  attribute :contact_email,
-    format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
-
-  def work
-    # Your logic here...
-  end
-end
-
-result = CreateProject.execute(
-  project_name: "AB",           # Too short
-  budget: 500,                  # Too low
-  priority: :urgent,            # Not in allowed list
-  contact_email: "invalid-email"    # Invalid format
-)
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "project_name is too short (minimum is 3 characters). budget must be greater than 1000. priority is not included in the list. contact_email is invalid.",
-                #       messages: {
-                #         project_name: ["is too short (minimum is 3 characters)"],
-                #         budget: ["must be greater than 1000"],
-                #         priority: ["is not included in the list"],
-                #         contact_email: ["is invalid"]
-                #       }
-                #     }
-                #   }
-```

data/docs/basics/chain.md

@@ -1,108 +0,0 @@
-# Basics - Chain
-
-Chains automatically track related task executions within a thread. Think of them as execution traces that help you understand what happened and in what order.
-
-## Management
-
-Each thread maintains its own isolated chain using thread-local storage.
-
-!!! warning
-
-    Chains are thread-local. Don't share chain references across threads—it causes race conditions.
-
-```ruby
-# Thread A
-Thread.new do
-  result = ImportDataset.execute(file_path: "/data/batch1.csv")
-  result.chain.id    #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
-end
-
-# Thread B (completely separate chain)
-Thread.new do
-  result = ImportDataset.execute(file_path: "/data/batch2.csv")
-  result.chain.id    #=> "z3a42b95-c821-7892-b156-dd7c921fe2a3"
-end
-
-# Access current thread's chain
-CMDx::Chain.current  #=> Returns current chain or nil
-CMDx::Chain.clear    #=> Clears current thread's chain
-```
-
-## Links
-
-Tasks automatically create or join the current thread's chain:
-
-!!! warning "Important"
-
-    Chain management is automatic—no manual lifecycle handling needed.
-
-```ruby
-class ImportDataset < CMDx::Task
-  def work
-    # First task creates new chain
-    result1 = ValidateHeaders.execute(file_path: context.file_path)
-    result1.chain.id           #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
-    result1.chain.results.size #=> 1
-
-    # Second task joins existing chain
-    result2 = SendNotification.execute(to: "admin@company.com")
-    result2.chain.id == result1.chain.id  #=> true
-    result2.chain.results.size            #=> 2
-
-    # Both results reference the same chain
-    result1.chain.results == result2.chain.results #=> true
-  end
-end
-```
-
-## Inheritance
-
-Subtasks automatically inherit the current thread's chain, building a unified execution trail:
-
-```ruby
-class ImportDataset < CMDx::Task
-  def work
-    context.dataset = Dataset.find(context.dataset_id)
-
-    # Subtasks automatically inherit current chain
-    ValidateSchema.execute
-    TransformData.execute!(context)
-    SaveToDatabase.execute(dataset_id: context.dataset_id)
-  end
-end
-
-result = ImportDataset.execute(dataset_id: 456)
-chain = result.chain
-
-# All tasks share the same chain
-chain.results.size #=> 4 (main task + 3 subtasks)
-chain.results.map { |r| r.task.class }
-#=> [ImportDataset, ValidateSchema, TransformData, SaveToDatabase]
-```
-
-## Structure
-
-Chains expose comprehensive execution information:
-
-!!! warning "Important"
-
-    Chain state reflects the first (outermost) task result. Subtasks maintain their own states.
-
-```ruby
-result = ImportDataset.execute(dataset_id: 456)
-chain = result.chain
-
-# Chain identification
-chain.id      #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
-chain.results #=> Array of all results in execution order
-
-# State delegation (from first/outer-most result)
-chain.state   #=> "complete"
-chain.status  #=> "success"
-chain.outcome #=> "success"
-
-# Access individual results
-chain.results.each_with_index do |result, index|
-  puts "#{index}: #{result.task.class} - #{result.status}"
-end
-```

data/docs/basics/context.md

@@ -1,121 +0,0 @@
-# Basics - Context
-
-Context is your data container for inputs, intermediate values, and outputs. It makes sharing data between tasks effortless.
-
-## Assigning Data
-
-Context automatically captures all task inputs, normalizing keys to symbols:
-
-```ruby
-# Direct execution
-CalculateShipping.execute(weight: 2.5, destination: "CA")
-
-# Instance creation
-CalculateShipping.new(weight: 2.5, "destination" => "CA")
-```
-
-!!! warning "Important"
-
-    String keys convert to symbols automatically. Prefer symbols for consistency.
-
-## Accessing Data
-
-Access context data using method notation, hash keys, or safe accessors:
-
-```ruby
-class CalculateShipping < CMDx::Task
-  def work
-    # Method style access (preferred)
-    weight = context.weight
-    destination = context.destination
-
-    # Hash style access
-    service_type = context[:service_type]
-    options = context["options"]
-
-    # Safe access with defaults
-    rush_delivery = context.fetch!(:rush_delivery, false)
-    carrier = context.dig(:options, :carrier)
-
-    # Shorter alias
-    cost = ctx.weight * ctx.rate_per_pound  # ctx aliases context
-  end
-end
-```
-
-!!! warning "Important"
-
-    Undefined attributes return `nil` instead of raising errors—perfect for optional data.
-
-## Modifying Context
-
-Context supports dynamic modification during task execution:
-
-```ruby
-class CalculateShipping < CMDx::Task
-  def work
-    # Direct assignment
-    context.carrier = Carrier.find_by(code: context.carrier_code)
-    context.package = Package.new(weight: context.weight)
-    context.calculated_at = Time.now
-
-    # Hash-style assignment
-    context[:status] = "calculating"
-    context["tracking_number"] = "SHIP#{SecureRandom.hex(6)}"
-
-    # Conditional assignment
-    context.insurance_included ||= false
-
-    # Batch updates
-    context.merge!(
-      status: "completed",
-      shipping_cost: calculate_cost,
-      estimated_delivery: Time.now + 3.days
-    )
-
-    # Remove sensitive data
-    context.delete!(:credit_card_token)
-  end
-
-  private
-
-  def calculate_cost
-    base_rate = context.weight * context.rate_per_pound
-    base_rate + (base_rate * context.tax_percentage)
-  end
-end
-```
-
-!!! tip
-
-    Use context for both input values and intermediate results. This creates natural data flow through your task execution pipeline.
-
-## Data Sharing
-
-Share context across tasks for seamless data flow:
-
-```ruby
-# During execution
-class CalculateShipping < CMDx::Task
-  def work
-    # Validate shipping data
-    validation_result = ValidateAddress.execute(context)
-
-    # Via context
-    CalculateInsurance.execute(context)
-
-    # Via result
-    NotifyShippingCalculated.execute(validation_result)
-
-    # Context now contains accumulated data from all tasks
-    context.address_validated    #=> true (from validation)
-    context.insurance_calculated #=> true (from insurance)
-    context.notification_sent    #=> true (from notification)
-  end
-end
-
-# After execution
-result = CalculateShipping.execute(destination: "New York, NY")
-
-CreateShippingLabel.execute(result)
-```

data/docs/basics/execution.md

@@ -1,152 +0,0 @@
-# Basics - Execution
-
-CMDx offers two execution methods with different error handling approaches. Choose based on your needs: safe result handling or exception-based control flow.
-
-## Execution Methods
-
-Both methods return results, but handle failures differently:
-
-| Method | Returns | Exceptions | Use Case |
-|--------|---------|------------|----------|
-| `execute` | Always returns `CMDx::Result` | Never raises | Predictable result handling |
-| `execute!` | Returns `CMDx::Result` on success | Raises `CMDx::Fault` when skipped or failed | Exception-based control flow |
-
-```mermaid
-flowchart LR
-    subgraph Methods
-        E[execute]
-        EB[execute!]
-    end
-
-    subgraph Returns [Returns CMDx::Result]
-        Success
-        Failed
-        Skipped
-    end
-
-    subgraph Raises [Raises CMDx::Fault]
-        FailFault
-        SkipFault
-    end
-
-    E --> Success
-    E --> Failed
-    E --> Skipped
-
-    EB --> Success
-    EB --> FailFault
-    EB --> SkipFault
-```
-
-## Non-bang Execution
-
-Always returns a `CMDx::Result`, never raises exceptions. Perfect for most use cases.
-
-```ruby
-result = CreateAccount.execute(email: "user@example.com")
-
-# Check execution state
-result.success?         #=> true/false
-result.failed?          #=> true/false
-result.skipped?         #=> true/false
-
-# Access result data
-result.context.email    #=> "user@example.com"
-result.state            #=> "complete"
-result.status           #=> "success"
-```
-
-## Bang Execution
-
-Raises `CMDx::Fault` exceptions on failure or skip. Returns results only on success.
-
-| Exception | Raised When |
-|-----------|-------------|
-| `CMDx::FailFault` | Task execution fails |
-| `CMDx::SkipFault` | Task execution is skipped |
-
-!!! warning "Important"
-
-    Behavior depends on `task_breakpoints` or `workflow_breakpoints` config. Default: only failures raise exceptions.
-
-```ruby
-begin
-  result = CreateAccount.execute!(email: "user@example.com")
-  SendWelcomeEmail.execute(result.context)
-rescue CMDx::FailFault => e
-  ScheduleAccountRetryJob.perform_later(e.result.context.email)
-rescue CMDx::SkipFault => e
-  Rails.logger.info("Account creation skipped: #{e.result.reason}")
-rescue Exception => e
-  ErrorTracker.capture(unhandled_exception: e)
-end
-```
-
-## Direct Instantiation
-
-Tasks can be instantiated directly for advanced use cases, testing, and custom execution patterns:
-
-```ruby
-# Direct instantiation
-task = CreateAccount.new(email: "user@example.com", send_welcome: true)
-
-# Access properties before execution
-task.id                      #=> "abc123..." (unique task ID)
-task.context.email           #=> "user@example.com"
-task.context.send_welcome    #=> true
-task.result.state            #=> "initialized"
-task.result.status           #=> "success"
-
-# Manual execution
-task.execute
-# or
-task.execute!
-
-task.result.success?         #=> true/false
-```
-
-## Result Details
-
-The `Result` object provides comprehensive execution information:
-
-```ruby
-result = CreateAccount.execute(email: "user@example.com")
-
-# Execution metadata
-result.id           #=> "abc123..."  (unique execution ID)
-result.task         #=> CreateAccount instance (frozen)
-result.chain        #=> Task execution chain
-
-# Context and metadata
-result.context      #=> Context with all task data
-result.metadata     #=> Hash with execution metadata
-```
-
-## Dry Run
-
-Execute tasks in dry-run mode to simulate execution without performing side effects. Pass `dry_run: true` in the context when initializing or executing the task.
-
-Inside your task, use the `dry_run?` method to conditionally skip side effects.
-
-```ruby
-class CloseStripeCard < CMDx::Task
-  def work
-    context.stripe_result =
-      if dry_run?
-        FactoryBot.build(:stripe_closed_card)
-      else
-        StripeApi.close_card(context.card_id)
-      end
-  end
-end
-
-# Execute in dry-run mode
-result = CloseStripeCard.execute(card_id: "card_abc123", dry_run: true)
-result.success? # => true
-
-# FactoryBot object
-result.context.stripe_result = {
-  card_id: "card_abc123",
-  status: "closed"
-}
-```