cmdx 1.8.0 → 1.9.1

data/README.md

@@ -1,68 +1,49 @@
-<p align="center">
-  <img src="./src/cmdx-logo.png" width="200" alt="CMDx Logo">
-</p>
+<div align="center">
+  <img src="./src/cmdx-light-logo.png#gh-light-mode-only" width="200" alt="CMDx Logo">
+  <img src="./src/cmdx-dark-logo.png#gh-dark-mode-only" width="200" alt="CMDx Logo">
+
+  ---
+
+  Build business logic that’s powerful, predictable, and maintainable.
+
+  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues)
 
-<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>
+</div>
 
-# 🚀 CMDx — Business logic without the chaos
+# CMDx
 
-Stop wrestling with messy service objects. CMDx gives you a clean, consistent way to design business processes:
+Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
-- Start small with a single `work` method
-- Scale to complex tasks and multi-step workflows
-- Get built-in flow control, logging, validations, and more...
+> [!NOTE]
+> Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
 
-*Build faster. Debug easier. Stay sane.*
+## Requirements
 
-## Compose, Execute, React, Observe pattern
+- Ruby: MRI 3.1+ or JRuby 9.4+.
 
-CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
-
-- **Compose** → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
-- **Execute** → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
-- **React** → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
-- **Observe** → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
+CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'cmdx'
+```sh
+gem install cmdx
+# - or -
+bundle add cmdx
 ```
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install cmdx
-
 ## Quick Example
 
-Here's how a quick 4 step process can open up a world of possibilities:
+Build powerful business logic in four simple steps:
 
 ### 1. Compose
 
-#### Minimum Viable Task
-
 ```ruby
-class SendAnalyzedEmail < CMDx::Task
-  def work
-    user = User.find(context.user_id)
-    MetricsMailer.analyzed(user).deliver_now
-  end
-end
-```
-
-#### Fully Featured Task
+# Full-featured task example
+# See docs for minimum viable task examples
 
-```ruby
 class AnalyzeMetrics < CMDx::Task
   register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
 
@@ -127,35 +108,7 @@ 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}
 ```
 
-## Table of contents
-
-- [Getting Started](docs/getting_started.md)
-- Basics
-  - [Setup](docs/basics/setup.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)
-- Outcomes
-  - [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)
-- [Logging](docs/logging.md)
-- [Internationalization (i18n)](docs/internationalization.md)
-- [Deprecation](docs/deprecation.md)
-- [Workflows](docs/workflows.md)
-- [Tips and Tricks](docs/tips_and_tricks.md)
+Ready to dive in? Check out the [Getting Started](https://drexed.github.io/cmdx/getting_started/) guide to learn more.
 
 ## Ecosystem
 
@@ -166,20 +119,10 @@ 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`
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/drexed/cmdx. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+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](CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the CMDx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/docs/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="1000" height="1000"><g clip-path="url(#SvgjsClipPath1038)"><rect width="1000" height="1000" fill="#ffffff"></rect><g transform="matrix(6.235191420376605,0,0,6.235191420376605,175.46452176081812,150)"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="104.098" height="112.266"><svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"></path></svg></svg></g></g><defs><clipPath id="SvgjsClipPath1038"><rect width="1000" height="1000" x="0" y="0" rx="150" ry="150"></rect></clipPath></defs></svg>

data/docs/attributes/coercions.md

@@ -1,18 +1,8 @@
 # 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.
+Automatically convert inputs to expected types. Coercions handle everything from simple string-to-integer conversions to JSON parsing.
 
-Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#coercions) docs for global configuration.
-
-## 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)
+See [Global Configuration](../getting_started.md#coercions) for custom coercion setup.
 
 ## Usage
 
@@ -43,8 +33,9 @@ ParseMetrics.execute(
 )
 ```
 
-> [!TIP]
-> Specify multiple coercion types for attributes that could be a variety of value formats. CMDx attempts each type in order until one succeeds.
+!!! 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
 
@@ -66,8 +57,9 @@ ParseMetrics.execute(
 
 ## Declarations
 
-> [!IMPORTANT]
-> Coercions must raise a CMDx::CoercionError and its message is used as part of the fault reason and metadata.
+!!! warning "Important"
+
+    Custom coercions must raise `CMDx::CoercionError` with a descriptive message.
 
 ### Proc or Lambda
 
@@ -117,10 +109,11 @@ end
 
 ## Removals
 
-Remove custom coercions when no longer needed:
+Remove unwanted coercions:
 
-> [!WARNING]
-> Only one removal operation is allowed per `deregister` call. Multiple removals require separate calls.
+!!! warning
+
+    Each `deregister` call removes one coercion. Use multiple calls for batch removals.
 
 ```ruby
 class TransformCoordinates < CMDx::Task
@@ -160,8 +153,3 @@ result.metadata #=> {
                 #     }
                 #   }
 ```
-
----
-
-- **Prev:** [Attributes - Naming](naming.md)
-- **Next:** [Attributes - Validations](validations.md)

data/docs/attributes/defaults.md

@@ -1,18 +1,10 @@
 # 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)
+Provide fallback values for optional attributes. Defaults kick in when values aren't provided or are `nil`.
 
 ## Declarations
 
-Defaults apply when attributes are not provided or resolve to `nil`. They work seamlessly with coercion, validation, and nested attributes.
+Defaults work seamlessly with coercions, validations, and nested attributes:
 
 ### Static Values
 
@@ -72,7 +64,7 @@ end
 
 ## Coercions and Validations
 
-Defaults are subject to the same coercion and validation rules as provided values, ensuring consistency and catching configuration errors early.
+Defaults follow the same coercion and validation rules as provided values:
 
 ```ruby
 class ScheduleBackup < CMDx::Task
@@ -83,8 +75,3 @@ class ScheduleBackup < CMDx::Task
   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

@@ -1,24 +1,12 @@
 # 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)
+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
 
-> [!TIP]
-> Prefer using the `required` and `optional` alias for `attributes` for brevity and to clearly signal intent.
+!!! tip
+
+    Prefer using the `required` and `optional` alias for `attributes` for brevity and to clearly signal intent.
 
 ### Optional
 
@@ -87,7 +75,7 @@ PublishArticle.execute(
 
 ## 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.
+Attributes read from any accessible object—not just context. Use sources to pull data from models, services, or any callable:
 
 ### Context
 
@@ -167,10 +155,11 @@ 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.
+Build complex structures with nested attributes. Children inherit their parent as source and support all attribute options:
+
+!!! note
 
-> [!NOTE]
-> All options available to top-level attributes are available to nested attributes, eg: naming, coercions, and validations
+    Nested attributes support all features: naming, coercions, validations, defaults, and more.
 
 ```ruby
 class ConfigureServer < CMDx::Task
@@ -223,15 +212,17 @@ ConfigureServer.execute(
 )
 ```
 
-> [!IMPORTANT]
-> Child attributes are only required when their parent attribute is provided, enabling flexible optional structures.
+!!! warning "Important"
+
+    Child requirements only apply when the parent is provided—perfect for optional structures.
 
 ## Error Handling
 
-Attribute validation failures result in structured error information with details about each failed attribute.
+Validation failures provide detailed, structured error messages:
+
+!!! note
 
-> [!NOTE]
-> Nested attributes are only ever evaluated when the parent attribute is available and valid.
+    Nested attributes are only validated when their parent is present and valid.
 
 ```ruby
 class ConfigureServer < CMDx::Task
@@ -280,8 +271,3 @@ result.metadata #=> {
                 #     }
                 #   }
 ```
-
----
-
-- **Prev:** [Outcomes - States](../outcomes/states.md)
-- **Next:** [Attributes - Naming](naming.md)

data/docs/attributes/naming.md

@@ -1,15 +1,10 @@
 # Attributes - Naming
 
-Attribute naming provides method name customization to prevent conflicts and enable flexible attribute access patterns. When attributes share names with existing methods or when multiple attributes from different sources have the same name, affixing ensures clean method resolution within tasks.
+Customize accessor method names to avoid conflicts and improve clarity. Affixing changes only the generated methods—not the original attribute names.
 
-> [!NOTE]
-> Affixing modifies only the generated accessor method names within tasks.
+!!! note
 
-## Table of Contents
-
-- [Prefix](#prefix)
-- [Suffix](#suffix)
-- [As](#as)
+    Use naming when attributes conflict with existing methods or need better clarity in your code.
 
 ## Prefix
 
@@ -71,8 +66,3 @@ end
 # Attributes passed as original attribute names
 ScheduleMaintenance.execute(scheduled_at: DateTime.new(2024, 12, 15, 2, 0, 0))
 ```
-
----
-
-- **Prev:** [Attributes - Definitions](definitions.md)
-- **Next:** [Attributes - Coercions](coercions.md)

data/docs/attributes/transformations.md

@@ -0,0 +1,63 @@
+# 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,25 +1,8 @@
 # Attributes - Validations
 
-Attribute validations ensure task arguments meet specified requirements before execution begins. Validations run after coercions and provide declarative rules for data integrity, supporting both built-in validators and custom validation logic.
-
-Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#validations) docs for global configuration.
-
-## Table of Contents
-
-- [Usage](#usage)
-- [Built-in Validators](#built-in-validators)
-  - [Common Options](#common-options)
-  - [Exclusion](#exclusion)
-  - [Format](#format)
-  - [Inclusion](#inclusion)
-  - [Length](#length)
-  - [Numeric](#numeric)
-  - [Presence](#presence)
-- [Declarations](#declarations)
-  - [Proc or Lambda](#proc-or-lambda)
-  - [Class or Module](#class-or-module)
-- [Removals](#removals)
-- [Error Handling](#error-handling)
+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
 
@@ -55,8 +38,9 @@ ProcessSubscription.execute(
 )
 ```
 
-> [!TIP]
-> Validations run after coercions, so you can validate the final coerced values rather than raw input.
+!!! tip
+
+    Validations run after coercions, so you can validate the final coerced values rather than raw input.
 
 ## Built-in Validators
 
@@ -211,8 +195,9 @@ end
 
 ## Declarations
 
-> [!IMPORTANT]
-> Custom validators must raise a `CMDx::ValidationError` and its message is used as part of the fault reason and metadata.
+!!! warning "Important"
+
+    Custom validators must raise `CMDx::ValidationError` with a descriptive message.
 
 ### Proc or Lambda
 
@@ -258,10 +243,11 @@ end
 
 ## Removals
 
-Remove custom validators when no longer needed:
+Remove unwanted validators:
 
-> [!WARNING]
-> Only one removal operation is allowed per `deregister` call. Multiple removals require separate calls.
+!!! warning
+
+    Each `deregister` call removes one validator. Use multiple calls for batch removals.
 
 ```ruby
 class SetupApplication < CMDx::Task
@@ -271,7 +257,7 @@ end
 
 ## Error Handling
 
-Validation failures provide detailed error information including attribute paths, validation rules, and specific failure reasons:
+Validation failures provide detailed, structured error messages:
 
 ```ruby
 class CreateProject < CMDx::Task
@@ -307,8 +293,3 @@ result.metadata #=> {
                 #     }
                 #   }
 ```
-
----
-
-- **Prev:** [Attributes - Coercions](coercions.md)
-- **Next:** [Attributes - Defaults](defaults.md)

data/docs/basics/chain.md

@@ -1,20 +1,14 @@
 # Basics - Chain
 
-Chains automatically group related task executions within a thread, providing unified tracking, correlation, and execution context management. Each thread maintains its own chain through thread-local storage, eliminating the need for manual coordination.
-
-## Table of Contents
-
-- [Management](#management)
-- [Links](#links)
-- [Inheritance](#inheritance)
-- [Structure](#structure)
+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 chain context through thread-local storage, providing automatic isolation without manual coordination.
+Each thread maintains its own isolated chain using thread-local storage.
 
-> [!WARNING]
-> Chain operations are thread-local. Never share chain references across threads as this can lead to race conditions and data corruption.
+!!! warning
+
+    Chains are thread-local. Don't share chain references across threads—it causes race conditions.
 
 ```ruby
 # Thread A
@@ -36,10 +30,11 @@ CMDx::Chain.clear    #=> Clears current thread's chain
 
 ## Links
 
-Every task execution automatically creates or joins the current thread's chain:
+Tasks automatically create or join the current thread's chain:
+
+!!! warning "Important"
 
-> [!IMPORTANT]
-> Chain creation is automatic and transparent. You don't need to manually manage chain lifecycle.
+    Chain management is automatic—no manual lifecycle handling needed.
 
 ```ruby
 class ImportDataset < CMDx::Task
@@ -62,7 +57,7 @@ end
 
 ## Inheritance
 
-When tasks call subtasks within the same thread, all executions automatically inherit the current chain, creating a unified execution trail.
+Subtasks automatically inherit the current thread's chain, building a unified execution trail:
 
 ```ruby
 class ImportDataset < CMDx::Task
@@ -87,10 +82,11 @@ chain.results.map { |r| r.task.class }
 
 ## Structure
 
-Chains provide comprehensive execution information with state delegation:
+Chains expose comprehensive execution information:
 
-> [!IMPORTANT]
-> Chain state always reflects the first (outer-most) task result, not individual subtask outcomes. Subtasks maintain their own success/failure states.
+!!! warning "Important"
+
+    Chain state reflects the first (outermost) task result. Subtasks maintain their own states.
 
 ```ruby
 result = ImportDataset.execute(dataset_id: 456)
@@ -110,8 +106,3 @@ chain.results.each_with_index do |result, index|
   puts "#{index}: #{result.task.class} - #{result.status}"
 end
 ```
-
----
-
-- **Prev:** [Basics - Context](context.md)
-- **Next:** [Interruptions - Halt](../interruptions/halt.md)