bbservices 2.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a49db154b10753f348203bbc19442fd51843284a04e234d979987d0112350ba1
-  data.tar.gz: a2bfd7d600dbb1e8532c991aa2fe21f2f6a60d8d80e2e7defc97398f7d6fcb8e
+  metadata.gz: 8068a7c26d7172de7b67e853055d740241e348496a65160f2dd9b7fd14cb2d8d
+  data.tar.gz: e74facc8ad5e219b0efef483cf5bdd8ea62dcce44c9b8fcaa6798c9a28e2d3fb
 SHA512:
-  metadata.gz: 55fda5b3d407d2a47cc311a849d12dcc6653bda3af5ee9b9b148b9a4400f7df7ace55c1739cb0f4d2310cd182768e7d42ee70c7189d1b2cc3c8d3d02b1753c64
-  data.tar.gz: e29fab244b847f80eaa751a4c54120cbb8ad4e8edcec1ca597dbdfcc2a697c51218b471f32106e1fdf7c22b2b23be41e95dd35f0be837facfa5e94d263538a15
+  metadata.gz: 69ed7f2a1296f2c5fca0f74931a5419aff418b1bf2aaaa2af3ac1350fb442bfb7a7bdc9d0ad6d52161b8e923760c65df8022368009b55313e476fa8dcc285a6e
+  data.tar.gz: b7f8b7b982d9ac06e09e8d39b38218babe107a0f0874f36c8bc9da9a92df581691a76f6f93e413e0a4088db353c7fe4f48c841d89fd7f46c21af2cdfe2eeed20

data/lib/bbservices.rb

@@ -1,2 +1,14 @@
+# frozen_string_literal: true
+
 require_relative 'bbservices/service'
-require_relative 'bbservices/service_provider'
+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,74 +1,84 @@
+# 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
-  class Service
-    attr_reader :params, :object, :errors
+  # Error thrown when a Hash type isn't given
+  class ServiceHashTypeError < StandardError
+    def message
+      'Params need to be a Hash'
+    end
+  end
 
-    ##
-    # Creates a new service class, then calls run
-    def self.run(params = {}, &block)
-      self.new(params).tap do |service|
-        service.run(&block)
+  # The lightweight service object provided by BBServices.
+  class Service
+    attr_reader :params, :object, :error
+
+    class << self
+
+      # 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
-    end
 
-    ##
-    # Creates a new service class, then calls run! 
-    def self.run!(params = {}, &block)
-      self.new(params).tap do |service|
-        service.run!(&block)
+      # 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
-    end
 
-    ##
-    # Sets the service class
-    def self.service_class(klass)
-      @service_class = klass
-    end
+      # An alias to {BBServices::Service}'s run method
+      alias call run
+
+      # An alias to {BBServices::Service}'s run! method
+      alias call! run!
 
-    ##
-    # Gets the service class
-    def self.get_service_class
-      @service_class
+      # 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
+
+      # 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 errors which are returned by the service
-      @errors = nil
-
-      ##
-      # The service class stored on the instance. This will override the
-      # service class set statically
+      @error = nil
       @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
         initialize_service
         run_service
-      rescue StandardError => e
+      rescue => e
         set_successful(false)
         set_error(e)
       ensure
@@ -76,128 +86,192 @@ 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
         initialize_service
         run_service!
         call_block(&block)
-      rescue StandardError => e
+      rescue => e
         set_successful(false)
         set_error(e)
         raise e
       end
     end
 
-    def set_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 instance variable
-    def service_class=(value)
-      set_service_class(value)
+    # 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 && !errors?)
+      successful?
     end
 
+    # Returns true/false on if the service was successful.
+    # @return [Boolean] true/false on if the service was successful.
     def successful?
-      (@successful && !errors?)
+      @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 errors?
-      !!(@errors && @errors.length.positive?)
+    # 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)
-      set_errors([]) unless @errors
-      @errors << error
-    end
+    private
 
-    def set_errors(errors)
-      @errors = errors
+    # 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
   end
-end
+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,42 +1,64 @@
+# frozen_string_literal: true
 
-module BBServices 
-  ##
-  # 
+# 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.extend ClassMethods
       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|
-            service.set_service_class(service_type)
+          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|
-            service.set_service_class(service_type)
+          create_service(service_type, service_params).tap do |service|
+            service.service_class = service_type
             service.run!(&block)
           end
         end
-      end
-    end
 
-    module ClassMethods
-      
+        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
-end
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: bbservices
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Stuart Farnaby, Big Bear Studios
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-18 00:00:00.000000000 Z
+date: 2021-06-12 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.7.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.7.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -30,14 +44,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.86.0
+        version: '1.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.86.0
+        version: '1.13'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -52,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: []
@@ -60,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:
@@ -73,7 +102,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="