bbservices 3.1.1 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8068a7c26d7172de7b67e853055d740241e348496a65160f2dd9b7fd14cb2d8d
-  data.tar.gz: e74facc8ad5e219b0efef483cf5bdd8ea62dcce44c9b8fcaa6798c9a28e2d3fb
+  metadata.gz: 9bfbb265ecdb59d185f9dcca455a161320e596aefa68ff089b9c5fe393281282
+  data.tar.gz: d69045637f1877db91be419d99d916c8021f5dee49c9192fe2c12ff6ed816cfe
 SHA512:
-  metadata.gz: 69ed7f2a1296f2c5fca0f74931a5419aff418b1bf2aaaa2af3ac1350fb442bfb7a7bdc9d0ad6d52161b8e923760c65df8022368009b55313e476fa8dcc285a6e
-  data.tar.gz: b7f8b7b982d9ac06e09e8d39b38218babe107a0f0874f36c8bc9da9a92df581691a76f6f93e413e0a4088db353c7fe4f48c841d89fd7f46c21af2cdfe2eeed20
+  metadata.gz: 073e84467f9d639fad01eacfed718e83379e6b895079f9da68dfee1f83116de9f1cfbfd225e9b24e43c88851dcfee101d570ca30744c44f1fa90314e827d3725
+  data.tar.gz: c2c540f5dd58ba9c426fb280b15f65de19d762f2c9f832eddd8c0de4707d5779c60e8a132612b5da1d5b414ddf49c128296292c4ddee6f1a49684eaa12bede08

data/lib/bbservices/extensions/with_params.rb

@@ -0,0 +1,52 @@
+module BBServices
+  module Extensions
+    # Developer Notes
+    # The module WithParams hasn't been decided if it will enter into a production
+    # state due to the confusion over *args vs *kwargs
+
+    # module WithParams
+
+    #   # Default initalizer override which takes in the params. 
+    #   # This will run through the run / run! methods which can take these params
+    #   def initialize(*args, **kwargs)
+    #     @params = initialization_params
+    #   end
+
+    #   protected
+
+    #   # Returns true / false if the service has any params
+    #   # @return [Boolean] true/false if the service has any params
+    #   def has_params?
+    #     @params.length > 0
+    #   end
+
+    #   def number_of_params
+    #     @params.count
+    #   end
+
+    #   #
+    #   # Developer Notes
+    #   # Not sure if this functionality will be used at all...
+
+    #   # # 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 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.internal_service_class
+    #   # end
+
+    # end
+  end
+end

data/lib/bbservices/service.rb

@@ -2,206 +2,110 @@
 
 require_relative 'service_chain'
 
-# The BBServices namespace.
 module BBServices
-  # 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.
+  # The lightweight service object provided by BBServices. The basic functionality includes:
+  # - Ability to access user defined initalization. E.g. initalize(one = 1, two = 2)
+  # - Ability to chain services via '.then'
+  # - Ability to check success / failure
+  # - Ability to store errors thrown via services
   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 [Array] args The array of params which has been passed to run
       # @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|
+      def run(*args, **kwargs, &block)
+        new(*args, **kwargs).tap do |service|
           service.run(&block)
         end
       end
 
       # 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
+      # @param [Array] args The array of params which has been passed to run!
+      # @param [Block] block The block which will be called upon the service finishing running successfully
       # @return [BBServices.Service] returns the service instance
-      def run!(params = {}, &block)
-        new(params).tap do |service|
+      def run!(*args, **kwargs, &block)
+        new(*args, **kwargs).tap do |service|
           service.run!(&block)
         end
       end
-
-      # 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
-
-      # 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 = {})
-      @object = nil
-      @successful = false
-      @ran = false
-      @error = nil
-      @service_class = nil
-
-      @params = params
-    end
-
-    # Runs the service using 'safe' execution. The @run variable will be set to true, initialize_service and run_service
-    # will then be called.
+    # Runs the service using 'safe' execution. The @run variable will be set to true, then
+    # the run method will 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
+        @ran = true
+        successful = on_run
+        set_successful(successful == nil ? true : !!successful)
       rescue => e
         set_successful(false)
-        set_error(e)
+        register_error(e)
       ensure
-        call_block(&block)
+        call_block(block) if block_given?
       end
     end
 
-    # Runs the service using 'unsafe' execution. The @run variable will be set to true,
-    # initialize_service and run_service will then be called.
+    # Runs the service using 'unsafe' execution. The @run variable will be set to true, then
+    # the run! method will 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)
+        @ran = true
+        successful = on_run!
+        set_successful(successful == nil ? true : !!successful)
+        call_block(block) if block_given?
       rescue => e
         set_successful(false)
-        set_error(e)
+        register_error(e)
         raise e
       end
     end
 
-    # 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 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.internal_service_class
-    end
-
-    # 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)
+    # Returns a ServiceChain with the service as a registered service.
+    # The service must have been ran in order to call this chaining method.
+    def then(*args, &block)
+      raise BBServices::ServiceMustRunBeforeChainingError if !self.ran?
 
-      @params = new_params
-    end
-
-    # 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
+      BBServices::ServiceChain.new(self).then(block)
     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)
+      !!@ran
     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?
+    def run?
+      !!@ran
     end
 
     # Returns true/false on if the service was successful.
     # @return [Boolean] true/false on if the service was successful.
     def successful?
-      @successful
+      (@successful == nil ? false : @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?
+      (@successful == nil ? false : !@successful) 
     end
 
     # Calls the given block if the service was successful
-    def success
+    def success(&block)
       yield(self) if succeeded?
     end
 
     # Calls the given block if the service failed
-    def failure
+    def failure(&block)
       yield(self) if failed?
     end
 
@@ -212,66 +116,63 @@ module BBServices
     def on(success: proc {}, failure: proc {})
       if successful?
         success.call
-      else
+      elsif failed?
         failure.call
       end
     end
 
-    # Returns true / false if the service threw an error
+    # Returns true / false if the service threw an error.
     # @return [Boolean] true/false on if an error has occurred
     def error?
-      !!@error
+      errors.count > 0
     end
 
-    protected
+    def error
+      errors.first
+    end
 
-    # Called upon run / run!, should be overridden in order to setup any variable
-    # initalization
-    def initialize_service() end
+    def errors
+      @errors ||= []
+    end
+
+    alias_method :succeeded?, :successful?
+    alias_method :call, :run
+    alias_method :call!, :run!
 
-    # Called upon run, should be overridden in order to setup any variable
-    # initalization
-    def run_service
-      set_successful
-      set_object(nil)
+    protected
+
+    # Called upon run. 
+    # @return (nil, boolean) a nil value will automatically set the successful value as
+    # success upon exiting of this method, a true / false value will set the successful value
+    # to that return
+    def on_run
+      raise NotImplementedError.new('#run must be implemented on subclass')
     end
 
-    # Called upon run, should be overridden in order to setup any variable
-    # initalization
-    def run_service!
-      set_successful
-      set_object(nil)
+    # Called upon run.
+    # @return (nil, boolean) a nil value will automatically set the successful value as
+    # success upon exiting of this method, a true / false value will set the successful value
+    # to that return
+    def on_run!
+      raise NotImplementedError.new('#run must be implemented on subclass')
     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
+    def call_block(block)
+      block.call(self)
     end
 
     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
 
-    # Sets the internal @error instance variable
+    # Adds an error to the errors list
     # @param [Error] error The error to be assigned
-    def set_error(error)
-      @error = error
-    end
-
-    # Calls the block which has been passed
-    def call_block
-      yield(self) if block_given?
+    def register_error(error)
+      errors << error
     end
   end
 end

data/lib/bbservices/service_chain.rb

@@ -1,30 +1,36 @@
 # 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
+    # @services a list of the services in the chain
+    def initialize(service)
+
+      raise NilServiceInChainError if service.nil?
+
+      @successful = nil
+      @services = [service]
     end
 
-    def chain(params = {})
-      tap do |_service_chain|
-        if @successful
-          service = yield(params, self, previous_service)
-          process_service(service)
-        end
+    # Creates a new chain in the service with block, returns the chain instance for method chaining.
+    # The block should be used to call the next service and recieves the following params:
+    # - BBServices::ServiceChain (self)
+    def chain(&block)
+      self.tap do |c|
+        c.send(:_chain, block)
       end
     end
 
-    def previous_service
-      return nil unless @services.length
+    alias_method :then, :chain
 
+    # Returns the last service which was ran. This will return the last
+    # service, if the previous chain returned a non-service instance
+    def last_service
       @services.last
     end
 
@@ -34,16 +40,16 @@ module BBServices
       successful?
     end
 
-    # Returns true/false on if the chain was successful.
-    # @return [Boolean] true/false on if the chain was successful.
+    # Returns true/false on if the service was successful.
+    # @return [Boolean] true/false on if the service was successful.
     def successful?
-      @successful
+      (@successful == nil ? false : @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.
+    # 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?
+      (@successful == nil ? false : !@successful) 
     end
 
     # Calls the given block if the chain was successful
@@ -68,25 +74,40 @@ module BBServices
       end
     end
 
-    # Returns true / false if the chain threw an error
+    # Returns a true / false value if an error has been thrown, this
+    # will be passed to the last_service if one is avalible, otherwise
+    # false will be returned
     # @return [Boolean] true/false on if an error has occurred
     def error?
-      previous_service ? previous_service.error? : false
+      last_service ? last_service.error? : false
     end
 
-    def error
-      previous_service ? previous_service.error : nil
+    # Returns all of the errors from the last_service, if no last_service
+    # is avalible then an empty array will be returned
+    def errors
+      last_service ? last_service.errors : []
     end
 
     private
 
-    def process_service(service)
-      if service.is_a?(BBServices::Service)
-        @services << service
-        @successful = service.successful?
-      else
-        @successful = !!service
+    def _chain(block)
+      if _continue_chain?
+        service = block.call(self)
+
+        if BBServices.is_a_service?(service)
+          @successful = service.successful?
+          @services << service
+        else
+          raise BBServices::ServiceExpectedError
+        end
       end
     end
+
+    # Returns true / false if the chain is able to continue, follows the following:
+    # - If we don't have a last service, return true
+    # - If we have a last service check the successful? method
+    def _continue_chain?
+      last_service.successful?
+    end
   end
 end

data/lib/bbservices/service_provider.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
-# The BBServices namespace.
 module BBServices
-  # Module to allow external classes (Namely controllers) to interact with underlying service objects
+
+  # Module to allow external classes to interact with underlying service objects
+  # in a structured way. This will allow the setting of services upon the calling
+  # of given methods. Services will also be bound to the provider.
   module ServiceProvider
     def self.included(base)
       base.class_eval do
+
         # 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
+        def create_service(service_type, *args, **kwargs)
+          @service = service_type.new(*args, **kwargs)
         end
 
         # Creates a service with a given type and params, the service instance will be ran using the run method.
@@ -23,9 +24,8 @@ module BBServices
         # @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)
-          create_service(service_type, service_params).tap do |service|
-            service.service_class = service_type
+        def run_service(service_type, *args, **kwargs, &block)
+          create_service(service_type, *args, **kwargs).tap do |service|
             service.run(&block)
           end
         end
@@ -36,28 +36,19 @@ module BBServices
         # @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)
-          create_service(service_type, service_params).tap do |service|
-            service.service_class = service_type
+        def run_service!(service_type, *args, **kwargs, &block)
+          create_service(service_type, *args, **kwargs).tap do |service|
             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
+        # Returns the {BBService::Service} instance currently stored within @service. This is set
+        # when a single service is ran. It will not be set when chain_service is used and service_chain
+        # should be used instead.
         # @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

data/lib/bbservices.rb

@@ -4,11 +4,40 @@ require_relative 'bbservices/service'
 require_relative 'bbservices/service_chain'
 require_relative 'bbservices/service_provider'
 
-# The BBServices namespace.
+require_relative 'bbservices/extensions/with_params'
+
+# The BBServices namespace. Provides helper methods to aid with
+# service resolution
 module BBServices
-  def self.chain(params = {}, &block)
-    BBServices::ServiceChain.new.tap do |service_chain|
-      service_chain.chain(params, &block)
+
+  class NilServiceInChainError < StandardError
+    def message
+      'BBServices - A BBService must be passed to a chain'
+    end
+  end
+
+  class ServiceMustRunBeforeChainingError < StandardError
+    def message
+      'BBServices - Service must be ran before chaining via then can occur'
+    end
+  end
+
+  class ServiceExpectedError < StandardError
+    def message
+      'BBServices - A service must be returned from the given block'
+    end
+  end
+
+  class << self
+
+    # Returns true if a BBServices::Service is passed, false for all other types
+    def is_a_service?(service)
+      service.is_a?(BBServices::Service)
+    end
+
+     # Returns false if a BBServices::Service is passed, true for all other types
+    def is_not_a_service?(service)
+      !BBServices.is_a_service?(service)
     end
   end
 end

metadata

@@ -1,85 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: bbservices
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 4.0.1
 platform: ruby
 authors:
 - Stuart Farnaby, Big Bear Studios
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-12 00:00:00.000000000 Z
+date: 2025-04-27 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
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.9.0
+        version: 3.4.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.9.0
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: '1.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: '1.13'
+        version: 3.4.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.5
+        version: 0.22.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !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
+        version: 0.22.0
 description:
 email:
 executables: []
@@ -87,10 +45,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/bbservices.rb
+- lib/bbservices/extensions/with_params.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
+homepage: https://github.com/bigbearstudios/bbservices-ruby
 licenses:
 - MIT
 metadata: {}
@@ -102,16 +61,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
-summary: A simple service library for Ruby. Please see BBActiveRecordServices for
-  a Rails / AR service library
+summary: A simple service library for Ruby
 test_files: []