cmdx 1.12.0 → 1.14.0

data/docs/attributes/naming.md

@@ -1,68 +0,0 @@
-# Attributes - Naming
-
-Customize accessor method names to avoid conflicts and improve clarity. Affixing changes only the generated methods—not the original attribute names.
-
-!!! note
-
-    Use naming when attributes conflict with existing methods or need better clarity in your code.
-
-## Prefix
-
-Adds a prefix to the generated accessor method name.
-
-```ruby
-class GenerateReport < CMDx::Task
-  # Dynamic from attribute source
-  attribute :template, prefix: true
-
-  # Static
-  attribute :format, prefix: "report_"
-
-  def work
-    context_template #=> "monthly_sales"
-    report_format    #=> "pdf"
-  end
-end
-
-# Attributes passed as original attribute names
-GenerateReport.execute(template: "monthly_sales", format: "pdf")
-```
-
-## Suffix
-
-Adds a suffix to the generated accessor method name.
-
-```ruby
-class DeployApplication < CMDx::Task
-  # Dynamic from attribute source
-  attribute :branch, suffix: true
-
-  # Static
-  attribute :version, suffix: "_tag"
-
-  def work
-    branch_context #=> "main"
-    version_tag    #=> "v1.2.3"
-  end
-end
-
-# Attributes passed as original attribute names
-DeployApplication.execute(branch: "main", version: "v1.2.3")
-```
-
-## As
-
-Completely renames the generated accessor method.
-
-```ruby
-class ScheduleMaintenance < CMDx::Task
-  attribute :scheduled_at, as: :when
-
-  def work
-    when #=> <DateTime>
-  end
-end
-
-# Attributes passed as original attribute names
-ScheduleMaintenance.execute(scheduled_at: DateTime.new(2024, 12, 15, 2, 0, 0))
-```

data/docs/attributes/transformations.md

@@ -1,63 +0,0 @@
-# Attributes - Transformations
-
-Modify attribute values after coercion but before validation. Perfect for normalization, formatting, and data cleanup.
-
-## Declarations
-
-### Symbol References
-
-Reference instance methods by symbol for dynamic value transformations:
-
-```ruby
-class ProcessAnalytics < CMDx::Task
-  attribute :options, transform: :compact_blank
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for dynamic value transformations:
-
-```ruby
-class CacheContent < CMDx::Task
-  # Proc
-  attribute :expire_hours, transform: proc { |v| v * 2 }
-
-  # Lambda
-  attribute :compression, transform: ->(v) { v.to_s.upcase.strip[0..2]  }
-end
-```
-
-### Class or Module
-
-Use any object that responds to `call` for reusable transformation logic:
-
-```ruby
-class EmailNormalizer
-  def call(value)
-    value.to_s.downcase.strip
-  end
-end
-
-class ProcessContacts < CMDx::Task
-  # Class or Module
-  attribute :email, transform: EmailNormalizer
-
-  # Instance
-  attribute :email, transform: EmailNormalizer.new
-end
-```
-
-## Validations
-
-Validations run on transformed values, ensuring data consistency:
-
-```ruby
-class ScheduleBackup < CMDx::Task
-  # Coercions
-  attribute :retention_days, type: :integer, transform: proc { |v| v.clamp(1, 5) }
-
-  # Validations
-  optional :frequency, transform: :downcase, inclusion: { in: %w[hourly daily weekly monthly] }
-end
-```

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)
-```