cmdx 1.13.0 → 1.14.0

data/docs/getting_started.md

@@ -1,137 +0,0 @@
-# Getting Started
-
-CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. It brings structure, consistency, and powerful developer tools to your business processes.
-
-**Common challenges:**
-
-- Inconsistent service object patterns across your codebase
-- Black boxes make debugging a nightmare
-- Fragile error handling erodes confidence
-
-**What you get:**
-
-- Consistent, standardized architecture
-- Built-in flow control and error handling
-- Composable, reusable workflows
-- Comprehensive logging for observability
-- Attribute validation with type coercions
-- Sensible defaults and developer-friendly APIs
-
-## Installation
-
-Add CMDx to your Gemfile:
-
-```sh
-gem install cmdx
-
-# - or -
-
-bundle add cmdx
-```
-
-## Configuration
-
-For Rails applications, run the following command to generate a global configuration file in `config/initializers/cmdx.rb`.
-
-```bash
-rails generate cmdx:install
-```
-
-If not using Rails, manually copy the [configuration file](https://github.com/drexed/cmdx/blob/main/lib/generators/cmdx/templates/install.rb).
-
-## The CERO Pattern
-
-CMDx embraces the Compose, Execute, React, Observe (CERO, pronounced "zero") pattern—a simple yet powerful approach to building reliable business logic.
-
-```mermaid
-flowchart LR
-    Compose --> Execute
-    Execute --> React
-    Execute -.-> Observe
-```
-
-### Compose
-
-Build reusable, single-responsibility tasks with typed attributes, validation, and callbacks. Tasks can be chained together in workflows to create complex business processes from simple building blocks.
-
-```ruby
-class AnalyzeMetrics < CMDx::Task
-  def work
-    # Your logic here...
-  end
-end
-```
-
-### Execute
-
-Invoke tasks with a consistent API that always returns a result object. Execution automatically handles validation, type coercion, error handling, and logging. Arguments are validated and coerced before your task logic runs.
-
-```ruby
-# Without args
-result = AnalyzeMetrics.execute
-
-# With args
-result = AnalyzeMetrics.execute(model: "blackbox", "sensitivity" => 3)
-```
-
-### React
-
-Every execution returns a result object with a clear outcome. Check the result's state (`success?`, `failed?`, `skipped?`) and access returned values, error messages, and metadata to make informed decisions.
-
-```ruby
-if result.success?
-  # Handle success
-elsif result.skipped?
-  # Handle skipped
-elsif result.failed?
-  # Handle failed
-end
-```
-
-### Observe
-
-Every task execution generates structured logs with execution chains, runtime metrics, and contextual metadata. Logs can be automatically correlated using chain IDs, making it easy to trace complex workflows and debug issues.
-
-```log
-I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
-index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
-
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
-```
-
-!!! note
-
-    This represents a log-only event-sourcing approach, enabling full traceability and a complete, time-ordered view of system behavior.
-
-## Task Generator
-
-Generate new CMDx tasks quickly using the built-in generator:
-
-```bash
-rails generate cmdx:task ModerateBlogPost
-```
-
-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`
-
-## Type safety
-
-CMDx includes built-in RBS (Ruby Type Signature) inline annotations throughout the codebase, providing type information for static analysis and editor support.
-
-- **Type checking** — Catch type errors before runtime using tools like Steep or TypeProf
-- **Better IDE support** — Enhanced autocomplete, navigation, and inline documentation
-- **Self-documenting code** — Clear method signatures and return types
-- **Refactoring confidence** — Type-aware refactoring reduces bugs

data/docs/index.md

@@ -1,134 +0,0 @@
-# CMDx
-
-Build business logic that's powerful, predictable, and maintainable.
-
-[![Version](https://img.shields.io/gem/v/cmdx)](https://rubygems.org/gems/cmdx)
-[![Build](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
-[![License](https://img.shields.io/github/license/drexed/cmdx)](https://github.com/drexed/cmdx/blob/main/LICENSE.txt)
-
----
-
-Say goodbye to messy service objects. CMDx (pronounced "Command X") helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
-
-!!! note
-
-    Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
-
-## Requirements
-
-- Ruby: MRI 3.1+ or JRuby 9.4+.
-
-CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
-
-## Installation
-
-```sh
-gem install cmdx
-
-# - or -
-
-bundle add cmdx
-```
-
-## Quick Example
-
-Build powerful business logic in four simple steps:
-
-### 1. Compose
-
-=== "Full Featured Task"
-
-    ```ruby
-    class AnalyzeMetrics < CMDx::Task
-      register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
-
-      on_success :track_analysis_completion!
-
-      required :dataset_id, type: :integer, numeric: { min: 1 }
-      optional :analysis_type, default: "standard"
-
-      def work
-        if dataset.nil?
-          fail!("Dataset not found", code: 404)
-        elsif dataset.unprocessed?
-          skip!("Dataset not ready for analysis")
-        else
-          context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
-          context.analyzed_at = Time.now
-
-          SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
-        end
-      end
-
-      private
-
-      def dataset
-        @dataset ||= Dataset.find_by(id: dataset_id)
-      end
-
-      def track_analysis_completion!
-        dataset.update!(analysis_result_id: context.result.id)
-      end
-    end
-    ```
-
-=== "Minimum Viable Task"
-
-    ```ruby
-    class SendAnalyzedEmail < CMDx::Task
-      def work
-        user = User.find(context.user_id)
-        MetricsMailer.analyzed(user).deliver_now
-      end
-    end
-    ```
-
-### 2. Execute
-
-```ruby
-result = AnalyzeMetrics.execute(
-  dataset_id: 123,
-  "analysis_type" => "advanced"
-)
-```
-
-### 3. React
-
-```ruby
-if result.success?
-  puts "Metrics analyzed at #{result.context.analyzed_at}"
-elsif result.skipped?
-  puts "Skipping analyzation due to: #{result.reason}"
-elsif result.failed?
-  puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
-end
-```
-
-### 4. Observe
-
-```log
-I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
-index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
-
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
-```
-
-Ready to dive in? Check out the [Getting Started](getting_started.md) guide to learn more.
-
-## Ecosystem
-
-- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
-
-For backwards compatibility of certain functionality:
-
-- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations, `v1.5.0` - `v1.6.2`
-- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks, `v1.6.1` - `v1.6.2`
-
-## Contributing
-
-Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](https://github.com/drexed/cmdx/blob/main/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/internationalization.md

@@ -1,126 +0,0 @@
-# Internationalization (i18n)
-
-CMDx supports 90+ languages out of the box for all error messages, validations, coercions, and faults. Error messages automatically adapt to the current `I18n.locale`, making it easy to build applications for global audiences.
-
-## Usage
-
-All error messages are automatically localized based on your current locale:
-
-```ruby
-class ProcessQuote < CMDx::Task
-  attribute :price, type: :float
-
-  def work
-    # Your logic here...
-  end
-end
-
-I18n.with_locale(:fr) do
-  result = ProcessQuote.execute(price: "invalid")
-  result.metadata[:messages][:price] #=> ["impossible de contraindre en float"]
-end
-```
-
-## Configuration
-
-CMDx uses the `I18n` gem for localization. In Rails, locales load automatically.
-
-### Copy Locale Files
-
-Copy locale files to your Rails application's `config/locales` directory:
-
-```bash
-rails generate cmdx:locale [LOCALE]
-
-# Eg: generate french locale
-rails generate cmdx:locale fr
-```
-
-### Available Locales
-
-- af - Afrikaans
-- ar - Arabic
-- az - Azerbaijani
-- be - Belarusian
-- bg - Bulgarian
-- bn - Bengali
-- bs - Bosnian
-- ca - Catalan
-- cnr - Montenegrin
-- cs - Czech
-- cy - Welsh
-- da - Danish
-- de - German
-- dz - Dzongkha
-- el - Greek
-- en - English
-- eo - Esperanto
-- es - Spanish
-- et - Estonian
-- eu - Basque
-- fa - Persian
-- fi - Finnish
-- fr - French
-- fy - Western Frisian
-- gd - Scottish Gaelic
-- gl - Galician
-- he - Hebrew
-- hi - Hindi
-- hr - Croatian
-- hu - Hungarian
-- hy - Armenian
-- id - Indonesian
-- is - Icelandic
-- it - Italian
-- ja - Japanese
-- ka - Georgian
-- kk - Kazakh
-- km - Khmer
-- kn - Kannada
-- ko - Korean
-- lb - Luxembourgish
-- lo - Lao
-- lt - Lithuanian
-- lv - Latvian
-- mg - Malagasy
-- mk - Macedonian
-- ml - Malayalam
-- mn - Mongolian
-- mr-IN - Marathi (India)
-- ms - Malay
-- nb - Norwegian Bokmål
-- ne - Nepali
-- nl - Dutch
-- nn - Norwegian Nynorsk
-- oc - Occitan
-- or - Odia
-- pa - Punjabi
-- pl - Polish
-- pt - Portuguese
-- rm - Romansh
-- ro - Romanian
-- ru - Russian
-- sc - Sardinian
-- sk - Slovak
-- sl - Slovenian
-- sq - Albanian
-- sr - Serbian
-- st - Southern Sotho
-- sv - Swedish
-- sw - Swahili
-- ta - Tamil
-- te - Telugu
-- th - Thai
-- tl - Tagalog
-- tr - Turkish
-- tt - Tatar
-- ug - Uyghur
-- uk - Ukrainian
-- ur - Urdu
-- uz - Uzbek
-- vi - Vietnamese
-- wo - Wolof
-- zh-CN - Chinese (Simplified)
-- zh-HK - Chinese (Hong Kong)
-- zh-TW - Chinese (Traditional)
-- zh-YUE - Chinese (Yue)

data/docs/interruptions/exceptions.md

@@ -1,52 +0,0 @@
-# Interruptions - Exceptions
-
-Exception handling differs between `execute` and `execute!`. Choose the method that matches your error handling strategy.
-
-## Exception Handling
-
-!!! warning "Important"
-
-    Prefer `skip!` and `fail!` over raising exceptions—they signal intent more clearly.
-
-### Non-bang execution
-
-Captures all exceptions and returns them as failed results:
-
-```ruby
-class CompressDocument < CMDx::Task
-  def work
-    document = Document.find(context.document_id)
-    document.compress!
-  end
-end
-
-result = CompressDocument.execute(document_id: "unknown-doc-id")
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.failed?  #=> true
-result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
-result.cause    #=> <ActiveRecord::NotFoundError>
-```
-
-!!! note
-
-    Use `exception_handler` with `execute` to send exceptions to APM tools before they become failed results.
-
-### Bang execution
-
-Lets exceptions propagate naturally for standard Ruby error handling:
-
-```ruby
-class CompressDocument < CMDx::Task
-  def work
-    document = Document.find(context.document_id)
-    document.compress!
-  end
-end
-
-begin
-  CompressDocument.execute!(document_id: "unknown-doc-id")
-rescue ActiveRecord::NotFoundError => e
-  puts "Handle exception: #{e.message}"
-end
-```

data/docs/interruptions/faults.md

@@ -1,169 +0,0 @@
-# Interruptions - Faults
-
-Faults are exceptions raised by `execute!` when tasks halt. They carry rich context about execution state, enabling sophisticated error handling patterns.
-
-## Fault Types
-
-| Type | Triggered By | Use Case |
-|------|--------------|----------|
-| `CMDx::Fault` | Base class | Catch-all for any interruption |
-| `CMDx::SkipFault` | `skip!` method | Optional processing, early returns |
-| `CMDx::FailFault` | `fail!` method | Validation errors, processing failures |
-
-!!! warning "Important"
-
-    All faults inherit from `CMDx::Fault` and expose result, task, context, and chain data.
-
-## Fault Handling
-
-```ruby
-begin
-  ProcessTicket.execute!(ticket_id: 456)
-rescue CMDx::SkipFault => e
-  logger.info "Ticket processing skipped: #{e.message}"
-  schedule_retry(e.context.ticket_id)
-rescue CMDx::FailFault => e
-  logger.error "Ticket processing failed: #{e.message}"
-  notify_admin(e.context.assigned_agent, e.result.metadata[:error_code])
-rescue CMDx::Fault => e
-  logger.warn "Ticket processing interrupted: #{e.message}"
-  rollback_changes
-end
-```
-
-## Data Access
-
-Access rich execution data from fault exceptions:
-
-```ruby
-begin
-  LicenseActivation.execute!(license_key: key, machine_id: machine)
-rescue CMDx::Fault => e
-  # Result information
-  e.result.state     #=> "interrupted"
-  e.result.status    #=> "failed" or "skipped"
-  e.result.reason    #=> "License key already activated"
-
-  # Task information
-  e.task.class       #=> <LicenseActivation>
-  e.task.id          #=> "abc123..."
-
-  # Context data
-  e.context.license_key #=> "ABC-123-DEF"
-  e.context.machine_id  #=> "[FILTERED]"
-
-  # Chain information
-  e.chain.id         #=> "def456..."
-  e.chain.size       #=> 3
-end
-```
-
-## Advanced Matching
-
-### Task-Specific Matching
-
-Handle faults only from specific tasks using `for?`:
-
-```ruby
-begin
-  DocumentWorkflow.execute!(document_data: data)
-rescue CMDx::FailFault.for?(FormatValidator, ContentProcessor) => e
-  # Handle only document-related failures
-  retry_with_alternate_parser(e.context)
-rescue CMDx::SkipFault.for?(VirusScanner, ContentFilter) => e
-  # Handle security-related skips
-  quarantine_for_review(e.context.document_id)
-end
-```
-
-### Custom Logic Matching
-
-```ruby
-begin
-  ReportGenerator.execute!(report: report_data)
-rescue CMDx::Fault.matches? { |f| f.context.data_size > 10_000 } => e
-  escalate_large_dataset_failure(e)
-rescue CMDx::FailFault.matches? { |f| f.result.metadata[:attempt_count] > 3 } => e
-  abandon_report_generation(e)
-rescue CMDx::Fault.matches? { |f| f.result.metadata[:error_type] == "memory" } => e
-  increase_memory_and_retry(e)
-end
-```
-
-## Fault Propagation
-
-Propagate failures with `throw!` to preserve context and maintain the error chain:
-
-### Basic Propagation
-
-```ruby
-class ReportGenerator < CMDx::Task
-  def work
-    # Throw if skipped or failed
-    validation_result = DataValidator.execute(context)
-    throw!(validation_result)
-
-    # Only throw if skipped
-    check_permissions = CheckPermissions.execute(context)
-    throw!(check_permissions) if check_permissions.skipped?
-
-    # Only throw if failed
-    data_result = DataProcessor.execute(context)
-    throw!(data_result) if data_result.failed?
-
-    # Continue processing
-    generate_report
-  end
-end
-```
-
-### Additional Metadata
-
-```ruby
-class BatchProcessor < CMDx::Task
-  def work
-    step_result = FileValidation.execute(context)
-
-    if step_result.failed?
-      throw!(step_result, {
-        batch_stage: "validation",
-        can_retry: true,
-        next_step: "file_repair"
-      })
-    end
-
-    continue_batch
-  end
-end
-```
-
-## Chain Analysis
-
-Trace fault origins and propagation through the execution chain:
-
-```ruby
-result = DocumentWorkflow.execute(invalid_data)
-
-if result.failed?
-  # Trace the original failure
-  original = result.caused_failure
-  if original
-    puts "Original failure: #{original.task.class.name}"
-    puts "Reason: #{original.reason}"
-  end
-
-  # Find what propagated the failure
-  thrower = result.threw_failure
-  puts "Propagated by: #{thrower.task.class.name}" if thrower
-
-  # Analyze failure type
-  case
-  when result.caused_failure?
-    puts "This task was the original source"
-  when result.threw_failure?
-    puts "This task propagated a failure"
-  when result.thrown_failure?
-    puts "This task failed due to propagation"
-  end
-end
-```