cmdx 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da7809a9d556cc2cb4cc5734fe52790f4e964ccc437728e1c78cef2a6e2121ec
-  data.tar.gz: 9577047cd8a98bc19fe81c02366aebf70c295e738e3083c478ab670c8af55048
+  metadata.gz: 4564456f58ece0df7606a6eee705e3ed5225b66e8cb1b3feae426ae990204fe4
+  data.tar.gz: 412ffb7cfdfbbd71da1c34f2a8bb871f9d9c67b7ef89ab7453af969c4bf6340b
 SHA512:
-  metadata.gz: 3101e89eafcaf552fa64db81fdc0547628e23636564097ae91fb5dc726cbe25bcfbb6c44a04619cbbfcfe41f29f9a42a658bcd045a1a035f85b0c098d20a6038
-  data.tar.gz: 97450b9d1018dfc80d73fac8b0072356c4a1e05f39fc377cbf517468a412c77041bb1376ae0b3a72fb34575709fa169115ebf69ae7285a75fe41d453b21ee247
+  metadata.gz: 9f416759468491771ec5c1ae8985ceef482287680cd494fc4747adea90a570d894a9725958ffd08167cd9c68e59311ea2f4080997ea1e1edf58db12433fad036
+  data.tar.gz: 6e0c6a16bfede183fb61633f55e5bd53bed529b75a2d3fcdbb763885f28d2a614c94abc0cabb178c5743bef99e404648f126c31b0378a0b7da5125d2d8b888a1

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [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
+- Add ansi util
+- Add string to json parsing in hash coercion
+- Add string to json parsing in array coercion
+### Changed
+- Skip assigning log settings if logger is nil
+- Improve ANSI escape sequence
+- Improve run inspector output
+
 ## [0.3.0] - 2025-03-14
 ### Added
 - Add `progname` to logger instances

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/logging.md

@@ -11,27 +11,27 @@ Built-in log formatters are:
 
 #### Success:
 ```txt
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task task=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=complete status=success outcome=success metadata={} runtime=0 origin=CMDx
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=complete status=success outcome=success metadata={} runtime=0 origin=CMDx
 ```
 
 #### Skipped:
 ```txt
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task task=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=skipped outcome=skipped metadata={} runtime=0 origin=CMDx
+W, [2022-07-17T18:43:15.000000 #3784] WARN -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=skipped outcome=skipped metadata={} runtime=0 origin=CMDx
 ```
 
 #### Failed:
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task task=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=failed metadata={} runtime=0 origin=CMDx
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=failed metadata={} runtime=0 origin=CMDx
 ```
 
 #### Level 1 subtask failure:
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task task=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", task: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", task: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} origin=CMDx
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} origin=CMDx
 ```
 
 #### Level 2+ subtask failure:
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task task=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 2, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", task: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", task: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, runtime: 0} origin=CMDx
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 2, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, runtime: 0} origin=CMDx
 ```
 
 ## Logger

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/coercions/array.rb

@@ -7,7 +7,11 @@ module CMDx
       module_function
 
       def call(value, _options = {})
-        Array(value)
+        if value.is_a?(::String) && value.start_with?("[")
+          JSON.parse(value)
+        else
+          Array(value)
+        end
       end
 
     end

data/lib/cmdx/coercions/hash.rb

@@ -8,11 +8,16 @@ module CMDx
 
       def call(value, _options = {})
         case value.class.name
-        when "Hash", "ActionController::Parameters" then value
-        when "Array" then ::Hash[*value]
-        else raise_coercion_error!
+        when "Hash", "ActionController::Parameters"
+          value
+        when "Array"
+          ::Hash[*value]
+        when "String"
+          value.start_with?("{") ? JSON.parse(value) : raise_coercion_error!
+        else
+          raise_coercion_error!
         end
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, TypeError, JSON::ParserError
         raise_coercion_error!
       end
 

data/lib/cmdx/configuration.rb

@@ -14,7 +14,7 @@ module CMDx
 
   def reset_configuration!
     @configuration = LazyStruct.new(
-      logger: ::Logger.new($stdout, formatter: CMDx::LogFormatters::Json.new),
+      logger: ::Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new),
       task_halt: CMDx::Result::FAILED,
       task_timeout: nil,
       batch_halt: CMDx::Result::FAILED,

data/lib/cmdx/logger.rb

@@ -6,10 +6,14 @@ module CMDx
     module_function
 
     def call(task)
-      logger           = task.task_setting(:logger)
-      logger.formatter = task.task_setting(:log_formatter) if task.task_setting?(:log_formatter)
-      logger.level     = task.task_setting(:log_level) if task.task_setting?(:log_level)
-      logger.progname  = task
+      logger = task.task_setting(:logger)
+
+      unless logger.nil?
+        logger.formatter = task.task_setting(:log_formatter) if task.task_setting?(:log_formatter)
+        logger.level     = task.task_setting(:log_level) if task.task_setting?(:log_level)
+        logger.progname  = task
+      end
+
       logger
     end
 

data/lib/cmdx/logger_ansi.rb

@@ -3,19 +3,20 @@
 module CMDx
   module LoggerAnsi
 
-    SEVERITY_COLOR_CODES = {
-      "D" => 34, # DEBUG - Blue
-      "I" => 32, # INFO  - Green
-      "W" => 33, # WARN  - Yellow
-      "E" => 31, # ERROR - Red
-      "F" => 35  # FATAL - Magenta
+    SEVERITY_COLORS = {
+      "D" => :blue,
+      "I" => :green,
+      "W" => :yellow,
+      "E" => :red,
+      "F" => :magenta
     }.freeze
 
     module_function
 
     def call(s)
-      c = SEVERITY_COLOR_CODES[s[0]] || 39 # Default
-      "\e[1;#{c}m#{s}\e[0m"
+      color = SEVERITY_COLORS[s[0]] || :default
+
+      Utils::AnsiColor.call(s, color:, mode: :bold)
     end
 
   end

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/result_ansi.rb

@@ -3,23 +3,24 @@
 module CMDx
   module ResultAnsi
 
-    STATE_COLOR_CODES = {
-      Result::INITIALIZED => 34, # Blue
-      Result::EXECUTING => 33,   # Yellow
-      Result::COMPLETE => 32,    # Green
-      Result::INTERRUPTED => 31  # Red
+    STATE_COLORS = {
+      Result::INITIALIZED => :blue,
+      Result::EXECUTING => :yellow,
+      Result::COMPLETE => :green,
+      Result::INTERRUPTED => :red
     }.freeze
-    STATUS_COLOR_CODES = {
-      Result::SUCCESS => 32, # Green
-      Result::SKIPPED => 33, # Yellow
-      Result::FAILED => 31   # Red
+    STATUS_COLORS = {
+      Result::SUCCESS => :green,
+      Result::SKIPPED => :yellow,
+      Result::FAILED => :red
     }.freeze
 
     module_function
 
     def call(s)
-      c = STATE_COLOR_CODES[s] || STATUS_COLOR_CODES[s] || 39 # Default
-      "\e[1;#{c}m#{s}\e[0m"
+      color = STATE_COLORS[s] || STATUS_COLORS[s] || :default
+
+      Utils::AnsiColor.call(s, color:)
     end
 
   end

data/lib/cmdx/result_inspector.rb

@@ -4,7 +4,7 @@ module CMDx
   module ResultInspector
 
     ORDERED_KEYS = %i[
-      task type index id state status outcome metadata
+      class type index id state status outcome metadata
       tags pid runtime caused_failure threw_failure
     ].freeze
 
@@ -17,10 +17,10 @@ module CMDx
         value = result[key]
 
         case key
-        when :task
+        when :class
           "#{value}:"
         when :caused_failure, :threw_failure
-          "#{key}=<[#{value[:index]}] #{value[:task]}: #{value[:id]}>"
+          "#{key}=<[#{value[:index]}] #{value[:class]}: #{value[:id]}>"
         else
           "#{key}=#{value}"
         end

data/lib/cmdx/result_logger.rb

@@ -12,7 +12,9 @@ module CMDx
     module_function
 
     def call(result)
-      logger   = result.task.send(:logger)
+      logger = result.task.send(:logger)
+      return if logger.nil?
+
       severity = STATUS_TO_SEVERITY[result.status]
 
       logger.with_level(severity) do

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_inspector.rb

@@ -3,18 +3,23 @@
 module CMDx
   module RunInspector
 
-    ORDERED_KEYS = %i[
+    FOOTER_KEYS = %i[
       state status outcome runtime
     ].freeze
 
     module_function
 
     def call(run)
-      header = "Run: #{run.id}"
-      footer = ORDERED_KEYS.map { |key| "#{key}=#{run.send(key)}" }.join(" ")
+      header = "\nrun: #{run.id}"
+      footer = FOOTER_KEYS.map { |key| "#{key}: #{run.send(key)}" }.join(" | ")
       spacer = "=" * [header.size, footer.size].max
 
-      run.results.map(&:to_s).unshift(header, spacer).push(spacer, footer).join("\n")
+      run
+        .results
+        .map { |r| r.to_h.except(:run_id).pretty_inspect }
+        .unshift(header, "#{spacer}\n")
+        .push(spacer, "#{footer}\n\n")
+        .join("\n")
     end
 
   end

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/task_serializer.rb

@@ -10,7 +10,7 @@ module CMDx
         index: task.result.index,
         run_id: task.run.id,
         type: task.is_a?(Batch) ? "Batch" : "Task",
-        task: task.class.name,
+        class: task.class.name,
         id: task.id,
         tags: task.task_setting(:tags)
       }

data/lib/cmdx/utils/ansi_color.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    module AnsiColor
+
+      COLOR_CODES = {
+        black: 30,
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        white: 37,
+        default: 39,
+        light_black: 90,
+        light_red: 91,
+        light_green: 92,
+        light_yellow: 93,
+        light_blue: 94,
+        light_magenta: 95,
+        light_cyan: 96,
+        light_white: 97
+      }.freeze
+      MODE_CODES = {
+        default: 0,
+        bold: 1,
+        dim: 2,
+        italic: 3,
+        underline: 4,
+        blink: 5,
+        blink_slow: 5,
+        blink_fast: 6,
+        invert: 7,
+        hide: 8,
+        strike: 9,
+        double_underline: 20,
+        reveal: 28,
+        overlined: 53
+      }.freeze
+
+      module_function
+
+      def call(value, color:, mode: :default)
+        color_code = COLOR_CODES.fetch(color)
+        mode_code  = MODE_CODES.fetch(mode)
+
+        "\e[#{mode_code};#{color_code};49m#{value}\e[0m"
+      end
+
+    end
+  end
+end

data/lib/cmdx/version.rb

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

data/lib/cmdx.rb

@@ -5,6 +5,7 @@ require "date"
 require "i18n"
 require "json"
 require "logger"
+require "pp"
 require "securerandom"
 require "time"
 require "timeout"
@@ -41,6 +42,7 @@ require_relative "cmdx/validators/inclusion"
 require_relative "cmdx/validators/length"
 require_relative "cmdx/validators/numeric"
 require_relative "cmdx/validators/presence"
+require_relative "cmdx/utils/ansi_color"
 require_relative "cmdx/utils/log_timestamp"
 require_relative "cmdx/utils/name_affix"
 require_relative "cmdx/utils/monotonic_runtime"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Juan Gomez
 bindir: exe
 cert_chain: []
-date: 2025-03-14 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -246,6 +246,7 @@ files:
 - lib/cmdx/task.rb
 - lib/cmdx/task_hook.rb
 - lib/cmdx/task_serializer.rb
+- lib/cmdx/utils/ansi_color.rb
 - lib/cmdx/utils/log_timestamp.rb
 - lib/cmdx/utils/monotonic_runtime.rb
 - lib/cmdx/utils/name_affix.rb