cmdx 1.12.0 → 1.14.0

data/docs/deprecation.md

@@ -1,145 +0,0 @@
-# Task Deprecation
-
-Manage legacy tasks gracefully with built-in deprecation support. Choose how to handle deprecated tasks—log warnings for awareness, issue Ruby warnings for development, or prevent execution entirely.
-
-## Modes
-
-### Raise
-
-Prevent task execution completely. Perfect for tasks that must no longer run.
-
-!!! warning
-
-    Use `:raise` mode carefully—it will break existing workflows immediately.
-
-```ruby
-class ProcessObsoleteAPI < CMDx::Task
-  settings(deprecated: :raise)
-
-  def work
-    # Will never execute...
-  end
-end
-
-result = ProcessObsoleteAPI.execute
-#=> raises CMDx::DeprecationError: "ProcessObsoleteAPI usage prohibited"
-```
-
-### Log
-
-Allow execution while tracking deprecation in logs. Ideal for gradual migrations.
-
-```ruby
-class ProcessLegacyFormat < CMDx::Task
-  settings(deprecated: :log)
-
-  # Same
-  settings(deprecated: true)
-
-  def work
-    # Executes but logs deprecation warning...
-  end
-end
-
-result = ProcessLegacyFormat.execute
-result.successful? #=> true
-
-# Deprecation warning appears in logs:
-# WARN -- : DEPRECATED: ProcessLegacyFormat - migrate to replacement or discontinue use
-```
-
-### Warn
-
-Issue Ruby warnings visible during development and testing. Keeps production logs clean while alerting developers.
-
-```ruby
-class ProcessOldData < CMDx::Task
-  settings(deprecated: :warn)
-
-  def work
-    # Executes but emits Ruby warning...
-  end
-end
-
-result = ProcessOldData.execute
-result.successful? #=> true
-
-# Ruby warning appears in stderr:
-# [ProcessOldData] DEPRECATED: migrate to a replacement or discontinue use
-```
-
-## Declarations
-
-### Symbol or String
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Symbol
-  settings(deprecated: :raise)
-
-  # String
-  settings(deprecated: "warn")
-end
-```
-
-### Boolean or Nil
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Deprecates with default :log mode
-  settings(deprecated: true)
-
-  # Skips deprecation
-  settings(deprecated: false)
-  settings(deprecated: nil)
-end
-```
-
-### Method
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Symbol
-  settings(deprecated: :deprecated?)
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def deprecated?
-    Time.now.year > 2024 ? :raise : false
-  end
-end
-```
-
-### Proc or Lambda
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Proc
-  settings(deprecated: proc { Rails.env.development? ? :raise : :log })
-
-  # Lambda
-  settings(deprecated: -> { Current.tenant.legacy_mode? ? :warn : :raise })
-end
-```
-
-### Class or Module
-
-```ruby
-class OutdatedTaskDeprecator
-  def call(task)
-    task.class.name.include?("Outdated")
-  end
-end
-
-class OutdatedConnector < CMDx::Task
-  # Class or Module
-  settings(deprecated: OutdatedTaskDeprecator)
-
-  # Instance
-  settings(deprecated: OutdatedTaskDeprecator.new)
-end
-```

data/docs/getting_started.md

@@ -1,126 +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.
-
-### 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}
-```
-
-## 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
-```