services 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4987f523acb227a70a5fddee85a8fae8aab86f8c
-  data.tar.gz: 3c4f1ca4a27990a08b9f5fa691392e66329ce76c
+  metadata.gz: d822d6579be3909fe382b950cd93d69303fa06a0
+  data.tar.gz: 528251f7a5177f619d09402b32aaaf2a84bb9b2c
 SHA512:
-  metadata.gz: 4ecc46999894ba5049d92c79c33a7d1745d4ebd6bd2db3b61037ed940ed0cd936800df117926b8b76694868771ab78ba78b99a0da84d80cd40258431e987bbcb
-  data.tar.gz: 6d9c4a3d5e7360f4e8422395b1b78148bd21f567dc2949610256836316277dc29d86d38057bbb60f5499bb41562b723b0628b178ff020eaa42c389322daeebbb
+  metadata.gz: d6a2fc3cefd633a743bb5e86e8ffc2163e2a42c7f4b1406a912b7108f2603ca9f770644f90d6e9b9aa409087b19cf7f4064943ea045bdd425a2f504c458fc331
+  data.tar.gz: 23805aad75f6806727fb430eef2bdec3b943ed7c3750ae5e479c97268a76884af1b001d90dc2ebb362cee5d6a1e96c556070856e6f90e8553ba9d4e63d97f87e

data/README.md

@@ -5,7 +5,129 @@
 [![Dependency Status](https://gemnasium.com/krautcomputing/services.png)](https://gemnasium.com/krautcomputing/services)
 [![Code Climate](https://codeclimate.com/github/krautcomputing/services.png)](https://codeclimate.com/github/krautcomputing/services)
 
-Services is a opinionated set of modules that can be used to implement the use cases (or services, contexts, whatchamacallit) of a Ruby application.
+Services is a collection of modules and base classes that let you implement a nifty service layer in your Rails app.
+
+## Motivation
+
+A lot has been written about service layers in Rails apps. There are advantages and disadvantages of course, but after using Services since 2013 in several Rails apps, I must say that in my opinion the advantages far outweigh the disadvantages.
+
+**The biggest benefit you get with a service layer is that it makes it much easier to reason about your application, find a bug, or implement new features, when all your business logic is in services, not scattered in models, controllers, helpers etc.**
+
+## Usage
+
+For disambiguation, we let's write Services with a uppercase S when we mean this gem, and services with a lowercase s when we mean, well, the plural of service.
+
+### Basic principles
+
+Services is based on a couple of basic principles of what a service should be and do in your Rails app:
+
+* a service does one thing well (Unix philosophy)
+* a service can be run synchronously (in the foreground) or asynchronously (in the background)
+* a service can be unique, meaning only one instance of it should be run at a time
+* a service logs all the things (start time, end time, caller, exceptions etc.)
+* a service has its own exception class and all exceptions that it may raise must be of that class or a subclass
+* a service can be called with one or multiple objects or one or multiple object IDs
+
+Apart from these basic principles, you can implement the actual logic in a service any way you want.
+
+### Conventions
+
+Follow these conventions that Services expects/recommends:
+
+* services inherit from `Services::Base` (or `Services::BaseFinder`)
+* services are located in `app/services/`
+* services are namespaced with the model they operate on and their names are verbs, e.g. `app/services/users/delete.rb` defines `Services::Users::Delete`. If a service operates on multiple models or no models at all, don't namespace them (`Services::DoLotsOfStuff`) or namespace them by logical groups unrelated to models (`Services::Maintenance::CleanOldUsers`, `Services::Maintenance::SendDailySummary`, etc.)
+* Sometimes services must call other services. Try to not combine multiple calls to other services and business logic in one service. Instead, some services should contain only business logic and other services only a bunch of service calls but no (or little) business logic. This keeps your services nice and modular.
+
+### Dependence
+
+To process services in the background, Services uses [Sidekiq](https://github.com/mperham/sidekiq). Sidekiq is not absolutely required to use Services though, if it's not present, a service will raise an exception when you try to enqueue it for background processing. If you're using Sidekiq, make sure to load the Services gem after the Sidekiq gem.
+
+The SQL `Services::BaseFinder` (discussed further down) generates is optimized for Postgres. It might work with other databases but it's not guaranteed. If you're not using Postgres, don't use `Services::BaseFinder` or, even better, submit a PR that fixes it to work with your database!
+
+### Examples
+
+The following service takes one or more users or user IDs as an argument.
+
+```
+module Services
+  module Users
+    class Delete < Services::Base
+      def call(ids_or_objects)
+        users = find_objects(ids_or_objects)
+        users.each do |user|
+          user.destroy
+          Mailer.user_deleted(user).deliver
+        end
+        users
+      end
+    end
+  end
+end
+```
+
+As you can see, the helper `find_objects` is used to make sure you are dealing with an array of users from that point on, no matter whether `ids_or_objects` is a single user ID or user, or an array of user IDs or users.
+
+It's good practice to always return the objects a service has been operating on at the end of the service.
+
+Another example, this time using `Services::BaseFinder`:
+
+```
+module Services
+  module Users
+    class Find < Services::BaseFinder
+      private def process(scope, conditions)
+        conditions.each do |k, v|
+          case k
+          when :email, :name
+            scope = scope.where(k => v)
+          when :product_id
+            scope = scope.joins(:products).where("#{Product.table_name}.id" => v)
+          when :product_category_id
+            scope = scope.joins(:product_categories).where("#{ProductCategory.table_name}.id" => v)
+          else
+            raise ArgumentError, "Unexpected condition: #{k}"
+          end
+        end
+        scope
+      end
+    end
+  end
+end
+```
+
+Since you will create services to find objects for pretty much every model you have and they all look very similar, i.e. process the find conditions and return a `ActiveRecord::Relation`, you can let those services inherit from `Services::BaseFinder` to remove some of the boilerplate.
+
+`Services::BaseFinder` inherits from `Services::Base` and takes an array of IDs and a hash of conditions as parameters. It then extracts some special conditions (:order, :limit, :page, :per_page) that are handled separately and passes a `ActiveRecord::Relation` and the remaining conditions to the `process` method that the inheriting class must define. This method should handle all the conditions, extend the scope and return it.
+
+Check out [the source of `Services::BaseFinder`](lib/services/base_finder.rb) to understand what it does in more detail.
+
+### Helpers
+
+Your services inherit from `Services::Base` which makes several helper methods available:
+
+* `Rails.application.routes.url_helpers` is included so you use all Rails URL helpers.
+* `find_objects` and `find_object` let you automatically find object or a single object from an array of objects or object IDs, or a single object or object ID. The only difference is that `find_object` returns a single object whereas `find_objects` always returns an array.
+* `object_class` tries to figure out the class the service operates on. If you follow the service naming conventions and you have a service `Services::Products::Find`, `object_class` will return `Product`. Don't call it if you have a service like `Services::DoStuff` or it will raise an exception.
+* `controller` creates a `ActionController::Base` instance with an empty request. You can use it to call `render_to_string` to render a view from your service for example.
+
+Your services also automatically get a custom `Error` class, so you can `raise Error, 'Uh-oh, something has gone wrong!'` and a `Services::MyService::Error` will be raised.
+
+### Logging
+
+to be described...
+
+### Exception wrapping
+
+to be described...
+
+### Uniqueness checking
+
+to be described...
+
+### Background/asynchronous processing
+
+to be described...
 
 ## Requirements
 
@@ -25,10 +147,6 @@ Or install it yourself as:
 
     $ gem install services
 
-## Usage
-
-Coming soon...
-
 ## Contributing
 
 1. Fork it

data/lib/services/base.rb

@@ -25,7 +25,7 @@ module Services
 
     private
 
-    def find_objects(ids_or_objects, klass = service_class)
+    def find_objects(ids_or_objects, klass = object_class)
       ids_or_objects = Array(ids_or_objects)
       ids, objects = ids_or_objects.grep(Fixnum), ids_or_objects.grep(klass)
       if ids.size + objects.size < ids_or_objects.size
@@ -52,7 +52,7 @@ module Services
       end.first
     end
 
-    def service_class
+    def object_class
       self.class.to_s[/Services::([^:]+)/, 1].singularize.constantize
     rescue
       raise "Could not determine service class from #{self.class}"

data/lib/services/base_finder.rb

@@ -3,21 +3,21 @@ module Services
     def call(ids = [], conditions = {})
       ids, conditions = Array(ids), conditions.symbolize_keys
       special_conditions = conditions.extract!(:order, :limit, :page, :per_page)
-      scope = service_class
-        .select("DISTINCT #{service_class.table_name}.id")
-        .order("#{service_class.table_name}.id")
+      scope = object_class
+        .select("DISTINCT #{object_class.table_name}.id")
+        .order("#{object_class.table_name}.id")
       scope = scope.where(id: ids) unless ids.empty?
 
       scope = process(scope, conditions)
 
-      scope = service_class.where(id: scope)
+      scope = object_class.where(id: scope)
       special_conditions.each do |k, v|
         case k
         when :order
           order = if v == 'random'
             'RANDOM()'
           else
-            "#{service_class.table_name}.#{v}"
+            "#{object_class.table_name}.#{v}"
           end
           scope = scope.order(order)
         when :limit

data/lib/services/modules/uniqueness_checker.rb

@@ -70,7 +70,7 @@ module Services
           end
         when Fixnum, String, TrueClass, FalseClass, NilClass
           arg
-        when service_class
+        when object_class
           arg.id
         else
           raise "Don't know how to convert arg #{arg.inspect} for rescheduling."

data/lib/services/version.rb

@@ -1,3 +1,3 @@
 module Services
-  VERSION = '0.3.4'
+  VERSION = '0.4.0'
 end

data/services.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |gem|
   gem.platform      = Gem::Platform::RUBY
   gem.author        = 'Manuel Meurer'
   gem.email         = 'manuel@krautcomputing.com'
-  gem.summary       = ''
-  gem.description   = ''
+  gem.summary       = 'A nifty service layer for your Rails app'
+  gem.description   = 'A nifty service layer for your Rails app'
   gem.homepage      = 'http://krautcomputing.github.io/services'
   gem.license       = 'MIT'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: services
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Manuel Meurer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-11 00:00:00.000000000 Z
+date: 2014-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -122,7 +122,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
-description: ''
+description: A nifty service layer for your Rails app
 email: manuel@krautcomputing.com
 executables: []
 extensions: []
@@ -180,7 +180,7 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: ''
+summary: A nifty service layer for your Rails app
 test_files:
 - spec/services/base_spec.rb
 - spec/services/modules/call_logger_spec.rb