service_record 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 904da829c98aa5d247c5979f1a01d4a23214e96cb24855bd3ca501275f28dbec
+  data.tar.gz: 1b5443f94ceab5481cbf3afcb08180ca3af00de5ab4e9ec04e315bb431f9c3ef
+SHA512:
+  metadata.gz: 02bebf02ace3c9af193819c7ff4ce0cd33427ef6f7e91b8911a0f6c3ceb2a547c0f4dbd301409652dc0f199e1ca5de304b8e2732c8516d655f11fb7597504961
+  data.tar.gz: cd925c97f73d12b5af2ca54351b93ee64654e5065c7e9363281f5542976941ccf99f73dbd474d77b834c8b622e0c4d737e373c221064803cdf01a959b24c2401

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.0
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in service_record.gemspec
+gemspec
+
+gem 'rake', '~> 12.3'
+gem 'rspec', '~> 3.9'

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    service_record (1.0.0)
+      activemodel (~> 6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.0.2.2)
+      activesupport (= 6.0.2.2)
+    activesupport (6.0.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    concurrent-ruby (1.1.6)
+    diff-lcs (1.3)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.0)
+    rake (12.3.3)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.6)
+      thread_safe (~> 0.1)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 12.3)
+  rspec (~> 3.9)
+  service_record!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Muhammad Usman
+
+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,182 @@
+# ServiceRecord
+
+An ActiveRecord lookalike but for business model requirements, a.k.a Service Objects.
+
+Rails is packed with all the amazing tools to get you started with building your new awesome project and enforces reliable and battle-tested guidelines. One of the guideline is "**thin controllers and fat models**", but sometimes (actually most of the time) its difficult to follow because most business requirements are not that simple like most CRUD operations. 
+
+Enters, ServiceRecord. Its similar to ActiveRecord models but their sole purpose is to perform a big/complex/muilt-step task without bloating the controllers or models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'service_record'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install service_record
+```
+
+Now you can start creating new service classes. Rails generator can be used to create new services, e.g, the following will create a service class file `app/services/authenticate_user.rb`.
+
+```shell
+rails g service authenticate_user
+```
+
+## Usage
+
+A basic Service class looks like the following
+
+```ruby
+class MyService < ApplicationService
+  attribute :email, :string
+  attribute :password, :string
+
+  validates :email, :password, presence: true
+
+  def perform
+  end
+end
+```
+
+Now you can invoke this service by writting;
+
+```ruby
+response = MyService.perform(email: '', password: '')
+```
+
+The returned response from a service will have the following useful attributes/methods,
+
+* `success?` contains true if service was performed without any errors, false otherwise
+* `failure?` contains opposite of success?
+* `result` contains returned value of service perform function
+* `errors` contains details about issues that occurr while performing the service 
+
+
+
+## Example
+
+Let's take a real world example of users controller and the sign_in action that involes JWT authentication.
+
+Without ServiceRecord 🙈
+
+```ruby
+# Inside controllers/users_controller.rb
+def sign_in
+  token = nil
+  errors = []
+
+  # Basic validation
+  errors << 'Email is required' if params[:email].blank?
+  errors << 'Email is invalid' if params[:email].present? && /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i.match?(params[:email])
+  errors << 'Password is required' if params[:password].blank?
+
+  if errors.size == 0
+    user = User.find_by(email: params[:email]).try(:authenticate, params[:password])
+
+    if user.present?
+      token = JsonWebToken.encode(user_id: user.id)
+    else
+      errors << 'Invalid credentials'
+    end
+  end
+
+  if errors.size == 0
+    render json: token
+  else
+    render json: errors, status: :unauthorized
+  end
+end
+```
+
+With ServiceRecord 😍
+
+```ruby
+# Inside services/authenticate_user.rb
+class AuthenticateUser < ApplicationService
+  attribute :email, :string
+  attribute :password, :string
+
+  validates :email, :password, presence: true
+  validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i }
+
+  def perform
+    user = User.find_by(email: email).try(:authenticate, password)
+
+    return JsonWebToken.encode(user_id: user.id) if user.present?
+    
+    errors.add :authentication, 'invalid credentials'
+  end
+end
+
+
+# Inside controllers/users_controller.rb
+def sign_in
+  response = AuthenticateUser.perform(params.permit(:email, :password))
+
+  if response.success?
+    render json: response.result
+  else
+    render json: response.errors, status: :unauthorized
+  end
+end
+```
+
+## Validations
+
+ServiceRecord extends on `ActiveModel::Validations`, so, everything that you can do there can be done inside a service class and ServiceRecord will make sure that a service only runs the perform function when all validations are passed, otherwise `errors` will contain details about the validation issues. Since services don't have an underlining object that needs to persisted like in ActiveRecord, you should avoid conditons filters like on create/update/save etc.
+
+You can also define callbacks like `before_validation` and `after_validation` just like you do inside an ActiveRecord class.
+
+
+## Custom Errors
+
+Just like validation errors, you can also add custom errors that you want to be reported. It useful to handle errors which are not related to input parameters validation. E.g.
+
+```ruby
+errors.add :authentication, 'invalid credentials'
+```
+
+## Callbacks
+
+You can also add callbacks on the perform function similar to [ActiveJob's](https://edgeguides.rubyonrails.org/active_job_basics.html#callbacks) perform function. E.g.
+
+```ruby
+class SampleService < ApplicationService
+  before_perform :do_something
+
+  def perform
+  end
+
+  private
+    def do_something
+    end
+end
+```
+
+Availble callbacks are `before_perform`, `after_perform` and `around_perform`. If a `before_perform` calls `throw :abort`, the callback chain is hallted and perform function would not be called.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/uxxman-sherwani/service_record.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "service_record"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rails/generators/service/service_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators/named_base'
+
+module Rails
+  module Generators
+    class ServiceGenerator < Rails::Generators::NamedBase
+      desc 'This generator creates a service file at app/services'
+
+      def self.default_generator_root
+        __dir__
+      end
+
+      def create_service_file
+        template 'service.rb', File.join('app/services', class_path, "#{file_name}.rb")
+
+        in_root do
+          if behavior == :invoke && !File.exist?(application_service_file_name)
+            template 'application_service.rb', application_service_file_name
+          end
+        end
+      end
+
+      private
+
+      def application_service_file_name
+        'app/services/application_service.rb'
+      end
+    end
+  end
+end

data/lib/rails/generators/service/templates/application_service.rb.tt

@@ -0,0 +1,4 @@
+<% module_namespacing do -%>
+class ApplicationService < ServiceRecord::Base
+end
+<% end -%>

data/lib/rails/generators/service/templates/service.rb.tt

@@ -0,0 +1,15 @@
+<% module_namespacing do -%>
+class <%= class_name %> < ApplicationService
+  # Example attributes
+  #
+  # attribute :email, :string
+  # attribute :password, :string
+
+  # Example validations
+  #
+  # validates :email, :password, presence: true
+
+  def perform
+  end
+end
+<% end -%>

data/lib/service_record.rb

@@ -0,0 +1,3 @@
+require 'active_model'
+require 'service_record/base'
+require 'service_record/version'

data/lib/service_record/base.rb

@@ -0,0 +1,38 @@
+require 'service_record/callbacks'
+
+module ServiceRecord
+  class Base
+    include Callbacks
+    include ActiveModel::Attributes
+    include ActiveModel::Validations
+    include ActiveModel::AttributeAssignment
+    include ActiveModel::Validations::Callbacks
+
+    def self.perform(args = {})
+      new.tap do |service|
+        service.attributes = args
+
+        if service.valid?
+          service.run_callbacks :perform do
+            service.result = service.perform
+            service.result = nil if service.failure?
+          end
+        end
+      end
+    end
+
+    attr_accessor :result
+
+    def success?
+      errors.empty?
+    end
+
+    def failure?
+      !success?
+    end
+
+    def perform
+      raise NotImplementedError
+    end
+  end
+end

data/lib/service_record/callbacks.rb

@@ -0,0 +1,25 @@
+module ServiceRecord
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveSupport::Callbacks
+
+      define_callbacks :perform
+    end
+
+    class_methods do
+      def before_perform(*filters, &blk)
+        set_callback(:perform, :before, *filters, &blk)
+      end
+
+      def after_perform(*filters, &blk)
+        set_callback(:perform, :after, *filters, &blk)
+      end
+
+      def around_perform(*filters, &blk)
+        set_callback(:perform, :around, *filters, &blk)
+      end
+    end
+  end
+end

data/lib/service_record/version.rb

@@ -0,0 +1,3 @@
+module ServiceRecord
+  VERSION = '1.0.0'
+end

data/service_record.gemspec

@@ -0,0 +1,30 @@
+require_relative 'lib/service_record/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'service_record'
+  spec.version       = ServiceRecord::VERSION
+  spec.authors       = ['Muhammad Usman']
+  spec.email         = ['uxman.sherwani@gmail.com']
+
+  spec.summary       = 'Service objects for rails'
+  spec.description   = 'ActiveRecord lookalike but for business model requirements'
+  spec.homepage      = 'https://github.com/uxxman/service_record'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activemodel', '~> 6.0'
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: service_record
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Muhammad Usman
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-04-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: ActiveRecord lookalike but for business model requirements
+email:
+- uxman.sherwani@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rails/generators/service/service_generator.rb
+- lib/rails/generators/service/templates/application_service.rb.tt
+- lib/rails/generators/service/templates/service.rb.tt
+- lib/service_record.rb
+- lib/service_record/base.rb
+- lib/service_record/callbacks.rb
+- lib/service_record/version.rb
+- service_record.gemspec
+homepage: https://github.com/uxxman/service_record
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/uxxman/service_record
+  source_code_uri: https://github.com/uxxman/service_record
+  changelog_uri: https://github.com/uxxman/service_record
+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.1.2
+signing_key: 
+specification_version: 4
+summary: Service objects for rails
+test_files: []