cmdx 1.13.0 → 1.14.0

data/docs/attributes/coercions.md

@@ -1,155 +0,0 @@
-# Attributes - Coercions
-
-Automatically convert inputs to expected types. Coercions handle everything from simple string-to-integer conversions to JSON parsing.
-
-See [Global Configuration](../getting_started.md#coercions) for custom coercion setup.
-
-## Usage
-
-Define attribute types to enable automatic coercion:
-
-```ruby
-class ParseMetrics < CMDx::Task
-  # Coerce into a symbol
-  attribute :measurement_type, type: :symbol
-
-  # Coerce into a rational fallback to big decimal
-  attribute :value, type: [:rational, :big_decimal]
-
-  # Coerce with options
-  attribute :recorded_at, type: :date, strptime: "%m-%d-%Y"
-
-  def work
-    measurement_type #=> :temperature
-    recorded_at      #=> <Date 2024-01-23>
-    value            #=> 98.6 (Float)
-  end
-end
-
-ParseMetrics.execute(
-  measurement_type: "temperature",
-  recorded_at: "01-23-2020",
-  value: "98.6"
-)
-```
-
-!!! tip
-
-    Specify multiple coercion types for attributes that could be a variety of value formats. CMDx attempts each type in order until one succeeds.
-
-## Built-in Coercions
-
-| Type | Options | Description | Examples |
-|------|---------|-------------|----------|
-| `:array` | | Array conversion with JSON support | `"val"` → `["val"]`<br>`"[1,2,3]"` → `[1, 2, 3]` |
-| `:big_decimal` | `:precision` | High-precision decimal | `"123.456"` → `BigDecimal("123.456")` |
-| `:boolean` | | Boolean with text patterns | `"yes"` → `true`, `"no"` → `false` |
-| `:complex` | | Complex numbers | `"1+2i"` → `Complex(1, 2)` |
-| `:date` | `:strptime` | Date objects | `"2024-01-23"` → `Date.new(2024, 1, 23)` |
-| `:datetime` | `:strptime` | DateTime objects | `"2024-01-23 10:30"` → `DateTime.new(2024, 1, 23, 10, 30)` |
-| `:float` | | Floating-point numbers | `"123.45"` → `123.45` |
-| `:hash` | | Hash conversion with JSON support | `'{"a":1}'` → `{"a" => 1}` |
-| `:integer` | | Integer with hex/octal support | `"0xFF"` → `255`, `"077"` → `63` |
-| `:rational` | | Rational numbers | `"1/2"` → `Rational(1, 2)` |
-| `:string` | | String conversion | `123` → `"123"` |
-| `:symbol` | | Symbol conversion | `"abc"` → `:abc` |
-| `:time` | `:strptime` | Time objects | `"10:30:00"` → `Time.new(2024, 1, 23, 10, 30)` |
-
-## Declarations
-
-!!! warning "Important"
-
-    Custom coercions must raise `CMDx::CoercionError` with a descriptive message.
-
-### Proc or Lambda
-
-Use anonymous functions for simple coercion logic:
-
-```ruby
-class TransformCoordinates < CMDx::Task
-  # Proc
-  register :callback, :geolocation, proc do |value, options = {}|
-    begin
-      Geolocation(value)
-    rescue StandardError
-      raise CMDx::CoercionError, "could not convert into a geolocation"
-    end
-  end
-
-  # Lambda
-  register :callback, :geolocation, ->(value, options = {}) {
-    begin
-      Geolocation(value)
-    rescue StandardError
-      raise CMDx::CoercionError, "could not convert into a geolocation"
-    end
-  }
-end
-```
-
-### Class or Module
-
-Register custom coercion logic for specialized type handling:
-
-```ruby
-class GeolocationCoercion
-  def self.call(value, options = {})
-    Geolocation(value)
-  rescue StandardError
-    raise CMDx::CoercionError, "could not convert into a geolocation"
-  end
-end
-
-class TransformCoordinates < CMDx::Task
-  register :coercion, :geolocation, GeolocationCoercion
-
-  attribute :latitude, type: :geolocation
-end
-```
-
-## Removals
-
-Remove unwanted coercions:
-
-!!! warning
-
-    Each `deregister` call removes one coercion. Use multiple calls for batch removals.
-
-```ruby
-class TransformCoordinates < CMDx::Task
-  deregister :coercion, :geolocation
-end
-```
-
-## Error Handling
-
-Coercion failures provide detailed error information including attribute paths, attempted types, and specific failure reasons:
-
-```ruby
-class AnalyzePerformance < CMDx::Task
-  attribute  :iterations, type: :integer
-  attribute  :score, type: [:float, :big_decimal]
-
-  def work
-    # Your logic here...
-  end
-end
-
-result = AnalyzePerformance.execute(
-  iterations: "not-a-number",
-  score: "invalid-float"
-)
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "iterations could not coerce into an integer. score could not coerce into one of: float, big_decimal.",
-                #       messages: {
-                #         iterations: ["could not coerce into an integer"],
-                #         score: ["could not coerce into one of: float, big_decimal"]
-                #       }
-                #     }
-                #   }
-```

data/docs/attributes/defaults.md

@@ -1,77 +0,0 @@
-# Attributes - Defaults
-
-Provide fallback values for optional attributes. Defaults kick in when values aren't provided or are `nil`.
-
-## Declarations
-
-Defaults work seamlessly with coercions, validations, and nested attributes:
-
-### Static Values
-
-```ruby
-class OptimizeDatabase < CMDx::Task
-  attribute :strategy, default: :incremental
-  attribute :level, default: "basic"
-  attribute :notify_admin, default: true
-  attribute :timeout_minutes, default: 30
-  attribute :indexes, default: []
-  attribute :options, default: {}
-
-  def work
-    strategy        #=> :incremental
-    level           #=> "basic"
-    notify_admin    #=> true
-    timeout_minutes #=> 30
-    indexes         #=> []
-    options         #=> {}
-  end
-end
-```
-
-### Symbol References
-
-Reference instance methods by symbol for dynamic default values:
-
-```ruby
-class ProcessAnalytics < CMDx::Task
-  attribute :granularity, default: :default_granularity
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def default_granularity
-    Current.user.premium? ? "hourly" : "daily"
-  end
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for dynamic default values:
-
-```ruby
-class CacheContent < CMDx::Task
-  # Proc
-  attribute :expire_hours, default: proc { Current.tenant.cache_duration || 24 }
-
-  # Lambda
-  attribute :compression, default: -> { Current.tenant.premium? ? "gzip" : "none" }
-end
-```
-
-## Coercions and Validations
-
-Defaults follow the same coercion and validation rules as provided values:
-
-```ruby
-class ScheduleBackup < CMDx::Task
-  # Coercions
-  attribute :retention_days, default: "7", type: :integer
-
-  # Validations
-  optional :frequency, default: "daily", inclusion: { in: %w[hourly daily weekly monthly] }
-end
-```

data/docs/attributes/definitions.md

@@ -1,283 +0,0 @@
-# Attributes - Definitions
-
-Attributes define your task's interface with automatic validation, type coercion, and accessor generation. They're the contract between callers and your business logic.
-
-## Declarations
-
-!!! warning "Important"
-
-    Attributes are order-dependent, so if you need to reference them as a source or use them in conditions, make sure they’re defined in the correct order.
-
-!!! tip
-
-    Prefer using the `required` and `optional` alias for `attributes` for brevity and to clearly signal intent.
-
-### Optional
-
-Optional attributes return `nil` when not provided.
-
-```ruby
-class ScheduleEvent < CMDx::Task
-  attribute :title
-  attributes :duration, :location
-
-  # Alias for attributes (preferred)
-  optional :description
-  optional :visibility, :attendees
-
-  def work
-    title       #=> "Team Standup"
-    duration    #=> 30
-    location    #=> nil
-    description #=> nil
-    visibility  #=> nil
-    attendees   #=> ["alice@company.com", "bob@company.com"]
-  end
-end
-
-# Attributes passed as keyword arguments
-ScheduleEvent.execute(
-  title: "Team Standup",
-  duration: 30,
-  attendees: ["alice@company.com", "bob@company.com"]
-)
-```
-
-### Required
-
-Required attributes must be provided in call arguments or task execution will fail.
-
-```ruby
-class PublishArticle < CMDx::Task
-  attribute :title, required: true
-  attributes :content, :author_id, required: true
-
-  # Alias for attributes => required: true (preferred)
-  required :category
-  required :status, :tags
-
-  # Conditionally required
-  required :publisher, if: :magazine?
-  attribute :approver, required: true, unless: proc { status == :published }
-
-  def work
-    title     #=> "Getting Started with Ruby"
-    content   #=> "This is a comprehensive guide..."
-    author_id #=> 42
-    category  #=> "programming"
-    status    #=> :published
-    tags      #=> ["ruby", "beginner"]
-    publisher #=> "Eastbay"
-    approver  #=> #<Editor ...>
-  end
-
-  private
-
-  def magazine?
-    context.title.ends_with?("[M]")
-  end
-end
-```
-
-!!! note
-
-    When a required attribute's condition evaluates to `false`, the attribute behaves as optional. All other attribute features such as coercions, validations, defaults, and transformations still apply normally.
-
-## Sources
-
-Attributes read from any accessible object—not just context. Use sources to pull data from models, services, or any callable:
-
-### Context
-
-```ruby
-class BackupDatabase < CMDx::Task
-  # Default source is :context
-  required :database_name
-  optional :compression_level
-
-  # Explicitly specify context source
-  attribute :backup_path, source: :context
-
-  def work
-    database_name     #=> context.database_name
-    backup_path       #=> context.backup_path
-    compression_level #=> context.compression_level
-  end
-end
-```
-
-### Symbol References
-
-Reference instance methods by symbol for dynamic source values:
-
-```ruby
-class BackupDatabase < CMDx::Task
-  attributes :host, :credentials, source: :database_config
-
-  # Access from declared attributes
-  attribute :connection_string, source: :credentials
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def database_config
-    @database_config ||= DatabaseConfig.find(context.database_name)
-  end
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for dynamic source values:
-
-```ruby
-class BackupDatabase < CMDx::Task
-  # Proc
-  attribute :timestamp, source: proc { Time.current }
-
-  # Lambda
-  attribute :server, source: -> { Current.server }
-end
-```
-
-### Class or Module
-
-For complex source logic, use classes or modules:
-
-```ruby
-class DatabaseResolver
-  def self.call(task)
-    Database.find(task.context.database_name)
-  end
-end
-
-class BackupDatabase < CMDx::Task
-  # Class or Module
-  attribute :schema, source: DatabaseResolver
-
-  # Instance
-  attribute :metadata, source: DatabaseResolver.new
-end
-```
-
-## Nesting
-
-Build complex structures with nested attributes. Children inherit their parent as source and support all attribute options:
-
-!!! note
-
-    Nested attributes support all features: naming, coercions, validations, defaults, and more.
-
-```ruby
-class ConfigureServer < CMDx::Task
-  # Required parent with required children
-  required :network_config do
-    required :hostname, :port, :protocol, :subnet
-    optional :load_balancer
-    attribute :firewall_rules
-  end
-
-  # Optional parent with conditional children
-  optional :ssl_config do
-    required :certificate_path, :private_key # Only required if ssl_config provided
-    optional :enable_http2, prefix: true
-  end
-
-  # Multi-level nesting
-  attribute :monitoring do
-    required :provider
-
-    optional :alerting do
-      required :threshold_percentage
-      optional :notification_channel
-    end
-  end
-
-  def work
-    network_config   #=> { hostname: "api.company.com" ... }
-    hostname         #=> "api.company.com"
-    load_balancer    #=> nil
-  end
-end
-
-ConfigureServer.execute(
-  server_id: "srv-001",
-  network_config: {
-    hostname: "api.company.com",
-    port: 443,
-    protocol: "https",
-    subnet: "10.0.1.0/24",
-    firewall_rules: "allow_web_traffic"
-  },
-  monitoring: {
-    provider: "datadog",
-    alerting: {
-      threshold_percentage: 85.0,
-      notification_channel: "slack"
-    }
-  }
-)
-```
-
-!!! warning "Important"
-
-    Child requirements only apply when the parent is provided—perfect for optional structures.
-
-## Error Handling
-
-Validation failures provide detailed, structured error messages:
-
-!!! note
-
-    Nested attributes are only validated when their parent is present and valid.
-
-```ruby
-class ConfigureServer < CMDx::Task
-  required :server_id, :environment
-  required :network_config do
-    required :hostname, :port
-  end
-
-  def work
-    # Your logic here...
-  end
-end
-
-# Missing required top-level attributes
-result = ConfigureServer.execute(server_id: "srv-001")
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "environment is required. network_config is required.",
-                #       messages: {
-                #         environment: ["is required"],
-                #         network_config: ["is required"]
-                #       }
-                #     }
-                #   }
-
-# Missing required nested attributes
-result = ConfigureServer.execute(
-  server_id: "srv-001",
-  environment: "production",
-  network_config: { hostname: "api.company.com" } # Missing port
-)
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "port is required.",
-                #       messages: {
-                #         port: ["is required"]
-                #       }
-                #     }
-                #   }
-```

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