lite-command 2.0.2 → 2.1.0

data/lib/lite/command/attribute.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class Attribute
+
+      # TODO: allow procs
+
+      attr_reader :command, :method_name, :options, :errors
+
+      def initialize(command, method_name, options)
+        @command = command
+        @method_name = method_name
+        @options = options
+        @errors = []
+      end
+
+      def from
+        options[:from] || :context
+      end
+
+      def filled?
+        Utils.call(command, options[:filled]) || false
+      end
+
+      def required?
+        Utils.call(command, options[:required]) || false
+      end
+
+      def typed?
+        options.key?(:types) && types.any?
+      end
+
+      def types
+        @types ||= begin
+          t = Array(Utils.call(command, options[:types]))
+
+          if filled?
+            t - [NilClass]
+          else
+            t | [NilClass]
+          end
+        end
+      end
+
+      def validate!
+        validate_respond_attribute!
+        return unless errors.empty?
+
+        validate_required_attribute!
+        validate_attribute_type!
+        validate_attribute_filled!
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def value
+        return @value if defined?(@value)
+
+        @value = command.send(from).public_send(method_name)
+      end
+
+      private
+
+      def validate_respond_attribute!
+        return if command.respond_to?(from, true)
+
+        @errors << "is not defined or an attribute"
+      end
+
+      def validate_required_attribute!
+        return unless required?
+        return if command.send(from).respond_to?(method_name)
+
+        @errors << "#{method_name} is required"
+      end
+
+      def validate_attribute_type!
+        return unless typed?
+        return if types.include?(value.class)
+
+        @errors << "#{method_name} type invalid"
+      end
+
+      def validate_attribute_filled!
+        return unless filled?
+        return unless value.nil?
+
+        @errors << "#{method_name} must be filled"
+      end
+
+    end
+  end
+end

data/lib/lite/command/attribute_validator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class AttributeValidator
+
+      attr_reader :command
+
+      def initialize(command)
+        @command = command
+      end
+
+      def attributes
+        @attributes ||=
+          command.class.attributes.map do |method_name, options|
+            Lite::Command::Attribute.new(command, method_name, options)
+          end
+      end
+
+      def errors
+        @errors ||= attributes.each_with_object({}) do |attribute, h|
+          attribute.validate!
+          next if attribute.valid?
+
+          h[attribute.from] ||= []
+          h[attribute.from] = h[attribute.from] | attribute.errors
+        end
+      end
+
+      def valid?
+        attributes.empty? || errors.empty?
+      end
+
+    end
+  end
+end

data/lib/lite/command/base.rb

@@ -5,24 +5,24 @@ module Lite
     class Base
 
       def self.inherited(base)
-        super
-
-        base.include Lite::Command::Internals::Callable
-        base.include Lite::Command::Internals::Executable
-        base.include Lite::Command::Internals::Faultable
-        base.include Lite::Command::Internals::Resultable
+        base.include Lite::Command::Internals::Context
+        base.include Lite::Command::Internals::Call
+        base.include Lite::Command::Internals::Execute
+        base.include Lite::Command::Internals::Fault
+        base.include Lite::Command::Internals::Result
 
         base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          # eg: Users::ResetPassword::Fault
-          class #{base}::Fault < Lite::Command::Fault; end
+          # eg: Users::ResetPassword::Fault < Lite::Command::Fault
+          #{base}::Fault = Class.new(Lite::Command::Fault)
+
+          # eg: Users::ResetPassword::Noop < Users::ResetPassword::Fault
+          #{base}::Noop    = Class.new(#{base}::Fault)
+          #{base}::Invalid = Class.new(#{base}::Fault)
+          #{base}::Failure = Class.new(#{base}::Fault)
+          #{base}::Error   = Class.new(#{base}::Fault)
         RUBY
 
-        FAULTS.each do |f|
-          base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            # eg: Users::ResetPassword::Noop < Users::ResetPassword::Fault
-            class #{base}::#{f.capitalize} < #{base}::Fault; end
-          RUBY
-        end
+        super
       end
 
       attr_reader :context
@@ -30,16 +30,7 @@ module Lite
 
       def initialize(context = {})
         @context = Lite::Command::Context.build(context)
-      end
-
-      private
-
-      def on_before_execution
-        # Define in your class to run code before execution
-      end
-
-      def on_after_execution
-        # Define in your class to run code after execution
+        Utils.hook(self, :on_pending)
       end
 
     end

data/lib/lite/command/fault.rb

@@ -5,22 +5,32 @@ module Lite
 
     class Fault < StandardError
 
-      attr_reader :caused_by, :thrown_by, :reason
+      attr_reader :caused_by, :thrown_by, :reason, :metadata
 
-      def initialize(caused_by, thrown_by, reason)
-        super(reason)
+      def initialize(**params)
+        @reason    = params.fetch(:reason)
+        @metadata  = params.fetch(:metadata)
+        @caused_by = params.fetch(:caused_by)
+        @thrown_by = params.fetch(:thrown_by)
 
-        @caused_by = caused_by
-        @thrown_by = thrown_by
-        @reason = reason
+        super(reason)
       end
 
-      def fault_klass
-        @fault_klass ||= self.class.name.split("::").last
+      def self.build(type, command, thrown_exception, dynamic: false)
+        klass = dynamic ? command.class : Lite::Command
+        fault = klass.const_get(type.to_s)
+        fault = fault.new(
+          reason: command.reason,
+          metadata: command.metadata,
+          caused_by: command.caused_by || command,
+          thrown_by: command
+        )
+        fault.set_backtrace(thrown_exception.backtrace) if thrown_exception.respond_to?(:backtrace)
+        fault
       end
 
-      def fault_name
-        @fault_name ||= fault_klass.downcase
+      def type
+        @type ||= self.class.name.split("::").last.downcase
       end
 
     end

data/lib/lite/command/fault_streamer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class FaultStreamer
+
+      attr_reader :command, :object
+
+      def initialize(command, object)
+        @command = command
+        @object = object
+      end
+
+      def caused_by
+        Utils.try(object, :caused_by) || command
+      end
+
+      def thrown_by
+        return object if Utils.try(object, :executed?)
+
+        Utils.try(object, :thrown_by) || command.caused_by
+      end
+
+      def metadata
+        Utils.try(object, :metadata) || command.metadata
+      end
+
+      def reason
+        if object.respond_to?(:reason)
+          object.reason
+        elsif object.is_a?(StandardError)
+          "[#{object.class.name}] #{object.message}".chomp(".")
+        else
+          object
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+
+    STATUSES = [
+      SUCCESS = "success",
+      NOOP    = "noop",
+      INVALID = "invalid",
+      FAILURE = "failure",
+      ERROR   = "error"
+    ].freeze
+    FAULTS = (STATUSES - [SUCCESS]).freeze
+
+    module Internals
+      module Call
+
+        def self.included(base)
+          base.extend ClassMethods
+          base.class_eval do
+            attr_reader :reason, :metadata
+          end
+        end
+
+        module ClassMethods
+
+          def call(context = {})
+            instance = send(:new, context)
+            instance.send(:execute)
+            instance
+          end
+
+          def call!(context = {})
+            instance = send(:new, context)
+            instance.send(:execute!)
+            instance
+          end
+
+        end
+
+        def call
+          raise NotImplementedError, "call method not defined in #{self.class}"
+        end
+
+        def status
+          @status || SUCCESS
+        end
+
+        def success?
+          status == SUCCESS
+        end
+
+        def ok?(reason = nil)
+          success? || noop?(reason)
+        end
+
+        def fault?(reason = nil)
+          !success? && reason?(reason)
+        end
+
+        FAULTS.each do |f|
+          # eg: noop? or failure?("idk")
+          define_method(:"#{f}?") do |reason = nil|
+            status == f && reason?(reason)
+          end
+        end
+
+        private
+
+        def reason?(str)
+          str.nil? || str == reason
+        end
+
+        def fault(object, status, metadata)
+          @status   = status
+          @metadata = metadata
+
+          down_stream = Lite::Command::FaultStreamer.new(self, object)
+          @reason    ||= down_stream.reason
+          @metadata  ||= down_stream.metadata
+          @caused_by ||= down_stream.caused_by
+          @thrown_by ||= down_stream.thrown_by
+        end
+
+        FAULTS.each do |f|
+          # eg: invalid!("idk") or failure!(fault) or error!("idk", { error_key: "some.error" })
+          define_method(:"#{f}!") do |object, metadata = nil|
+            fault(object, f, metadata)
+
+            raise Lite::Command::Fault.build(f.capitalize, self, object, dynamic: raise_dynamic_faults?)
+          end
+        end
+
+        alias fail! failure!
+
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    module Internals
+      module Context
+
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+
+          def attribute(*args, **options)
+            args.each do |method_name|
+              attributes[method_name] = options
+
+              define_method(method_name) do
+                ivar = :"@#{method_name}"
+                return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+                attribute = Lite::Command::Attribute.new(self, method_name, options)
+                instance_variable_set(ivar, attribute.value)
+              end
+            end
+          end
+
+          def attributes
+            @attributes ||= {}
+          end
+
+        end
+
+        private
+
+        def validate_context_attributes
+          validator = Lite::Command::AttributeValidator.new(self)
+          return if validator.valid?
+
+          invalid!("Invalid context attributes", validator.errors)
+        end
+
+      end
+    end
+  end
+end

data/lib/lite/command/internals/{executable.rb → execute.rb}

@@ -4,48 +4,28 @@ module Lite
   module Command
 
     STATES = [
-      PENDING = "pending",
-      EXECUTING = "executing",
-      COMPLETE = "complete",
-      DNF = "dnf"
+      PENDING     = "pending",
+      EXECUTING   = "executing",
+      COMPLETE    = "complete",
+      INTERRUPTED = "interrupted"
     ].freeze
 
     module Internals
-      module Executable
-
-        def execute
-          around_execution { call }
-        rescue StandardError => e
-          fn = e.respond_to?(:fault_name) ? e.fault_name : ERROR
-
-          send(:"#{fn}", e)
-          after_execution
-          send(:"on_#{fn}", e)
-        end
-
-        def execute!
-          around_execution { call }
-        rescue StandardError => e
-          after_execution
-
-          raise(e) unless raise_dynamic_faults? && e.is_a?(Lite::Command::Fault)
-
-          raise_dynamic_fault(e)
-        end
+      module Execute
 
         def state
           @state || PENDING
         end
 
         def executed?
-          dnf? || complete?
+          complete? || interrupted?
         end
 
         STATES.each do |s|
           # eg: executing?
           define_method(:"#{s}?") { state == s }
 
-          # eg: dnf!
+          # eg: interrupted!
           define_method(:"#{s}!") { @state = s }
         end
 
@@ -53,15 +33,17 @@ module Lite
 
         def before_execution
           increment_execution_index
-          assign_execution_cid
+          assign_execution_cmd_id
           start_monotonic_time
+          Utils.hook(self, :on_before_execution)
+          validate_context_attributes
           executing!
-          on_before_execution
+          Utils.hook(self, :on_executing)
         end
 
         def after_execution
-          fault? ? dnf! : complete!
-          on_after_execution
+          send(:"#{success? ? COMPLETE : INTERRUPTED}!")
+          Utils.hook(self, :on_after_execution)
           stop_monotonic_time
           append_execution_result
           freeze_execution_objects
@@ -73,6 +55,28 @@ module Lite
           after_execution
         end
 
+        def execute
+          around_execution { call }
+          Utils.hook(self, :on_success)
+        rescue StandardError => e
+          fault(e, ERROR, metadata) unless e.is_a?(Lite::Command::Fault)
+          after_execution
+          Utils.hook(self, :"on_#{status}", e)
+        ensure
+          Utils.hook(self, :"on_#{state}")
+        end
+
+        def execute!
+          around_execution { call }
+          Utils.hook(self, :on_success)
+        rescue StandardError => e
+          fault(e, ERROR, metadata) unless e.is_a?(Lite::Command::Fault)
+          after_execution
+          raise(e)
+        else
+          Utils.hook(self, :"on_#{state}")
+        end
+
       end
     end
 

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    module Internals
+      module Fault
+
+        def self.included(base)
+          base.class_eval do
+            attr_reader :caused_by, :thrown_by
+          end
+        end
+
+        def caused_fault?
+          caused_by == self
+        end
+
+        def threw_fault?
+          thrown_by == self
+        end
+
+        def thrown?
+          fault? && !caused_fault?
+        end
+
+        private
+
+        def throw!(command)
+          return if command.success?
+
+          send(:"#{command.status}!", command)
+        end
+
+        def raise_dynamic_faults?
+          false
+        end
+
+      end
+    end
+  end
+end

data/lib/lite/command/internals/{resultable.rb → result.rb}

@@ -5,14 +5,14 @@ require "securerandom" unless defined?(SecureRandom)
 module Lite
   module Command
     module Internals
-      module Resultable
+      module Result
 
         def index
           @index ||= context.index ||= 0
         end
 
-        def cid
-          @cid ||= context.cid
+        def cmd_id
+          @cmd_id ||= context.cmd_id ||= SecureRandom.uuid
         end
 
         def outcome
@@ -28,12 +28,13 @@ module Lite
         def to_hash
           {
             index:,
-            cid:,
+            cmd_id:,
             command: self.class.name,
             outcome:,
             state:,
             status:,
             reason:,
+            metadata:,
             caused_by: caused_by&.index,
             thrown_by: thrown_by&.index,
             runtime:
@@ -43,8 +44,8 @@ module Lite
 
         private
 
-        def assign_execution_cid
-          context.cid ||= SecureRandom.uuid
+        def assign_execution_cmd_id
+          @cmd_id = context.cmd_id ||= cmd_id
         end
 
         def increment_execution_index

data/lib/lite/command/sequence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class Sequence < Base
+
+      def self.step(*commands, **options)
+        commands.flatten.each do |command|
+          steps << Step.new(command, options)
+        end
+      end
+
+      def self.steps
+        @steps ||= []
+      end
+
+      def call
+        self.class.steps.each do |step|
+          next unless step.run?(self)
+
+          cmd = step.command.call(context)
+          throw!(cmd) unless cmd.ok?
+        end
+      end
+
+    end
+  end
+end

data/lib/lite/command/step.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class Step
+
+      attr_reader :command, :options
+
+      def initialize(command, options)
+        @command = command
+        @options = options
+      end
+
+      def run?(cmd)
+        if options[:if]
+          Utils.call(cmd, options[:if])
+        elsif options[:unless]
+          !Utils.call(cmd, options[:unless])
+        else
+          true
+        end
+      end
+
+    end
+  end
+end

data/lib/lite/command/utils.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    module Utils
+
+      module_function
+
+      def try(object, method_name, *args, include_private: false)
+        return unless object.respond_to?(method_name, include_private)
+
+        object.send(method_name, *args)
+      end
+
+      def hook(object, method_name, *args)
+        try(object, method_name, *args, include_private: true)
+      end
+
+      def call(object, method_name_or_proc)
+        if method_name_or_proc.is_a?(Symbol) || method_name_or_proc.is_a?(String)
+          object.send(method_name_or_proc)
+        elsif method_name_or_proc.is_a?(Proc)
+          object.instance_eval(&method_name_or_proc)
+        else
+          method_name_or_proc
+        end
+      end
+
+    end
+  end
+end