lite-command 3.1.5 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25949bea3778fbe660ae361819879bc36deb461fb37e9efa4ad11012529ae682
-  data.tar.gz: 7f9df66b9027c3c7e3cb7b8efaad1508dec68c22b4b63ab27c4ffd123707519e
+  metadata.gz: ecfaebe941a3ed585e42a5a43b361d60de38076b6a4254125722b13d57294885
+  data.tar.gz: da15660c9410a9c8797d6c322ab79797f800f5233319a7a39d6476bba10504ec
 SHA512:
-  metadata.gz: 9c2ee67da223708a63852d539ab82f7a893214c1016376fc0af4496d224ccdcfef3340b1267f6fec11348ae8d2ede2c87b605494aa2090a8f449c317a3d9613a
-  data.tar.gz: 29ec28857fc0e8f29e1ba34a41cae8b44298a44c9477e73a237f5eb708965ba555a4b82edff984b20b61b4f1967ce93586ec74075a8421f6481c353865c0e275
+  metadata.gz: b91f356964b41577a7e274a5cc5cf46c74b60a088ffa781e7c5f3cbf0f7bd7713accf16ddf8bee16e99342e04a0040ea8dab2fb8c5ff7eb3132d7e3000596ca0
+  data.tar.gz: d905466a1fe16049f5af3877c2488120eb581070fe85a9bf20654cf09127bcccc8e6e9a79c436f16164e3104d5fc7d1bd6bbb7b839069250d29cc4b551e8c47e

data/CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0] - 2024-10-29
+### Changed
+- Move callbacks to hooks instead of try methods
+
 ## [3.1.5] - 2024-10-28
 ### Changed
 - Renamed private `delegate` method to `delegates` to prevent rails clash

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lite-command (3.1.5)
+    lite-command (3.2.0)
       activemodel
       ostruct
 

data/README.md

@@ -33,10 +33,9 @@ Or install it yourself as:
 * [States](#states)
 * [Statuses](#statuses)
 * [Hooks](#hooks)
-  * [State Hooks](#status-hooks)
-  * [Attribute Hooks](#attribute-hooks)
-  * [Execution Hooks](#execution-hooks)
+  * [Lifecycle Hooks](#lifecycle-hooks)
   * [Status Hooks](#status-hooks)
+  * [State Hooks](#state-hooks)
 * [Children](#children)
   * [Throwing Faults](#throwing-faults)
 * [Sequences](#sequences)
@@ -143,6 +142,10 @@ cmd.raise!(original: true)  #=> raises Lite::Command::Fault
 # On exception:
 cmd.raise!(original: false) #=> raises Lite::Command::Error
 cmd.raise!(original: true)  #=> raises StandardError
+
+# Access the exception objects directly
+cmd.original_exception #=> <StandardError ...>
+cmd.command_exception  #=> <Lite::Command::Error ...>
 ```
 
 ### Dynamic Faults
@@ -361,9 +364,6 @@ cmd.status   #=> "invalid"
 cmd.reason   #=> "Invalid message start value"
 cmd.metadata #=> { i18n: "gb.invalid_start_value" }
 
-cmd.original_exception #=> <RuntimeError ...>
-cmd.command_exception  #=> <DecryptSecretMessage::Error ...>
-
 cmd.success? #=> false
 cmd.noop?    #=> false
 cmd.invalid? #=> true
@@ -387,140 +387,91 @@ cmd.bad?("Other reason") #=> false
 ## Hooks
 
 Use hooks to run arbituary code at transition points and on finalized internals.
-The following is an example of the hooks called for a failed command with a
-successful child command.
+All hooks are ran in the order they are defined. Hooks types can be defined
+multiple times. The following is an example of the hooks called for a failed
+command with a successful child command.
 
 ```ruby
--> 1. FooCommand.on_pending
--> 2. FooCommand.on_before_execution
--> 3. FooCommand.on_executing
----> 3a. BarCommand.on_pending
----> 3b. BarCommand.on_before_execution
----> 3c. BarCommand.on_executing
----> 3d. BarCommand.on_after_execution
----> 3e. BarCommand.on_success
----> 3f. BarCommand.on_complete
--> 4. FooCommand.on_after_execution
--> 5. FooCommand.on_failure
--> 6. FooCommand.on_interrupted
+-> 1. FooCommand.after_initialize
+-> 2. FooCommand.on_pending
+-> 3. FooCommand.before_validation
+-> 4. FooCommand.after_validation
+-> 5. FooCommand.before_execution
+-> 6. FooCommand.on_executing
+---> 6a. BarCommand.after_initialize
+---> 6b. BarCommand.on_pending
+---> 6c. BarCommand.before_validation
+---> 6d. BarCommand.after_validation
+---> 6e. BarCommand.before_execution
+---> 6f. BarCommand.on_executing
+---> 6g. BarCommand.after_execution
+---> 6h. BarCommand.on_failure
+---> 6i. BarCommand.on_interrupted
+-> 7. FooCommand.after_execution
+-> 8. FooCommand.on_failure
+-> 9. FooCommand.on_interrupted
 ```
 
-### Status Hooks
+### Lifecycle Hooks
 
-Define one or more callbacks that are called during transitions between states.
+Define before and after callbacks to call around execution.
 
 ```ruby
 class DecryptSecretMessage < Lite::Command::Base
 
-  def call
-    # ...
-  end
-
-  private
-
-  def on_pending
-    # eg: Append additional contextual data
-  end
-
-  def on_executing
-    # eg: Insert inspection debugger
-  end
-
-  def on_complete
-    # eg: Log message for posterity
-  end
-
-  def on_interrupted
-    # eg: Report to APM with tags and metadata
-  end
-
-end
-```
-
-### Attribute Hooks
-
-Define before attribtue validation callbacks.
-
-```ruby
-class DecryptSecretMessage < Lite::Command::Base
+  after_initialize  :some_method
+  before_validation :some_method
+  after_validation  :some_method
+  before_execution  :some_method
+  after_execution   :some_method
 
   def call
     # ...
   end
 
-  private
-
-  def on_before_validation
-    # eg: Normalize context data
-  end
-
 end
 ```
 
-### Execution Hooks
+### Status Hooks
 
-Define before and after callbacks to call around execution.
+Define one or more callbacks that are called after execution for
+specific statuses.
 
 ```ruby
 class DecryptSecretMessage < Lite::Command::Base
 
+  on_success :some_method
+  on_noop    :some_method
+  on_invalid :some_method
+  on_failure :some_method
+  on_error   :some_method
+
   def call
     # ...
   end
 
-  private
-
-  def on_before_execution
-    # eg: Append additional contextual data
-  end
-
-  def on_after_execution
-    # eg: Store results to database
-  end
-
 end
 ```
 
-### Status Hooks
+### State Hooks
 
-Define one or more callbacks that are called after execution for
-specific statuses.
+Define one or more callbacks that are called during transitions between states.
 
 ```ruby
 class DecryptSecretMessage < Lite::Command::Base
 
+  on_pending     :some_method
+  on_executing   :some_method
+  on_complete    :some_method
+  on_interrupted :some_method
+
   def call
     # ...
   end
 
-  private
-
-  def on_success
-    # eg: Increment KPI counter
-  end
-
-  def on_noop(fault)
-    # eg: Log message for posterity
-  end
-
-  def on_invalid(fault)
-    # eg: Send metadata errors to frontend
-  end
-
-  def on_failure(fault)
-    # eg: Rollback record changes
-  end
-
-  def on_error(fault_or_exception)
-    # eg: Report to APM with tags and metadata
-  end
-
 end
 ```
 
-> [!NOTE]
-> The `on_success` callback does **NOT** take any arguments.
-
 ## Children
 
 When building complex commands, its best that you pass the parents context to the

data/lib/lite/command/base.rb

@@ -16,6 +16,7 @@ module Lite
         base.include Internals::Faults
         base.include Internals::Calls
         base.include Internals::Executions
+        base.include Internals::Hooks
         base.include Internals::Results
 
         if Lite::Command.configuration.raise_dynamic_faults # rubocop:disable Style/GuardClause
@@ -34,7 +35,7 @@ module Lite
 
       def initialize(context = {})
         @context = Context.build(context)
-        Utils.try(self, :on_pending)
+        run_hooks(:after_initialize)
       end
 
     end

data/lib/lite/command/internals/attributes.rb

@@ -52,9 +52,9 @@ module Lite
         private
 
         def validate_context_attributes
-          return if errors.empty?
-
-          invalid!(errors.full_messages.join(". "), metadata: errors.messages)
+          run_hooks(:before_validation)
+          invalid!(errors.full_messages.join(". "), metadata: errors.messages) unless valid?
+          run_hooks(:after_validation)
         end
 
       end

data/lib/lite/command/internals/calls.rb

@@ -24,14 +24,12 @@ module Lite
 
           def call(context = {})
             instance = send(:new, context)
-            instance.validate
             instance.send(:execute)
             instance
           end
 
           def call!(context = {})
             instance = send(:new, context)
-            instance.validate
             instance.send(:execute!)
             instance
           end

data/lib/lite/command/internals/executions.rb

@@ -50,16 +50,18 @@ module Lite
           increment_execution_index
           assign_execution_cmd_id
           start_monotonic_time
-          Utils.try(self, :on_before_validation)
+          run_hooks(:on_pending)
           validate_context_attributes
-          Utils.try(self, :on_before_execution)
+          run_hooks(:before_execution)
           executing!
-          Utils.try(self, :on_executing)
+          run_hooks(:on_executing)
         end
 
         def after_execution
           send(:"#{success? ? COMPLETE : INTERRUPTED}!")
-          Utils.try(self, :on_after_execution)
+          run_hooks(:after_execution)
+          run_hooks(:"on_#{status}")
+          run_hooks(:"on_#{state}")
           stop_monotonic_time
           append_execution_result
           freeze_execution_objects
@@ -72,26 +74,17 @@ module Lite
         end
 
         def execute
-          around_execution { call }
-          Utils.try(self, :on_success)
-        rescue StandardError => e
-          fault(e, Utils.try(e, :type) || ERROR, metadata, exception: e)
-          after_execution
-          Utils.try(self, :"on_#{status}", e)
-        ensure
-          Utils.try(self, :"on_#{state}")
+          execute!
+        rescue StandardError
+          # Do nothing
         end
 
         def execute!
           around_execution { call }
-          Utils.try(self, :on_success)
         rescue StandardError => e
           fault(e, Utils.try(e, :type) || ERROR, metadata, exception: e)
           after_execution
-          Utils.try(self, :"on_#{status}", e)
           raise(e)
-        else
-          Utils.try(self, :"on_#{state}")
         end
 
       end

data/lib/lite/command/internals/hooks.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+
+    HOOKS = [
+      :after_initialize,
+      :before_validation,
+      :after_validation,
+      :before_execution,
+      :after_execution,
+      *STATUSES.map { |s| :"on_#{s}" },
+      *STATES.map { |s| :"on_#{s}" }
+    ].freeze
+
+    module Internals
+      module Hooks
+
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+
+          def hooks
+            @hooks ||= Utils.try(superclass, :hooks).dup || {}
+          end
+
+          HOOKS.each do |h|
+            define_method(h) do |*method_names, &block|
+              method_names << block if block_given?
+              method_names.each { |mn| (hooks[h] ||= []) << mn }
+            end
+          end
+
+        end
+
+        private
+
+        def run_hooks(hook)
+          hooks = self.class.hooks[hook]
+          return if hooks.nil?
+
+          hooks.each { |h| Utils.call(self, h) }
+        end
+
+      end
+    end
+
+  end
+end

data/lib/lite/command/version.rb

@@ -3,7 +3,7 @@
 module Lite
   module Command
 
-    VERSION = "3.1.5"
+    VERSION = "3.2.0"
 
   end
 end

data/lib/lite/command.rb

@@ -16,6 +16,7 @@ require "lite/command/internals/attributes"
 require "lite/command/internals/faults"
 require "lite/command/internals/calls"
 require "lite/command/internals/executions"
+require "lite/command/internals/hooks"
 require "lite/command/internals/results"
 require "lite/command/base"
 require "lite/command/step"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lite-command
 version: !ruby/object:Gem::Version
-  version: 3.1.5
+  version: 3.2.0
 platform: ruby
 authors:
 - Juan Gomez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-28 00:00:00.000000000 Z
+date: 2024-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -201,6 +201,7 @@ files:
 - lib/lite/command/internals/calls.rb
 - lib/lite/command/internals/executions.rb
 - lib/lite/command/internals/faults.rb
+- lib/lite/command/internals/hooks.rb
 - lib/lite/command/internals/results.rb
 - lib/lite/command/internals/runtimes.rb
 - lib/lite/command/sequence.rb