bbservices 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a1f2e96213010efff9a6fc0e7d7c2a9afe4f8139b18d1a9b0ec1930affccdbb
-  data.tar.gz: 82795e5ad405330c4cdd89d3e14c535dd70207598e3b7c71f81e905a9d78188b
+  metadata.gz: 662a72a39dbe2e481513c47eba00edcde5288c6018aea566c881c5834c4020ea
+  data.tar.gz: fdfb42ddcd57afa106896271602c3aa715ac5d5093835b289de48de868e0ff1a
 SHA512:
-  metadata.gz: 3d2ccdbcce8e8404e7a6cac802eee2f135e0ded720449c84ec32898a38ae65143f7e75563799f3d9e984570902e350d80055a6f6ecbb8bb1eb1e41308e9349e6
-  data.tar.gz: ea5b4bb65ed5f14ce931c61d15aa5fe2c0666ec279345cab7ca7c3e26d38e4b555e9f5e80fe9487f17ca535e74228454a82cb185d686ecd61291623c813606ab
+  metadata.gz: 95a00382d51a488d15de9a3260793966052a8de0a80b24cf1b7eb25902f27438c67b5b997349e3762081b02423d8431c27e2c112c36f898a0ac3d3761aa61e40
+  data.tar.gz: 2248179e4cd90ad84e6f1af0bcf5c9e8c705f5d5fcabb918c6f690a58073d4d736deb4f2f85e1887aa469975fb9b7fd51fadd1718c908eb085820e07fa557ce6

data/lib/bbservices.rb

@@ -1,4 +1,14 @@
 # frozen_string_literal: true
 
 require_relative 'bbservices/service'
+require_relative 'bbservices/service_chain'
 require_relative 'bbservices/service_provider'
+
+# The BBServices namespace.
+module BBServices
+  def self.chain(params = {}, &block)
+    BBServices::ServiceChain.new.tap do |service_chain|
+      service_chain.chain(params, &block)
+    end
+  end
+end

data/lib/bbservices/service.rb

@@ -1,68 +1,78 @@
 # frozen_string_literal: true
 
+require_relative 'service_chain'
+
+# The BBServices namespace.
 module BBServices
-  ##
-  # The base class for all services. Handles the basic run loop and general accessors
+  # Error thrown when a Hash type isn't given
+  class ServiceHashTypeError < StandardError
+    def message
+      'Params need to be a Hash'
+    end
+  end
+
+  # The lightweight service object provided by BBServices.
   class Service
     attr_reader :params, :object, :error
 
     class << self
-      # Creates a new service class, then calls run
+
+      # Creates the service instances and calls run upon said instance
+      # @param [Hash] params The params which are passed to the service
+      # @param [Block] block The block which will be called upon the service finishing running
+      # @return [BBServices.Service] returns the service instance
       def run(params = {}, &block)
         new(params).tap do |service|
           service.run(&block)
         end
       end
 
-      ##
-      # Creates a new service class, then calls run!
+      # Creates the service instances and calls run! upon said instance
+      # @param [Hash] params The params which are passed to the service
+      # @param [Block] block The block which will be called upon the service finishing running
+      # @return [BBServices.Service] returns the service instance
       def run!(params = {}, &block)
         new(params).tap do |service|
           service.run!(&block)
         end
       end
 
-      ##
-      # Sets the service class
+      # An alias to {BBServices::Service}'s run method
+      alias call run
+
+      # An alias to {BBServices::Service}'s run! method
+      alias call! run!
+
+      # Sets the service class on the Class. Please note this is an internal method.
+      # @param [Class] klass The class which will be set as the service_class
+      # @return [BBServices.Service] returns the service instance
       def service_class(klass)
         @service_class = klass
       end
 
-      def get_service_class
+      # Gets the current service class
+      # @return [Class] returns the service class. Please note this is an internal method.
+      def internal_service_class
         @service_class
       end
     end
 
+    # Initializes the service with a hash of params
+    # @param [Hash] params The params which are passed to the service
     def initialize(params = {})
-      ##
-      # The object which will be assigned to the service
       @object = nil
-
-      ##
-      # The state of success, was the service successful
       @successful = false
-
-      ##
-      # The state of the run, has the service being ran
       @ran = false
-
-      ##
-      # The error that has been throw by the service
       @error = nil
-
-      ##
-      # The service class stored on the instance. This will override the
-      # service class set statically
       @service_class = nil
 
-      ##
-      # The params passed to the resource
       @params = params
     end
 
-    ##
-    # This runs the safe version of the service. E.g. Will rescue on exception
-    # and set the error attribute
+    # Runs the service using 'safe' execution. The @run variable will be set to true, initialize_service and run_service
+    # will then be called.
+    # @param [Block] block The block which will be called upon the service finishing running
+    # @return [BBServices.Service] returns the service instance
     def run(&block)
       set_ran
       begin
@@ -76,8 +86,10 @@ module BBServices
       end
     end
 
-    ##
-    # This runs the unsafe version of the service. E.g. Exceptions will be thrown
+    # Runs the service using 'unsafe' execution. The @run variable will be set to true,
+    # initialize_service and run_service will then be called.
+    # @param [Block] block The block which will be called upon the service finishing running
+    # @return [BBServices.Service] returns the service instance
     def run!(&block)
       set_ran
       begin
@@ -91,102 +103,173 @@ module BBServices
       end
     end
 
-    ##
-    # Sets the service_class instance variable
-    def service_class=(value)
-      @service_class = value
+    # An alias to {BBServices::Service}'s run method
+    alias call run
+
+    # An alias to {BBServices::Service}'s run! method
+    alias call! run!
+
+    # Sets the service_class on the instance. This will override the self.class.internal_service_class.
+    # @param [Class] new_service_class The new service class.
+    def set_service_class(new_service_class)
+      @service_class = new_service_class
+    end
+
+    # Sets the service_class on the instance. This will override the self.class.internal_service_class.
+    # @param [Class] new_service_class The new service class.
+    def service_class=(new_service_class)
+      set_service_class(new_service_class)
     end
 
-    ##
-    # Gets the service_class. This will go instance first, then static
+    # Gets the current service class. This will use @service_class if set, otherwise will fallback to
+    # self.class.internal_service_class.
+    # @return [Class] new_service_class The new service class.
     def service_class
-      @service_class ||= self.class.get_service_class
+      @service_class ||= self.class.internal_service_class
     end
 
-    def set_params(value)
-      @params = value
+    # Sets the params variable (@params) on the service.
+    # @param [Hash] new_params The new params Hash.
+    def set_params(new_params)
+      raise BBServices::ServiceHashTypeError unless new_params.is_a?(Hash)
+
+      @params = new_params
     end
 
-    def params=(value)
-      set_params(value)
+    # Sets the params variable (@params) on the service.
+    # @param [Hash] new_params The new params Hash.
+    def params=(new_params)
+      set_params(new_params)
     end
 
+    # Gets a single param using a key
+    # @param [String/Symbol] key The key which is used to find the param
+    # @return [Hash] The param found using the key
     def param_for(key)
       param(key)
     end
 
+    # Gets a single param using a key
+    # @param [String/Symbol] key The key which is used to find the param
+    # @return [Hash] The param found using the key
     def param(key)
       @params[key] if @params
     end
 
+    # Gets the number of params
+    # @return [Number] The number of params
     def number_of_params
       @params ? @params.length : 0
     end
 
+    # Returns true/false on if the service has been ran
+    # @return [Boolean] True/False value on if the service has been ran
     def ran?
       @ran
     end
 
+    # Returns true / false if the service has any params
+    # @return [Boolean] true/false if the service has any params
+    def params?
+      !!(@params && @params.length)
+    end
+
+    # An alias to {BBServices::Service}'s ran? method
+    alias run? ran?
+
+    # Returns true/false on if the service did succeed.
+    # @return [Boolean] true/false on if the service did succeed.
     def succeeded?
       successful?
     end
 
+    # Returns true/false on if the service was successful.
+    # @return [Boolean] true/false on if the service was successful.
     def successful?
       @successful
     end
 
+    # Returns true/false on if the service was unsuccessful. This will always be the inverse of successful?
+    # @return [Boolean] true/false on if the service failed.
     def failed?
       !succeeded?
     end
 
-    def success(&block)
-      call_block(&block) if succeeded?
+    # Calls the given block if the service was successful
+    def success
+      yield(self) if succeeded?
     end
 
-    def failure(&block)
-      call_block(&block) if failed?
+    # Calls the given block if the service failed
+    def failure
+      yield(self) if failed?
     end
 
-    def error?
-      !!@error
+    # Calls success on success?, failure on !success?
+    # @param [Proc] success The proc to be called upon a successful service
+    # @param [Proc] failure
+    # @return [Boolean] true/false if the service has any params
+    def on(success: proc {}, failure: proc {})
+      if successful?
+        success.call
+      else
+        failure.call
+      end
     end
 
-    def params?
-      !!@params
+    # Returns true / false if the service threw an error
+    # @return [Boolean] true/false on if an error has occurred
+    def error?
+      !!@error
     end
 
     protected
 
+    # Called upon run / run!, should be overridden in order to setup any variable
+    # initalization
     def initialize_service() end
 
+    # Called upon run, should be overridden in order to setup any variable
+    # initalization
     def run_service
       set_successful
       set_object(nil)
     end
 
+    # Called upon run, should be overridden in order to setup any variable
+    # initalization
     def run_service!
       set_successful
       set_object(nil)
     end
 
+    # Sets the @object instance variable, the object will be accessible via the .object property outside of the service
+    # @param obj The object which will be assigned to the @object instance variable
     def set_object(obj)
       @object = obj
     end
 
-    def set_error(error)
-      @error = error
+    private
+
+    # Sets the internal @ran instance variable
+    # @param [Boolean] ran True / False if the service has been ran
+    def set_ran(ran = true)
+      @ran = ran
     end
 
+    # Sets the internal @successful instance variable
+    # @param [Boolean] successful True / False if the service has been successful
     def set_successful(successful = true)
       @successful = successful
     end
 
-    def set_ran(ran = true)
-      @ran = ran
+    # Sets the internal @error instance variable
+    # @param [Error] error The error to be assigned
+    def set_error(error)
+      @error = error
     end
 
-    private
-
+    # Calls the block which has been passed
     def call_block
       yield(self) if block_given?
     end

data/lib/bbservices/service_chain.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# The BBServices namespace.
+module BBServices
+  # Container for chained services.
+  class ServiceChain
+
+    attr_reader :services
+
+    # Initializes the ServiceChain
+    def initialize
+      @services = []
+      @successful = true
+    end
+
+    def chain(params = {})
+      tap do |_service_chain|
+        if @successful
+          service = yield(params, self, previous_service)
+          process_service(service)
+        end
+      end
+    end
+
+    def previous_service
+      return nil unless @services.length
+
+      @services.last
+    end
+
+    # Returns true/false on if the chain did succeed.
+    # @return [Boolean] true/false on if the chain did succeed.
+    def succeeded?
+      successful?
+    end
+
+    # Returns true/false on if the chain was successful.
+    # @return [Boolean] true/false on if the chain was successful.
+    def successful?
+      @successful
+    end
+
+    # Returns true/false on if the chain was unsuccessful. This will always be the inverse of successful?
+    # @return [Boolean] true/false on if the chain failed.
+    def failed?
+      !succeeded?
+    end
+
+    # Calls the given block if the chain was successful
+    def success
+      yield(self) if succeeded?
+    end
+
+    # Calls the given block if the chain failed
+    def failure
+      yield(self) if failed?
+    end
+
+    # Calls success on success?, failure on !success?
+    # @param [Proc] success The proc to be called upon a successful chain
+    # @param [Proc] failure
+    # @return [Boolean] true/false if the chain has any params
+    def on(success: proc {}, failure: proc {})
+      if successful?
+        success.call
+      else
+        failure.call
+      end
+    end
+
+    # Returns true / false if the chain threw an error
+    # @return [Boolean] true/false on if an error has occurred
+    def error?
+      previous_service ? previous_service.error? : false
+    end
+
+    def error
+      previous_service ? previous_service.error : nil
+    end
+
+    private
+
+    def process_service(service)
+      if service.is_a?(BBServices::Service)
+        @services << service
+        @successful = service.successful?
+      else
+        @successful = !!service
+      end
+    end
+  end
+end

data/lib/bbservices/service_provider.rb

@@ -1,36 +1,63 @@
 # frozen_string_literal: true
 
+# The BBServices namespace.
 module BBServices
-  ##
-  #
+  # Module to allow external classes (Namely controllers) to interact with underlying service objects
   module ServiceProvider
     def self.included(base)
       base.class_eval do
-        ##
-        # Creates a brand new service of a given type
-        def service(service_type, service_params = {})
-          service_type.new.tap do |service|
-            service.set_params(service_params)
+        # Creates a service with a given type and params, the service instance will not be ran.
+        # Sets the @service instance on the object which includes this provider.
+        # @param [Class] service_type The class which should be instanciated
+        # @param [Hash] service_params The params which will be passed to the service
+        # @return [{BBServices::Service}] The service type instance
+        def create_service(service_type, service_params = {})
+          @service = service_type.new.tap do |new_service|
+            new_service.set_params(service_params)
           end
         end
 
-        ##
-        # Creates and runs a brand new service using the safe method
+        # Creates a service with a given type and params, the service instance will be ran using the run method.
+        # Sets the @service instance on the object which includes this provider.
+        # @param [Class] service_type The class which should be instanciated
+        # @param [Hash] service_params The params which will be passed to the service
+        # @param [Block] block The block to call upon running of the service is complete
+        # @return [{BBServices::Service}] The service type instance
         def run_service(service_type, service_params = {}, &block)
-          service(service_type, service_params).tap do |service|
+          create_service(service_type, service_params).tap do |service|
             service.service_class = service_type
             service.run(&block)
           end
         end
 
-        ##
-        # Creates and runs a brand new service using the unsafe method
+        # Creates a service with a given type and params, the service instance will be ran using the run! method.
+        # Sets the @service instance on the object which includes this provider.
+        # @param [Class] service_type The class which should be instanciated
+        # @param [Hash] service_params The params which will be passed to the service
+        # @param [Block] block The block to call upon running of the service is complete
+        # @return [{BBServices::Service}] The service type instance
         def run_service!(service_type, service_params = {}, &block)
-          service(service_type, service_params).tap do |service|
+          create_service(service_type, service_params).tap do |service|
             service.service_class = service_type
             service.run!(&block)
           end
         end
+
+        def chain_services(params = {}, &block)
+          @service_chain = BBServices.chain(params, &block)
+        end
+
+        # Returns the {BBService::Service} instance currently stored within @service
+        # @return [{BBService::Service}] The current service
+        def service
+          @service
+        end
+
+        # Returns the {BBServices::ServiceChain} instance currently stored within @service_chain
+        # @return [{BBServices::ServiceChain}] The current service
+        def service_chain
+          @service_chain
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bbservices
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Stuart Farnaby, Big Bear Studios
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-24 00:00:00.000000000 Z
+date: 2021-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: guard-rspec
@@ -66,6 +66,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.18.5
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.7.6
 description:
 email:
 executables: []
@@ -74,6 +88,7 @@ extra_rdoc_files: []
 files:
 - lib/bbservices.rb
 - lib/bbservices/service.rb
+- lib/bbservices/service_chain.rb
 - lib/bbservices/service_provider.rb
 homepage: https://gitlab.com/big-bear-studios-open-source/bbservices
 licenses: