service_objects_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfd8b349fec82efeaba05ceebd23dceb3f5b6b72840442cc7e4e5d22e219c89b
+  data.tar.gz: fcda7ca5e0417fcc890dc1e8867d6019af4c0dabf75d8b507065ab6b38fcf3ae
+SHA512:
+  metadata.gz: c03cda7db0b3b27378a6eadb576e13b5fb022b8a4fa333a8bddf103b81c101319e8cdf0c8683451e859478f4c9f71ed8204447c047fe3a88a8d456f28fecb86c
+  data.tar.gz: 0554bf7e6ec1b43463c2928b5378fc0e0e608677c70f29ce54befc120e744c313908d90ef6fd9b24d929e4c4f42533cd78dc1b20146fb5fbb5f97be216a7a82a

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (23-Feb-22)
+
+Initial gem skeleton and basic functionality.

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "rspec_junit_formatter"
+  gem "tzinfo-data", platforms: %i[mingw mswin x64_mingw jruby]
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Matthew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+# Service Objects for Rails
+
+[![mattwd7](https://circleci.com/gh/mattwd7/service_objects_rails.svg?style=svg)](https://app.circleci.com/pipelines/github/mattwd7/service_objects_rails?filter=all)
+[![Test Coverage](https://codecov.io/gh/mattwd7/service_objects_rails/graph/badge.svg)](https://codecov.io/gh/mattwd7/service_objects_rails)
+
+A lightweight, high-speed service layer for Rails applications.
+
+## Motivation
+Gone are the days of fat controllers and fat models! Service objects (sometimes known as Commands) enable an important service layer in your Rails applications to keep your code readable, reusable, and testable. Service objects help to facilitate a separation of concerns and the single responsibility principle. Here is an example of a service object that adds a new user to a table in a poker application:
+
+```
+module Services
+  class AddPlayerToTable
+    include Services::Base
+
+    def initialize(user_id:, table_id:)
+      @user = User.find(user_id)
+      @table = Table.find(table_id)
+    end
+
+    def call
+      confirm_player_has_available_funds
+      assign_player_to_table
+      queue_player_for_next_deal
+    end
+
+    private
+
+    attr_reader :user, :table
+
+    def confirm_player_has_available_funds
+      # business logic
+    end
+
+    def assign_player_to_table
+      # business logic
+    end
+
+    def queue_player_for_next_deal
+      # business logic
+    end
+  end
+end
+```
+Without this Service Object, our Rails models like User, Table, and Queue would require a knowledge of associated models and their logic, consequently bloating model classes and their tests. Instead, this Service Object orchestrates the necessary objects to perform the singular task of adding a player to a poker table.
+
+## Installation
+Include the gem in your Gemfile:
+```
+gem "service_objects_rails"
+```
+
+and install:
+```
+bundle install
+```
+
+Then generate boilerplate directories and gem configuration files with
+```
+rails generate services:install
+```
+
+This will create the `app/namespaces/services` directory which will hold the namespaced service objects you create and use in your application.
+
+## Quick start
+```
+## generate a service
+
+rails g services:new AddPlayerToTable user_id table_id
+
+## write out and test the service
+
+module Services
+  class AddPlayerToTable
+    include Services::Base
+
+    def initialize(user_id:, table_id:)
+      @user = User.find(user_id)
+      @table = Table.find(table_id)
+    end
+
+    def call
+      confirm_player_has_available_funds
+      assign_player_to_table
+      queue_player_for_next_deal
+    end
+
+    private
+
+    attr_reader :user, :table
+
+    def confirm_player_has_available_funds
+      # business logic
+    end
+
+    def assign_player_to_table
+      # business logic
+    end
+
+    def queue_player_for_next_deal
+      # business logic
+    end
+  end
+end
+
+## use the service
+
+# app/controllers/tables_controller.rb
+class TablesController < ApplicationController
+  def join_table
+    service_response = Services::AddPlayerToTable.call(
+      user_id: params[:user_id],
+      table_id: params[:table_id]
+    )
+
+    if service_response.success?
+      render :show, status: 204
+    else
+      render json: { errors: service_response.errors.full_messages }
+    end
+  end
+end
+```
+
+## Usage
+All service objects have the same skeleton: an `initialize` method, a `call` method, and an included `Services::Base` mixin. The `Services::Base` mixin enforces strict, predictable usage of service objects such that they
+
+1. Are always called with named arguemnts
+1. Can never be publicly instantiated; only `call`ed
+1. Always return an instance of a Services::Response object
+
+It is a best-practice to name service objects in the format <ACTION><NOUN> to abstract the responsibilty and function of the service at the highest level, e.g. `Services::AddPlayerToTable` as opposed to `Services::NewPlayerTable`.
+
+### Using the Generator
+To quickly whip up a new service object and corresponding spec, use the provided generator:
+```
+rails generate services:new <MyNewServiceName> <named_arg_1> <named_arg_2> ...
+```
+
+An example of using the generator:
+```
+rails g services:new AddPlayerToTable user_id table_id
+
+# app/namespaces/services/add_player_to_table.rb
+module Services
+  class AddPlayerToTable
+    include ServiceObject::Base
+
+    def initialize(user_id:, table_id:,)
+      @user_id = user_id
+      @table_id = table_id
+    end
+
+    def call
+    end
+
+    private
+
+    attr_reader :user_id, :table_id
+  end
+end
+
+
+# spec/namespaces/services/add_player_to_table_spec.rb
+include "rails_helper"
+
+RSpec.describe Services::AddPlayerToTable do
+  subject(:service_response) do
+    described_class.call(user_id: user_id, table_id: table_id)
+  end
+
+  let(:user_id) { nil }
+  let(:table_id) { nil }
+
+  it "does what it says" do
+  end
+
+  it "returns what is expected" do
+  end
+end
+```

data/lib/generators/services/install_generator.rb

@@ -0,0 +1,24 @@
+require "rails/generators"
+
+module Services
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __dir__)
+
+      desc "Creates the file structure for Service objects, " \
+        "generates a config files, and generates the ServiceBase module."
+
+      def copy_config
+        template(
+          "service_objects_rails_config.rb",
+          "#{Rails.root}/config/service_objects_rails.rb"
+        )
+      end
+
+      def setup_file_structure
+        empty_directory("#{Rails.root}/app/namespaces/services")
+        empty_directory("#{Rails.root}/spec/namespaces/services")
+      end
+    end
+  end
+end

data/lib/generators/services/new_generator.rb

@@ -0,0 +1,38 @@
+require "rails/generators"
+
+module Services
+  module Generators
+    class NewGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __dir__)
+
+      argument :service_name, type: :string
+      argument :service_args, type: :array, default: []
+
+      desc "Creates a new Service Object and corresponding spec file"
+
+      def create_new_service
+        template(
+          "new_service.erb",
+          "#{Rails.root}/app/namespaces/services/#{service_filepath}.rb"
+        )
+      end
+
+      def create_new_service_spec
+        template(
+          "new_service_spec.erb",
+          "#{Rails.root}/spec/namespaces/services/#{service_filepath}_spec.rb"
+        )
+      end
+
+      private
+
+      def service_filepath
+        service_name.gsub(/::/, "/")
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
+          .downcase
+      end
+    end
+  end
+end

data/lib/generators/templates/new_service.erb

@@ -0,0 +1,16 @@
+module Services
+  class <%= @service_name %>
+    include Services::Base
+
+    def initialize(<%= @service_args.map { |arg| "#{arg}:" }.join(", ") %>)
+      <%= @service_args.map { |arg| "@#{arg} = #{arg}" }.join("\n      ") %>
+    end
+
+    def call
+    end
+
+    private
+
+    attr_reader <%= @service_args.map { |arg| ":#{arg}" }.join(", ") %>
+  end
+end

data/lib/generators/templates/new_service_spec.erb

@@ -0,0 +1,13 @@
+require "rails_helper"
+
+RSpec.describe Services::<%= @service_name %> do
+  subject(:service_response) do
+    described_class.call<%= "(\n      #{@service_args.map { |arg| "#{arg}: #{arg}" }.join(",\n      ")}\n    )" if @service_args.any? %>
+  end
+
+  <%= @service_args.map { |arg| "let(:#{arg}) { nil }" }.join("\n  ") %>
+
+  it "does what it should"
+
+  it "returns what it ought to"
+end

data/lib/generators/templates/service_objects_rails_config.rb

@@ -0,0 +1,12 @@
+require "service_objects_rails"
+
+ServiceObjectsRails.config do |c|
+  # The Services::Response class is always returned after
+  # executing the #call on a Service. This object includes
+  # goodies like graceful error handling and returning with the
+  # object(s) upon which the Service operated in response.body.
+  # However, some consider it good practice to simply return the
+  # object(s) a service operated on. Set this to false to avoid
+  # Services::Response altogether.
+  # c.return_service_response_object = false
+end

data/lib/service_objects_rails.rb

@@ -0,0 +1,16 @@
+require "services/base"
+require "services/version"
+
+module ServiceObjectsRails
+  class << self
+    attr_writer :return_service_response_object
+
+    def config
+      yield self
+    end
+
+    def return_service_response_object
+      @return_service_response_object.nil? ? true : @return_service_response_object
+    end
+  end
+end

data/lib/services/base.rb

@@ -0,0 +1,24 @@
+require "services/response"
+
+module Services::Base
+  def self.included(base)
+    base.extend ClassMethods
+
+    base.private_class_method :new
+    base.send(:attr_reader, :response)
+  end
+
+  module ClassMethods
+    def call(**args)
+      service = new(**args)
+      service.instance_variable_set(:@response, Services::Response.new)
+
+      if ServiceObjectsRails.return_service_response_object
+        service.response.body = service.call
+        service.response
+      else
+        service.call
+      end
+    end
+  end
+end

data/lib/services/response.rb

@@ -0,0 +1,19 @@
+module Services
+  class Response
+    attr_accessor :body
+    attr_reader :errors
+
+    def initialize
+      @body = nil
+      @errors = []
+    end
+
+    def add_errors(*errors)
+      @errors.concat(Array(errors))
+    end
+
+    def success?
+      errors.empty?
+    end
+  end
+end

data/lib/services/version.rb

@@ -0,0 +1,3 @@
+module Services
+  VERSION = "0.1.0"
+end

data/service_objects_rails.gemspec

@@ -0,0 +1,38 @@
+$LOAD_PATH << File.expand_path("lib", __dir__)
+require "services/version"
+
+Gem::Specification.new do |gem|
+  gem.name = "service_objects_rails"
+  gem.version = Services::VERSION
+  gem.authors = ["Matthew Dick"]
+  gem.email = ["mattwd7@gmail.com"]
+  gem.summary = "A lightweight, high-speed service layer for Rails applications"
+  gem.description = "A lightweight, high-speed service layer for Rails applications"
+  gem.homepage = "https://github.com/mattwd7/service_objects_rails"
+  gem.license = "MIT"
+  gem.platform = Gem::Platform::RUBY
+  gem.required_ruby_version = ">= 2.5.0"
+  gem.require_path = "lib"
+  gem.files = Dir.glob("lib/**/*") + [
+    "service_objects_rails.gemspec",
+    "Gemfile",
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "README.md"
+  ]
+
+  gem.add_development_dependency "codecov", "~> 0.6"
+  gem.add_development_dependency "dotenv", "~> 2.7"
+  gem.add_development_dependency "factory_bot_rails", "~> 6.2"
+  gem.add_development_dependency "pry", "~> 0.14"
+  gem.add_development_dependency "rake", "~> 13.0"
+  gem.add_development_dependency "rails", "~> 7.0"
+  gem.add_development_dependency "rspec-rails", "~> 5.1"
+  gem.add_development_dependency "rspec", "~> 3.11"
+  gem.add_development_dependency "rubocop-performance", "~> 1.13"
+  gem.add_development_dependency "rubocop-rails", "~> 2.13"
+  gem.add_development_dependency "rubocop-rspec", "~> 2.8"
+  gem.add_development_dependency "rubocop", "~> 1.25"
+  gem.add_development_dependency "simplecov", "~> 0.21"
+  gem.add_development_dependency "standard", "~> 1.7"
+end

metadata

@@ -0,0 +1,253 @@
+--- !ruby/object:Gem::Specification
+name: service_objects_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Dick
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  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'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: A lightweight, high-speed service layer for Rails applications
+email:
+- mattwd7@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- lib/generators/services/install_generator.rb
+- lib/generators/services/new_generator.rb
+- lib/generators/templates/new_service.erb
+- lib/generators/templates/new_service_spec.erb
+- lib/generators/templates/service_objects_rails_config.rb
+- lib/service_objects_rails.rb
+- lib/services/base.rb
+- lib/services/response.rb
+- lib/services/version.rb
+- service_objects_rails.gemspec
+homepage: https://github.com/mattwd7/service_objects_rails
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.8
+signing_key:
+specification_version: 4
+summary: A lightweight, high-speed service layer for Rails applications
+test_files: []