cmdx 1.1.2 → 1.5.0

data/README.md

@@ -1,16 +1,25 @@
-# CMDx
+<p align="center">
+  <img src="./src/cmdx-logo.png" width="200" alt="CMDx Logo">
+</p>
 
-[![forthebadge](http://forthebadge.com/images/badges/made-with-ruby.svg)](http://forthebadge.com)
+<p align="center">
+  <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
+  <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">
+  <img alt="License" src="https://img.shields.io/github/license/drexed/cmdx">
+</p>
 
-[![Gem Version](https://badge.fury.io/rb/cmdx.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/cmdx)
-[![CI](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=shields)](http://makeapullrequest.com)
+# CMDx
 
-`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 framework for building maintainable business processes. It simplifies building task objects by offering integrated:
 
-## Installation
+- Flow controls
+- Composable workflows
+- Comprehensive logging
+- Attribute definition
+- Validations and coercions
+- And much more...
 
-**Prerequisites:** This gem requires Ruby `>= 3.1` to be installed.
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -28,83 +37,98 @@ Or install it yourself as:
 
 ## Quick Example
 
+Here's how a quick 3 step process can open up a world of possibilities:
+
 ```ruby
-# Setup task
-class SendWelcomeEmailTask < CMDx::Task
-  use :middleware, CMDx::Middlewares::Timeout, seconds: 5
+# 1. Setup task
+# ---------------------------------
+class AnalyzeMetrics < CMDx::Task
+  register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
 
-  on_success :track_email_delivery!
+  on_success :track_analysis_completion!
 
-  required :user_id, type: :integer, numeric: { min: 1 }
-  optional :template, type: :string, default: "welcome"
+  required :dataset_id, type: :integer, numeric: { min: 1 }
+  optional :analysis_type, default: "standard"
 
-  def call
-    if user.nil?
-      fail!(reason: "User not found", code: 404)
-    elsif user.unconfirmed?
-      skip!(reason: "Email not verified")
+  def work
+    if dataset.nil?
+      fail!("Dataset not found", code: 404)
+    elsif dataset.unprocessed?
+      skip!("Dataset not ready for analysis")
     else
-      response = UserMailer.welcome(user, template).deliver_now
-      context.message_id = response.message_id
+      context.result = PValueAnalyzer.analyze(dataset, analysis_type)
+      context.analyzed_at = Time.now
     end
   end
 
   private
 
-  def user
-    @user ||= User.find_by(id: user_id)
+  def dataset
+    @dataset ||= Dataset.find_by(id: dataset_id)
   end
 
-  def track_email_delivery!
-    user.touch(:welcomed_at)
+  def track_analysis_completion!
+    dataset.update!(analysis_result_id: context.result.id)
   end
 end
 
-# Execute task
-result = SendWelcomeEmailTask.call(user_id: 123, template: "premium_welcome")
+# 2. Execute task
+# ---------------------------------
+result = AnalyzeMetrics.execute(
+  dataset_id: 123,
+  "analysis_type" => "advanced"
+)
 
-# Handle result
+# 3. Handle result
+# ---------------------------------
 if result.success?
-  puts "Welcome email sent <message_id: #{result.context.message_id}>"
+  puts "Metrics analyzed at #{result.context.analyzed_at}"
 elsif result.skipped?
-  puts "Skipped: #{result.metadata[:reason]}"
+  puts "Skipping analyzation due to: #{result.reason}"
 elsif result.failed?
-  puts "Failed: #{result.metadata[:reason]} with code: #{result.metadata[:code]}"
+  puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
 end
 ```
 
 ## Table of contents
 
 - [Getting Started](docs/getting_started.md)
-- [Configuration](docs/configuration.md)
 - Basics
   - [Setup](docs/basics/setup.md)
-  - [Call](docs/basics/call.md)
+  - [Execution](docs/basics/execution.md)
   - [Context](docs/basics/context.md)
   - [Chain](docs/basics/chain.md)
 - Interruptions
   - [Halt](docs/interruptions/halt.md)
   - [Faults](docs/interruptions/faults.md)
   - [Exceptions](docs/interruptions/exceptions.md)
-- Parameters
-  - [Definitions](docs/parameters/definitions.md)
-  - [Namespacing](docs/parameters/namespacing.md)
-  - [Coercions](docs/parameters/coercions.md)
-  - [Validations](docs/parameters/validations.md)
-  - [Defaults](docs/parameters/defaults.md)
 - Outcomes
-  - [Result](#results)
+  - [Result](docs/outcomes/result.md)
   - [States](docs/outcomes/states.md)
   - [Statuses](docs/outcomes/statuses.md)
+- Attributes
+  - [Definitions](docs/attributes/definitions.md)
+  - [Naming](docs/attributes/naming.md)
+  - [Coercions](docs/attributes/coercions.md)
+  - [Validations](docs/attributes/validations.md)
+  - [Defaults](docs/attributes/defaults.md)
 - [Callbacks](docs/callbacks.md)
 - [Middlewares](docs/middlewares.md)
-- [Workflows](docs/workflows.md)
 - [Logging](docs/logging.md)
 - [Internationalization (i18n)](docs/internationalization.md)
-- [Testing](docs/testing.md)
 - [Deprecation](docs/deprecation.md)
-- [AI Prompts](docs/ai_prompts.md)
-- [Tips & Tricks](docs/tips_and_tricks.md)
+- [Workflows](docs/workflows.md)
+- [Tips and Tricks](docs/tips_and_tricks.md)
+
+## Ecosystem
+
+The following gems are currently under development:
+
+- `cmdx-i18n` I18n locales
+- `cmdx-rspec` RSpec matchers
+- `cmdx-minitest` Minitest matchers
+- `cmdx-jobs` Background job integrations
+- `cmdx-parallel` Parallel workflow task execution
 
 ## Development
 

data/docs/attributes/coercions.md

@@ -0,0 +1,162 @@
+# Attributes - Coercions
+
+Attribute coercions automatically convert task arguments to expected types, ensuring type safety while providing flexible input handling. Coercions transform raw input values into the specified types, supporting simple conversions like string-to-integer and complex operations like JSON parsing.
+
+## Table of Contents
+
+- [Usage](#usage)
+- [Built-in Coercions](#built-in-coercions)
+- [Declarations](#declarations)
+  - [Proc or Lambda](#proc-or-lambda)
+  - [Class or Module](#class-or-module)
+- [Removals](#removals)
+- [Error Handling](#error-handling)
+
+## 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
+
+> [!IMPORTANT]
+> Coercions must raise a CMDx::CoercionError and its message is used as part of the fault reason and metadata.
+
+### 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 custom coercions when no longer needed:
+
+> [!WARNING]
+> Only one removal operation is allowed per `deregister` call. Multiple removals require separate calls.
+
+```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   #=> "iterations could not coerce into an integer. score could not coerce into one of: float, big_decimal."
+result.metadata #=> {
+                #     messages: {
+                #       iterations: ["could not coerce into an integer"],
+                #       score: ["could not coerce into one of: float, big_decimal"]
+                #     }
+                #   }
+```
+
+---
+
+- **Prev:** [Attributes - Naming](naming.md)
+- **Next:** [Attributes - Validations](validations.md)

data/docs/attributes/defaults.md

@@ -0,0 +1,90 @@
+# Attributes - Defaults
+
+Attribute defaults provide fallback values when arguments are not provided or resolve to `nil`. Defaults ensure tasks have sensible values for optional attributes while maintaining flexibility for callers to override when needed.
+
+## Table of Contents
+
+- [Declarations](#declarations)
+  - [Static Values](#static-values)
+  - [Symbol References](#symbol-references)
+  - [Proc or Lambda](#proc-or-lambda)
+- [Coercions and Validations](#coercions-and-validations)
+
+## Declarations
+
+Defaults apply when attributes are not provided or resolve to `nil`. They work seamlessly with coercion, validation, 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 are subject to the same coercion and validation rules as provided values, ensuring consistency and catching configuration errors early.
+
+```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
+```
+
+---
+
+- **Prev:** [Attributes - Validations](validations.md)
+- **Next:** [Callbacks](../callbacks.md)

data/docs/attributes/definitions.md

@@ -0,0 +1,281 @@
+# Attributes - Definitions
+
+Attributes define the interface between task callers and implementation, enabling automatic validation, type coercion, and method generation. They provide a contract to verify that task execution arguments match expected requirements and structure.
+
+## Table of Contents
+
+- [Declarations](#declarations)
+  - [Optional](#optional)
+  - [Required](#required)
+- [Sources](#sources)
+  - [Context](#context)
+  - [Symbol References](#symbol-references)
+  - [Proc or Lambda](#proc-or-lambda)
+  - [Class or Module](#class-or-module)
+- [Nesting](#nesting)
+- [Error Handling](#error-handling)
+
+## Declarations
+
+> [!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
+
+  def work
+    title     #=> "Getting Started with Ruby"
+    content   #=> "This is a comprehensive guide..."
+    author_id #=> 42
+    category  #=> "programming"
+    status    #=> :published
+    tags      #=> ["ruby", "beginner"]
+  end
+end
+
+# Attributes passed as keyword arguments
+PublishArticle.execute(
+  title: "Getting Started with Ruby",
+  content: "This is a comprehensive guide...",
+  author_id: 42,
+  category: "programming",
+  status: :published,
+  tags: ["ruby", "beginner"]
+)
+```
+
+## Sources
+
+Attributes delegate to accessible objects within the task. The default source is `:context`, but any accessible method or object can serve as an attribute source.
+
+### 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
+
+Nested attributes enable complex attribute structures where child attributes automatically inherit their parent as the source. This allows validation and access of structured data.
+
+> [!NOTE]
+> All options available to top-level attributes are available to nested attributes, eg: naming, coercions, and validations
+
+```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"
+    }
+  }
+)
+```
+
+> [!IMPORTANT]
+> Child attributes are only required when their parent attribute is provided, enabling flexible optional structures.
+
+## Error Handling
+
+Attribute validation failures result in structured error information with details about each failed attribute.
+
+> [!NOTE]
+> Nested attributes are only ever evaluated when the parent attribute is available 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   #=> "environment is required. network_config is required."
+result.metadata #=> {
+                #     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   #=> "port is required."
+result.metadata #=> {
+                #     messages: {
+                #       port: ["is required"]
+                #     }
+                #   }
+```
+
+---
+
+- **Prev:** [Outcomes - States](../outcomes/states.md)
+- **Next:** [Attributes - Naming](naming.md)