cmdx 1.12.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dffef0df3a8abb190fc0ca6a194383614fdd81f3eebf22ecab59d8ec047d1d7
-  data.tar.gz: 0f38ccaa12a07c41b64fb4fd3f0685bafb45b7de0b3830243f85a53de4d331c4
+  metadata.gz: 620c2c00dd483c6a4122c7b5acbbe6cf7a07d22260d0331d6f1d54b571ef7648
+  data.tar.gz: aff47b340a77b052bc4cd2e201068044a443c1d8f4609163fa45025bdba25d00
 SHA512:
-  metadata.gz: 8649dadb0908d88f7441b80d6e3dce03e7f0d20095216d8ac24cc0bf8b1446f57b4552f021a324f47d860112e431b531695a5cd78e84a4b2cf0c3be0dff1224e
-  data.tar.gz: 5e88be6d5a3070d75abbbcb20e25d900db3a44f011f71ed55c61f748cda77e9be4297f12829ab9f28daac66a4b2c511725318ae4e1455793eef8b8f806c3864c
+  metadata.gz: a8f6fec277ff0198937013c25a1a1c753d4cf5100ff4920c834dc92fba8df7d2adc1ef3fbcff91c999f1af8c4676c3e8702c71a29a3402efcf36d4a0236163ba
+  data.tar.gz: 2233517633c8d9afaafb7a44878b6b3fe0939dabcbe647ceafd9e7ca04450ee1e5e9f6b6f5adb2de58c305b0c2c0940e74ee2d7290f0eb202bda429d76b66992

data/CHANGELOG.md

@@ -4,166 +4,183 @@ 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).
 
-## [UNRELEASED]
+## [Unreleased]
 
-## [1.12.0] - 2025-12-18
+### Added
+- Add Ruby 4.0 compatibility
+- Add `Context#clear!` method to remove all context data
+- Add `Task.attribute_schema` class method for attribute introspection
+- Add `#to_h` method for attribute serialization
+
+### Changed
+- **BREAKING**: Switch license from MIT to LGPLv3
+- Replace `instance_eval` with `define_singleton_method` for attribute method definitions
+- Move retry count from metadata to result object
+- Exclude non-essential files from gem package
+
+### Removed
+- Remove public `Result#rolled_back!` method to hide internal implementation
+
+## [1.13.0] - 2025-12-23
 
 ### Added
-- Added active record database transaction example
-- Added Sentry error tracking example
-- Added Redis idempotency example
-- Added Flipper feature flag example
-
-### Updated
-- Remove `handle_*` methods and provide `on(*states_or_statuses)` method for more flexibility
-- Optimize logging ancestor lookup
-- Use chop instead of range for better string performance
-- Update boolean coercion `TRUTHY` and `FALSEY` regexp to be case insensitive
-- Improve YARD documentation with `yard-lint`
+- Add rollback tracking and logging for task execution
+- Add `dry_run` execution option with inheritance support for nested tasks
+- Add `Context#delete` alias for `Context#delete!`
+- Add `Context#merge` alias for `Context#merge!`
+
+## [1.12.0] - 2025-12-18
+
+### Changed
+- Optimize logging ancestor chain lookup performance
+- Use `String#chop` instead of range indexing for improved string performance
+- Make boolean coercion `TRUTHY` and `FALSEY` patterns case-insensitive
+- Enhance YARD documentation using `yard-lint` validation
+
+### Removed
+- Remove `handle_*` callback methods in favor of `on(*states_or_statuses)` for flexible state handling
 
 ## [1.11.0] - 2025-11-08
 
-### Updated
-- Added conditionally required attributes options
-- Update specs to use new `cmdx-rspec` matcher names
+### Changed
+- Add conditional requirement support for attribute validation
+- Update specs to use new `cmdx-rspec` matcher naming conventions
 
 ## [1.10.1] - 2025-11-06
 
 ### Added
-- Added Sidekiq async integration example
-- Added YARDoc documentation to docs site
+- Add YARDoc documentation to documentation site
 
 ### Removed
-- Removed `Executor#repeator` method (never used)
+- Remove unused `Executor#repeator` method
 
 ## [1.10.0] - 2025-10-26
 
 ### Added
-- Added `rollback` ability to undo on matching status
-- Added documentation for retries
-- Added Stoplight circuit breaker integration example
+- Add `rollback` capability to undo operations based on status
+- Add retry mechanism documentation
 
-### Updated
-- Updated `retry_jitter` option to support symbol, proc, and callables on top of fixed values
+### Changed
+- Extend `retry_jitter` option to accept symbols, procs, and callable objects
 
 ## [1.9.1] - 2025-10-22
 
 ### Added
-- Added RBS inlines type signatures
-- Added YARDocs for `attr_reader` and `attr_accessor` methods
+- Add RBS inline type signatures
+- Add YARDocs for `attr_reader` and `attr_accessor` methods
 
 ## [1.9.0] - 2025-10-21
 
 ### Added
-- Added `transform` option to attributes
-- Added option to output failure backtraces
-- Added exception handling for non-bang methods
-- Added durability with automatic retries to execution
-- Added `to_h` hash coercion support
-- Added comprehensive MkDocs configuration with material theme
+- Add `transform` option for attribute value transformations
+- Add optional failure backtrace output
+- Add exception handling for non-bang execution methods
+- Add automatic retry mechanism for execution durability
+- Add `to_h` hash coercion support
+- Add MkDocs configuration with Material theme
 
 ### Changed
-- Improved performance of task settings setup
-- Improved error messages for raised exceptions
-- Improved inheritance of parent settings
-- Cleaned halt backtrace frames for better readability
+- Improve task settings initialization performance
+- Improve exception error message clarity
+- Improve parent settings inheritance behavior
+- Clean halt backtrace frames for better readability
 
 ### Removed
-- Removed `Freezer` module and moved logic into executor `freeze_execution!` method
-- Removed task parameter from callback signature
-- Removed task and workflow arguments from conditional checks
-- Removed chain persistence after execution in specs
+- Remove `Freezer` module; consolidate logic into `Executor#freeze_execution!`
+- Remove `task` parameter from callback method signatures
+- Remove `task` and `workflow` arguments from conditional checks
+- Remove chain persistence after execution in specs
 
 ## [1.8.0] - 2025-09-22
 
 ### Changed
-- Generalized locale values for fault `invalid` and `unspecified`
-- Nested attribute error messages under `error` key within metadata
-- Reordered logstash formatter keys for consistency
-- Improved error message for already defined items
-- Changed hash coercion for `nil` to return `{}`
+- Generalize locale values for `invalid` and `unspecified` faults
+- Nest attribute error messages under `error` key in metadata
+- Reorder Logstash formatter keys for consistency
+- Improve error messaging for duplicate item definitions
+- Return empty hash `{}` for `nil` hash coercion
 
 ## [1.7.5] - 2025-09-10
 
 ### Added
-- Added `fetch_or_store` method to context
-- Added `ctx` alias for context in result
-- Added `ok?` alias for `good?` in result
-- Added deconstruction values in result
+- Add `Context#fetch_or_store` method for atomic get-or-set operations
+- Add `Result#ctx` alias for `Result#context`
+- Add `Result#ok?` alias for `Result#good?`
+- Add result deconstruction support for pattern matching
 
 ## [1.7.4] - 2025-09-03
 
 ### Added
-- Added errors delegation from result object
-- Added `full_messages` and `to_hash` methods to errors
+- Add errors delegation from result object
+- Add `Errors#full_messages` and `Errors#to_hash` methods
 
 ## [1.7.3] - 2025-09-03
 
 ### Changed
-- Changed validation reasons to use generic values
-- Moved validation full message string to `:full_message` key within metadata
+- Use generic validation reason values
+- Move validation full message to `:full_message` key in metadata
 
 ## [1.7.2] - 2025-09-03
 
 ### Changed
-- Changed correlation ID to be set before continuing to further steps
+- Set correlation ID before proceeding to subsequent execution steps
 
 ## [1.7.1] - 2025-08-26
 
 ### Added
-- Added result yielding when block is given to `execute` and `execute!` methods
+- Add block yielding support to `execute` and `execute!` methods
 
 ## [1.7.0] - 2025-08-25
 
 ### Added
-- Added workflow generator
+- Add workflow generator
 
 ### Changed
-- Ported `cmdx-parallel` changes into core
-- Ported `cmdx-i18n` changes into core
+- Integrate `cmdx-parallel` functionality into core
+- Integrate `cmdx-i18n` functionality into core
 
 ## [1.6.2] - 2025-08-24
 
 ### Changed
-- Prefixed railtie I18n with `::` for compatibility with `CMDx::I18n`
-- Changed to use `cmdx-rspec` for matchers support
+- Prefix railtie I18n with `::` for `CMDx::I18n` compatibility
+- Switch to `cmdx-rspec` for matcher support
 
 ## [1.6.1] - 2025-08-23
 
 ### Changed
-- Changed task results to be logged before freezing
-- Renamed `execute_tasks_sequentially` to `execute_tasks_in_sequence`
+- Log task results before freezing execution state
+- Rename `execute_tasks_sequentially` to `execute_tasks_in_sequence`
 
 ## [1.6.0] - 2025-08-22
 
 ### Added
-- Added workflow task `:breakpoints` support
+- Add workflow task `:breakpoints` support
 
 ### Changed
-- Renamed `Worker` class to `Executor`
-- Moved workflow `work` logic into `Pipeline`
+- Rename `Worker` class to `Executor`
+- Extract workflow execution logic into `Pipeline` class
 
 ## [1.5.2] - 2025-08-22
 
 ### Changed
-- Renamed workflow `execution_groups` attribute to `pipeline`
+- Rename workflow `execution_groups` attribute to `pipeline`
 
 ## [1.5.1] - 2025-08-21
 
 ### Changed
-- Prefixed locale I18n with `::` for compatibility with `CMDx::I18n`
-- Added safe navigation to length and numeric validators
-- Updated railtie file path to point to correct directory
+- Prefix locale I18n with `::` for `CMDx::I18n` compatibility
+- Add safe navigation to length and numeric validators
+- Fix railtie file path to reference correct directory
 
 ## [1.5.0] - 2025-08-21
 
 ### Changed
-- **BREAKING**: Revamped CMDx for improved clarity, transparency, and higher performance
+- **BREAKING**: Complete architecture redesign for improved clarity, transparency, and performance
 
 ## [1.1.2] - 2025-07-20
 
 ### Changed
-- All changes between versions `0.1.0` and `1.1.2` should be reviewed within their respective git tags
+- See git tags for changes between versions 0.1.0 and 1.1.2
 
 ## [0.1.0] - 2025-03-07
 

data/LICENSE.txt

@@ -1,21 +1,4 @@
-The MIT License (MIT)
+Copyright (c) Drexed
 
-Copyright (c) 2025 Juan Gomez
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+CMDx is an Open Source project licensed under the terms of the LGPLv3 license.
+Please see <http://www.gnu.org/licenses/lgpl-3.0.html> for license text.

data/README.md

@@ -1,6 +1,6 @@
 <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">
+  <img src="./src/cmdx-light-logo.png#gh-light-mode-only" width="200" alt="CMDx Light Logo">
+  <img src="./src/cmdx-dark-logo.png#gh-dark-mode-only" width="200" alt="CMDx Dark Logo">
 
   ---
 
@@ -10,7 +10,7 @@
 
   <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">
+  <img alt="License" src="https://img.shields.io/badge/license-LGPL%20v3-blue.svg">
 </div>
 
 # CMDx
@@ -18,13 +18,14 @@
 Say goodbye to messy service objects. CMDx 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.
+> [Documentation](https://drexed.github.io/cmdx/getting_started/) 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+.
+- Ruby: MRI 3.1+ or JRuby 9.4+
+- Dependencies: None
 
-CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
+Rails support is built-in, but it's framework-agnostic at its core.
 
 ## Installation
 
@@ -125,4 +126,4 @@ Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. W
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [LGPLv3 License](https://www.gnu.org/licenses/lgpl-3.0.html).

data/lib/cmdx/attribute.rb

@@ -235,6 +235,23 @@ module CMDx
       end
     end
 
+    # @return [Hash] A hash representation of the attribute
+    #
+    # @example
+    #   attribute.to_h # => { name: :user_id, method_name: :user_id, required: true, types: [:integer], options: {}, children: [] }
+    #
+    # @rbs () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        name: name,
+        method_name: method_name,
+        required: required?,
+        types: types,
+        options: options.except(:if, :unless),
+        children: children.map(&:to_h)
+      }
+    end
+
     private
 
     # Creates nested attributes as children of this attribute.
@@ -312,11 +329,10 @@ module CMDx
       attribute_value.generate
       attribute_value.validate
 
-      task.instance_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-        def #{method_name}
-          attributes[:#{method_name}]
-        end
-      RUBY
+      name_of_method = method_name
+      task.define_singleton_method(name_of_method) do
+        attributes[name_of_method]
+      end
     end
 
   end

data/lib/cmdx/chain.rb

@@ -39,9 +39,10 @@ module CMDx
     # @return [Chain] A new chain instance
     #
     # @rbs () -> void
-    def initialize
+    def initialize(dry_run: false)
       @id = Identifier.generate
       @results = []
+      @dry_run = !!dry_run
     end
 
     class << self
@@ -102,16 +103,28 @@ module CMDx
       #   puts "Chain size: #{chain.size}"
       #
       # @rbs (Result result) -> Chain
-      def build(result)
+      def build(result, dry_run: false)
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
-        self.current ||= new
+        self.current ||= new(dry_run:)
         current.results << result
         current
       end
 
     end
 
+    # Returns whether the chain is running in dry-run mode.
+    #
+    # @return [Boolean] Whether the chain is running in dry-run mode
+    #
+    # @example
+    #   chain.dry_run? # => true
+    #
+    # @rbs () -> bool
+    def dry_run?
+      !!@dry_run
+    end
+
     # Converts the chain to a hash representation.
     #
     # @option return [String] :id The chain identifier
@@ -127,7 +140,8 @@ module CMDx
     # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
-        id: id,
+        id:,
+        dry_run: dry_run?,
         results: results.map(&:to_h)
       }
     end

data/lib/cmdx/context.rb

@@ -164,6 +164,7 @@ module CMDx
       args.to_h.each { |key, value| self[key.to_sym] = value }
       self
     end
+    alias merge merge!
 
     # Deletes a key-value pair from the context.
     #
@@ -182,6 +183,23 @@ module CMDx
     def delete!(key, &)
       table.delete(key.to_sym, &)
     end
+    alias delete delete!
+
+    # Clears all key-value pairs from the context.
+    #
+    # @return [Context] self for method chaining
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.clear!
+    #   context.to_h # => {}
+    #
+    # @rbs () -> self
+    def clear!
+      table.clear
+      self
+    end
+    alias clear clear!
 
     # Compares this context with another object for equality.
     #

data/lib/cmdx/executor.rb

@@ -8,6 +8,8 @@ module CMDx
   # and proper error handling for different types of failures.
   class Executor
 
+    extend Forwardable
+
     # Returns the task being executed.
     #
     # @return [Task] The task instance
@@ -18,6 +20,8 @@ module CMDx
     # @rbs @task: Task
     attr_reader :task
 
+    def_delegators :task, :result
+
     # @param task [CMDx::Task] The task to execute
     #
     # @return [CMDx::Executor] A new executor instance
@@ -65,13 +69,13 @@ module CMDx
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         task.class.settings[:exception_handler]&.call(task, e)
       ensure
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -96,14 +100,14 @@ module CMDx
       rescue UndefinedMethodError => e
         raise_exception(e)
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
         halt_execution?(e) ? raise_exception(e) : post_execution!
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         raise_exception(e)
       else
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -134,17 +138,17 @@ module CMDx
     #
     # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
-      available_retries = (task.class.settings[:retries] || 0).to_i
+      available_retries = Integer(task.class.settings[:retries] || 0)
       return false unless available_retries.positive?
 
-      current_retries = (task.result.metadata[:retries] ||= 0).to_i
-      remaining_retries = available_retries - current_retries
+      current_retry = result.retries
+      remaining_retries = available_retries - current_retry
       return false unless remaining_retries.positive?
 
       exceptions = Array(task.class.settings[:retry_on] || StandardError)
       return false unless exceptions.any? { |e| exception.class <= e }
 
-      task.result.metadata[:retries] += 1
+      result.retries += 1
 
       task.logger.warn do
         reason = "[#{exception.class}] #{exception.message}"
@@ -154,13 +158,13 @@ module CMDx
       jitter = task.class.settings[:retry_jitter]
       jitter =
         if jitter.is_a?(Symbol)
-          task.send(jitter, current_retries)
+          task.send(jitter, current_retry)
         elsif jitter.is_a?(Proc)
-          task.instance_exec(current_retries, &jitter)
+          task.instance_exec(current_retry, &jitter)
         elsif jitter.respond_to?(:call)
-          jitter.call(task, current_retries)
+          jitter.call(task, current_retry)
         else
-          jitter.to_f * current_retries
+          jitter.to_f * current_retry
         end
 
       sleep(jitter) if jitter.positive?
@@ -208,7 +212,7 @@ module CMDx
       task.class.settings[:attributes].define_and_verify(task)
       return if task.errors.empty?
 
-      task.result.fail!(
+      result.fail!(
         Locale.t("cmdx.faults.invalid"),
         errors: {
           full_message: task.errors.to_s,
@@ -223,7 +227,7 @@ module CMDx
     def execution!
       invoke_callbacks(:before_execution)
 
-      task.result.executing!
+      result.executing!
       task.work
     end
 
@@ -231,12 +235,12 @@ module CMDx
     #
     # @rbs () -> void
     def post_execution!
-      invoke_callbacks(:"on_#{task.result.state}")
-      invoke_callbacks(:on_executed) if task.result.executed?
+      invoke_callbacks(:"on_#{result.state}")
+      invoke_callbacks(:on_executed) if result.executed?
 
-      invoke_callbacks(:"on_#{task.result.status}")
-      invoke_callbacks(:on_good) if task.result.good?
-      invoke_callbacks(:on_bad) if task.result.bad?
+      invoke_callbacks(:"on_#{result.status}")
+      invoke_callbacks(:on_good) if result.good?
+      invoke_callbacks(:on_bad) if result.bad?
     end
 
     # Finalizes execution by freezing the task, logging results, and rolling back work.
@@ -246,26 +250,25 @@ module CMDx
       log_execution!
       log_backtrace! if task.class.settings[:backtrace]
 
+      rollback_execution!
       freeze_execution!
       clear_chain!
-
-      rollback_execution!
     end
 
     # Logs the execution result at the configured log level.
     #
     # @rbs () -> void
     def log_execution!
-      task.logger.info { task.result.to_h }
+      task.logger.info { result.to_h }
     end
 
     # Logs the backtrace of the exception if the task failed.
     #
     # @rbs () -> void
     def log_backtrace!
-      return unless task.result.failed?
+      return unless result.failed?
 
-      exception = task.result.caused_failure.cause
+      exception = result.caused_failure.cause
       return if exception.is_a?(Fault)
 
       task.logger.error do
@@ -287,11 +290,11 @@ module CMDx
       return if Coercions::Boolean.call(skip_freezing)
 
       task.freeze
-      task.result.freeze
+      result.freeze
 
       # Freezing the context and chain can only be done
       # once the outer-most task has completed.
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       task.context.freeze
       task.chain.freeze
@@ -301,7 +304,7 @@ module CMDx
     #
     # @rbs () -> void
     def clear_chain!
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       Chain.clear
     end
@@ -310,12 +313,14 @@ module CMDx
     #
     # @rbs () -> void
     def rollback_execution!
+      return if result.rolled_back?
       return unless task.respond_to?(:rollback)
 
       statuses = task.class.settings[:rollback_on]
       statuses = Array(statuses).map(&:to_s).uniq
-      return unless statuses.include?(task.result.status)
+      return unless statuses.include?(result.status)
 
+      result.rolled_back = true
       task.rollback
     end