cmdx 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00e2b2067ace8ed3afdb75bc07e3f3c5ec3ed40233a63cc3a9abc495c3a3199c
-  data.tar.gz: 053c7a3a6e3c70808b4dba6d916a35419ee0c858145dbace0d83d89e0583d05a
+  metadata.gz: 4564456f58ece0df7606a6eee705e3ed5225b66e8cb1b3feae426ae990204fe4
+  data.tar.gz: 412ffb7cfdfbbd71da1c34f2a8bb871f9d9c67b7ef89ab7453af969c4bf6340b
 SHA512:
-  metadata.gz: 2de61e9b7e43d9e1187b4c6c925c930ae55163a5075ac624f4a9c29595588b10aacd007d64654397dc458a9c704d9175dd884eadafbef614bb8f01182f022cf0
-  data.tar.gz: 52dcb48c2e9538d33fea460946fde8f25814127aa490895fc4a676f865423d0b915ad1e7c5daae88ebe46e4bff01a36f850fa704bff312fa938ed5e3a7ea879a
+  metadata.gz: 9f416759468491771ec5c1ae8985ceef482287680cd494fc4747adea90a570d894a9725958ffd08167cd9c68e59311ea2f4080997ea1e1edf58db12433fad036
+  data.tar.gz: 6e0c6a16bfede183fb61633f55e5bd53bed529b75a2d3fcdbb763885f28d2a614c94abc0cabb178c5743bef99e404648f126c31b0378a0b7da5125d2d8b888a1

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-03-21
+
+### Added
+- Add `to_a` alias on array of hashes serializers
+- Add `state`, `status`, `outcome`, and `runtime` to run serializer
+- Add `on_[state]` and `on_[status]` based result callback handlers
+- Add `on_executed` state task hook
+- Add `on_good` and `on_bad` status task hook
+### Changed
+- Changed status and state hook order
+
 ## [0.4.0] - 2025-03-17
 
 ### Added

data/docs/hooks.md

@@ -41,13 +41,16 @@ The hook methods support the following options:
 Hook types are executed in the following order:
 
 ```ruby
-1. before_execution
-2. on_executing
-3. before_validation
-4. after_validation
-5. on_[success, skipped, failed]
-6. on_[complete, interrupted]
-7. after_execution
+0. before_execution
+1. on_executing
+2. before_validation
+3. after_validation
+4. on_[complete, interrupted]
+5. on_executed
+6. on_[success, skipped, failed]
+7. on_good
+8. on_bad
+9. after_execution
 ```
 
 > [!IMPORTANT]

data/docs/outcomes/states.md

@@ -25,6 +25,27 @@ result.interrupted? #=> false
 result.executed?
 ```
 
+## Handlers
+
+Results can be used to trigger state based callbacks. Handlers require a block
+and will have the result available as local variable. Callback handlers can be
+chained and repeated.
+
+```ruby
+result = ProcessOrderTask.call
+result.on_complete { do_work }
+
+# - or -
+
+ProcessOrderTask
+  .call(...)
+  .on_executing { do_work }
+  .on_executed { |result| $statsd.increment(result.state) }
+```
+
+> [!TIP]
+> Handlers help execute you logical branches without `if/else` blocks.
+
 ---
 
 - **Prev:** [Outcomes - Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)

data/docs/outcomes/statuses.md

@@ -27,6 +27,27 @@ result.good?    #=> true
 result.bad?     #=> true
 ```
 
+## Handlers
+
+Results can be used to trigger status based callbacks. Handlers require a block
+and will have the result available as local variable. Callback handlers can be
+chained and repeated.
+
+```ruby
+result = ProcessOrderTask.call
+result.on_success { do_work }
+
+# - or -
+
+ProcessOrderTask
+  .call(...)
+  .on_success { do_work }
+  .on_bad { |result| $statsd.increment(result.state) }
+```
+
+> [!TIP]
+> Handlers help execute you logical branches without `if/else` blocks.
+
 ---
 
 - **Prev:** [Outcomes - Result](https://github.com/drexed/cmdx/blob/main/docs/outcomes/result.md)

data/lib/cmdx/parameters.rb

@@ -18,6 +18,7 @@ module CMDx
     def to_h
       ParametersSerializer.call(self)
     end
+    alias to_a to_h
 
     def to_s
       ParametersInspector.call(self)

data/lib/cmdx/result.rb

@@ -26,6 +26,14 @@ module CMDx
     STATES.each do |s|
       # eg: executing?
       define_method(:"#{s}?") { state == s }
+
+      # eg: on_interrupted { ... }
+      define_method(:"on_#{s}") do |&block|
+        raise ArgumentError, "a block is required" unless block
+
+        block.call(self) if send(:"#{s}?")
+        self
+      end
     end
 
     def executed!
@@ -36,6 +44,13 @@ module CMDx
       complete? || interrupted?
     end
 
+    def on_executed(&)
+      raise ArgumentError, "a block is required" unless block_given?
+
+      yield(self) if executed?
+      self
+    end
+
     def executing!
       return if executing?
 
@@ -69,16 +84,38 @@ module CMDx
     STATUSES.each do |s|
       # eg: skipped?
       define_method(:"#{s}?") { status == s }
+
+      # eg: on_failed { ... }
+      define_method(:"on_#{s}") do |&block|
+        raise ArgumentError, "a block is required" unless block
+
+        block.call(self) if send(:"#{s}?")
+        self
+      end
     end
 
     def good?
       !failed?
     end
 
+    def on_good(&)
+      raise ArgumentError, "a block is required" unless block_given?
+
+      yield(self) if good?
+      self
+    end
+
     def bad?
       !success?
     end
 
+    def on_bad(&)
+      raise ArgumentError, "a block is required" unless block_given?
+
+      yield(self) if bad?
+      self
+    end
+
     def skip!(**metadata)
       return if skipped?
 

data/lib/cmdx/run.rb

@@ -21,6 +21,7 @@ module CMDx
     def to_h
       RunSerializer.call(self)
     end
+    alias to_a to_h
 
     def to_s
       RunInspector.call(self)

data/lib/cmdx/run_serializer.rb

@@ -8,6 +8,10 @@ module CMDx
     def call(run)
       {
         id: run.id,
+        state: run.state,
+        status: run.status,
+        outcome: run.outcome,
+        runtime: run.runtime,
         results: run.results.map(&:to_h)
       }
     end

data/lib/cmdx/task.rb

@@ -8,6 +8,9 @@ module CMDx
       :after_validation,
       :before_execution,
       :after_execution,
+      :on_executed,
+      :on_good,
+      :on_bad,
       *Result::STATUSES.map { |s| :"on_#{s}" },
       *Result::STATES.map { |s| :"on_#{s}" }
     ].freeze
@@ -103,8 +106,12 @@ module CMDx
     end
 
     def after_call
-      TaskHook.call(self, :"on_#{result.status}")
       TaskHook.call(self, :"on_#{result.state}")
+      TaskHook.call(self, :on_executed) if result.executed?
+
+      TaskHook.call(self, :"on_#{result.status}")
+      TaskHook.call(self, :on_good) if result.good?
+      TaskHook.call(self, :on_bad) if result.bad?
 
       TaskHook.call(self, :after_execution)
     end

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Juan Gomez
 bindir: exe
 cert_chain: []
-date: 2025-03-17 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal