diff --git a/CHANGELOG.md b/CHANGELOG.md index fdb0d158a..8f62dc1cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,15 +2,14 @@ All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [TODO] ## [1.5.0] - 2025-08-21 ### Changes -- !BREAKING! Revamp CMDx for clarity, transparency, and higher performance +- BREAKING - Revamp CMDx for clarity, transparency, and higher performance ## [1.1.2] - 2025-07-20 diff --git a/LLM.md b/LLM.md index cd64adbb6..ec294b700 100644 --- a/LLM.md +++ b/LLM.md @@ -587,6 +587,7 @@ end result = CalculateShipping.execute(destination: "New York, NY") CreateShippingLabel.execute(result) +``` --- @@ -697,6 +698,7 @@ chain.outcome #=> "success" chain.results.each_with_index do |result, index| puts "#{index}: #{result.task.class} - #{result.status}" end +``` --- @@ -1082,23 +1084,27 @@ CMDx provides robust exception handling that differs between the `execute` and ` ## Exception Handling +> [!IMPORTANT] +> When designing tasks, try not to `raise` your own exceptions directly. Instead, use skip! or fail! to signal intent clearly. skip! communicates that the task was intentionally bypassed, while fail! marks it as an expected failure with proper handling. This keeps workflows observable, predictable, and easier to debug. + ### Non-bang execution The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing. ```ruby -class ProcessDocument < CMDx::Task +class CompressDocument < CMDx::Task def work - raise UnsupportedFormat, "document format not supported" + document = Document.find(context.document_id) + document.compress! end end -result = ProcessDocument.execute +result = CompressDocument.execute(document_id: "unknown-doc-id") result.state #=> "interrupted" result.status #=> "failed" result.failed? #=> true -result.reason #=> "[UnsupportedFormat] document format not supported" -result.cause #=> +result.reason #=> "[ActiveRecord::NotFoundError] record not found" +result.cause #=> ``` ### Bang execution @@ -1106,17 +1112,19 @@ result.cause #=> The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration. ```ruby -class ProcessDocument < CMDx::Task +class CompressDocument < CMDx::Task def work - raise UnsupportedFormat, "document format not supported" + document = Document.find(context.document_id) + document.compress! end end begin - ProcessDocument.execute! -rescue UnsupportedFormat => e + CompressDocument.execute!(document_id: "unknown-doc-id") +rescue ActiveRecord::NotFoundError => e puts "Handle exception: #{e.message}" end +``` --- @@ -1371,6 +1379,7 @@ result .on_complete { |result| send_upload_notification(result) } .on_interrupted { |result| cleanup_temp_files(result) } .on_executed { |result| log_upload_metrics(result) } +``` --- @@ -1440,6 +1449,7 @@ result result .on_good { |result| update_message_stats(result) } .on_bad { |result| track_delivery_failure(result) } +``` --- @@ -1780,6 +1790,7 @@ end # Attributes passed as original attribute names ScheduleMaintenance.execute(scheduled_at: DateTime.new(2024, 12, 15, 2, 0, 0)) +``` --- diff --git a/docs/interruptions/exceptions.md b/docs/interruptions/exceptions.md index f6f0a56f6..d0b905500 100644 --- a/docs/interruptions/exceptions.md +++ b/docs/interruptions/exceptions.md @@ -10,23 +10,27 @@ CMDx provides robust exception handling that differs between the `execute` and ` ## Exception Handling +> [!IMPORTANT] +> When designing tasks, try not to `raise` your own exceptions directly. Instead, use skip! or fail! to signal intent clearly. skip! communicates that the task was intentionally bypassed, while fail! marks it as an expected failure with proper handling. This keeps workflows observable, predictable, and easier to debug. + ### Non-bang execution The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing. ```ruby -class ProcessDocument < CMDx::Task +class CompressDocument < CMDx::Task def work - raise UnsupportedFormat, "document format not supported" + document = Document.find(context.document_id) + document.compress! end end -result = ProcessDocument.execute +result = CompressDocument.execute(document_id: "unknown-doc-id") result.state #=> "interrupted" result.status #=> "failed" result.failed? #=> true -result.reason #=> "[UnsupportedFormat] document format not supported" -result.cause #=> +result.reason #=> "[ActiveRecord::NotFoundError] record not found" +result.cause #=> ``` ### Bang execution @@ -34,15 +38,16 @@ result.cause #=> The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration. ```ruby -class ProcessDocument < CMDx::Task +class CompressDocument < CMDx::Task def work - raise UnsupportedFormat, "document format not supported" + document = Document.find(context.document_id) + document.compress! end end begin - ProcessDocument.execute! -rescue UnsupportedFormat => e + CompressDocument.execute!(document_id: "unknown-doc-id") +rescue ActiveRecord::NotFoundError => e puts "Handle exception: #{e.message}" end ```