performify 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5d73a6fd3521ef86fbaeae9cb733e410e6101a5
-  data.tar.gz: fd8f33d33a3d9ac5309b53c097c1417db447c5cb
+  metadata.gz: c4e16b9f54a462104c0d2851bbbb75d30a36ae4d
+  data.tar.gz: 4788ceeb7f37d2210c400afdbc628497386d2d9a
 SHA512:
-  metadata.gz: da1783feeb0b3a51ed5314cb045e00912d67622f4d29231b532b4a49f0bfc25b8f4c7fdfcbc588bb85c0bcd484dd093746feb96943ce534c52ec791661245a6b
-  data.tar.gz: 7e2ac421eff8be0222d97263266e784ad281e02e780c5c54aaf66151e0252b7c66274794ff121b0e8f82130c2e4169aeb3e8c0e43006ebb69997e754dfd15fe5
+  metadata.gz: a08337228b009943e7995b4384c30724f7685264bcea0ba1afda47643e5790924a8b84f6971cb4be0a5d071e882096b4516595a80b8bee10c78f6e5db4a7d7ec
+  data.tar.gz: 2516c4e62c09d77ed0681a46c06ca2650f906d480a57f61bd4f5091e02bf0753a8005622c6dcad49a8cfba20b6d76de3ce30cd1063f2d2694bfed3767d3b30cc

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.byebug_history

data/.rubocop.yml

@@ -0,0 +1,81 @@
+AllCops:
+  Exclude:
+    - 'bin/*'
+    - 'spec/**/*_spec.rb'
+
+Rails:
+  Enabled: false
+
+Documentation:
+  Enabled: false
+
+Metrics/ClassLength:
+  CountComments: false
+  Max: 300
+
+Metrics/LineLength:
+  Max: 120
+  AllowHeredoc: true
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Rails/Validation:
+  Enabled: false
+
+Rails/HasAndBelongsToMany:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - db/migrate/*
+
+Lint/HandleExceptions:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Style/CommentAnnotation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/SpaceInsideBrackets:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/MultilineMethodCallIndentation:
+  Enabled: false
+
+Style/ClosingParenthesisIndentation:
+  Enabled: false
+
+Style/MultilineMethodCallBraceLayout:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Bundler/OrderedGems:
+  Enabled: false

data/.travis.yml

@@ -2,4 +2,9 @@ sudo: false
 language: ruby
 rvm:
   - 2.3.1
-before_install: gem install bundler -v 1.14.6
+before_install:
+  - gem install bundler -v 1.14.6
+install:
+  - bin/setup
+before_script:
+  - bin/rubocop

data/README.md

@@ -1,8 +1,6 @@
 # Performify
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/performify`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+It's well-known practice that has been proved in many large projects to move server logic into separated service classes. This approach gives a lot of advantages, because when you are able to create object that incapsulates your logic it's much easier to develop, search, control and test. And `performify` helps you to do it in nice and easy way with minimum of pain and maximum of result.
 
 ## Installation
 
@@ -14,28 +12,246 @@ gem 'performify'
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install performify
+```
+$ gem install performify
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+How to have a deal with services:
+
+1. Define `ApplicationService`
+2. Create new service inherited from `ApplicationService`
+3. Implement `execute!` method
+4. Use `super` to work with db transaction and automatic success / fail workflow control
+5. Use `success!` and `fail!` to control everything by hands
+6. Use `on_success` / `on_fail` to define callbacks
+
+### ApplicationService
+
+So, first of all it's better to create `ApplicationService` class that will be used as base for all services in your project. You can put any shared logic (like, authorization, for example) here:
+
+```ruby
+class ApplicationService < Performify::Base
+  def authorize!(record)
+    # you can put authorization logic here and use it from inherited services
+  end
+end
+```
+
+This is, for example, how authorization can be implemented for `Pundit`:
+
+```ruby
+class ApplicationService < Performify::Base
+  def authorize!(record, query = default_query, record_policy = nil)
+    record_policy ||= policy(record)
+    return if record_policy.public_send(query)
+
+    raise Pundit::NotAuthorizedError, query: query, record: record, policy: record_policy
+  end
+
+  def default_query
+    @default_query ||= "#{self.class.name.demodulize.underscore.to_sym}?"
+  end
+
+  def policy(record)
+    @policy ||= Pundit.policy!(@current_user, record)
+  end
+end
+```
+
+### Service: database
+
+Now, to define new service just create new class and inherit it from `ApplicationService`:
+
+```ruby
+module Users
+  class Destroy < ApplicationService
+    def execute!
+      # current user is already available, so feel free to use it
+      # to get user's context
+
+      authorize! current_user unless force?
+
+      # block passed into super's implementation will be executed
+      # in transaction, so you can do multiple data operations, and final
+      # result of this block will be used to determine result of execution
+
+      super do
+        if current_user.update(destroyed_at: Time.zone.now)
+          current_user.comments.find_each do |c|
+            s = Comments::Destroy.new(current_user, c)
+            s.execute!
+
+            # it's also ok to raise ActiveRecord::Rollback, it will be handled
+            # gracefully as regular execution fail
+
+            raise ActiveRecord::Rollback unless s.success?
+          end
+        end
+      end
+    end
+
+    def force?
+      # additional instance variables can be passed as named args into
+      # initializer and accessed in service flow
+
+      force.present?
+    end
+  end
+end
+```
+
+Now you can create instance of your service and check result of execution:
+
+```ruby
+service = Users::Destroy.new(current_user, force: true)
+service.execute!
+service.success? # or service.fail?
+```
+
+### Service: HTTP API
+
+Sometimes your service doesn't work with database, but calls some http endpoint or do some other stuff that doesn't require db transaction. In this case you can control your service flow manually:
+
+```ruby
+class Stripe::Create < ApplicationService
+  attr_reader :subscription
+
+  def execute!
+    # here you can go to Stripe and create subscription for the user
+    begin
+      @subscription = Stripe::Subscription.create(
+        customer: current_user.customer_id,
+        plan: selected_plan.stripe_name,
+      )
+
+      # everything looks ok, success
+
+      success!
+   rescue Stripe::StripeError => e
+      # something went wrong, let's notify developers and say that
+      # service execution has been failed
+
+     Airbrake.notify(e)
+     fail!
+   end
+  end
+end
+```
+
+### Callbacks
+
+If you need to do something on service success / fail it is possible to define appropriate callbacks. Notice, that in case of using `super` callbacks will be executed outside of db transaction, so it's safe to send emails from there, for example.
+
+```ruby
+module Passwords
+  class Update < ApplicationService
+    def execute!
+      authorize! current_user
+
+      super do
+        current_user.update(password: password, password_confirmation: password_confirmation)
+      end
+    end
+
+    # you can pass method name as a callback
+
+    on_success :invalidate_sessions
+
+    # or you can pass block instead of method name
+
+    on_success { UserMailer.password_changed(current_user).deliver_later }
+
+    private def invalidate_sessions
+      # you can invalidate existing user's sessions here
+    end
+  end
+end
+```
+
+### Validation
+
+Performify allows you to validate input arguments using [dry-validation](http://dry-rb.org/gems/dry-validation/) schemas. Validation is performed on creation of service instance. And if validation is not passed it will be impossible to call execution. Result of execution will be automatically switched to failed state.
+
+```ruby
+module Users
+  module Create
+    schema do
+      required(:email).filled(:str?)
+    end
+
+    def execute!
+      # it will be impossible to call execution if provided arguments
+      # did not pass validation
+    end
+  end
+end
+
+service = Users::Create.new(current_user, email: nil)
+service.execute! # nothing happens here
+service.success? # will be false because of validation
+service.errors   # contains hash of errors
+```
+
+Sometimes you can have differences between validation errors and execution errors. But usually it's boring to check them separately since you just need to display final result to user. To avoid double check you can use following trick:
+
+```ruby
+module Users
+  module Create
+    attr_reader :user
+
+    schema do
+      required(:email).filled(:str?)
+    end
+
+    def execute!
+      user = User.new(email: email)
+      authorize! user
+
+      # Let's assume that user has additional validation of uniqueness on the
+      # level of model, so in controller you need to check separately service's
+      # errors and model's errors, right?
+
+      super { user.save }
+    end
+
+    # So, we define on fail callback where we copy errors from model
+    # to service so now in controller we can check and use only service's errors
+
+    on_fail { errors! user.errors.to_h }
+  end
+end
+
+# in controller
+
+service = Users::Create.new(current_user, email: nil)
+service.execute!
+
+if service.success?
+  # respond with ok
+else
+  # respond with unprocessable entity and service.errors
+end
+```
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/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).
+To install this gem onto your local machine, run `bin/rake install`. To release a new version, update the version number in `version.rb`, and then run `bin/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/[USERNAME]/performify.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kimrgrey/performify.
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/Rakefile

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

data/bin/rubocop

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/lib/performify/base.rb

@@ -1,20 +1,28 @@
 require 'performify/callbacks'
+require 'performify/validation'
 
 module Performify
   class Base
     extend Performify::Callbacks
+    extend Performify::Validation
 
     attr_reader :current_user
 
     def initialize(current_user = nil, **args)
       @current_user = current_user
 
-      args.each do |arg_name, arg_value|
+      return if args.empty?
+
+      validate(args).each do |arg_name, arg_value|
         define_singleton_method(arg_name) { arg_value }
       end
+
+      fail!(with_callbacks: true) if errors?
     end
 
     def execute!
+      return if defined?(@result)
+
       block_result = nil
 
       ActiveRecord::Base.transaction do

data/lib/performify/callbacks.rb

@@ -2,7 +2,7 @@ module Performify
   module Callbacks
     class UnknownTypeOfCallbackError < StandardError; end
 
-    TYPES_OF_CALLBACK = [ :success, :fail ].freeze
+    TYPES_OF_CALLBACK = %i[success fail].freeze
 
     def clean_callbacks
       @service_callbacks = {}

data/lib/performify/validation.rb

@@ -0,0 +1,42 @@
+require 'dry-validation'
+
+module Performify
+  module Validation
+    def self.extended(base)
+      base.extend Performify::Validation::ClassMethods
+      base.include Performify::Validation::InstanceMethods
+    end
+
+    module ClassMethods
+      def schema(&block)
+        return @schema unless block_given?
+        @schema = Dry::Validation.Schema(Dry::Validation::Schema::Form, {}, &block)
+      end
+    end
+
+    module InstanceMethods
+      def schema
+        self.class.schema
+      end
+
+      def validate(args)
+        return args if schema.nil?
+        result = schema.call(args)
+        errors!(result.errors) unless result.success?
+        result.output
+      end
+
+      def errors!(new_errors)
+        errors.merge!(new_errors)
+      end
+
+      def errors
+        @errors ||= {}
+      end
+
+      def errors?
+        errors.any?
+      end
+    end
+  end
+end

data/lib/performify/version.rb

@@ -1,3 +1,3 @@
 module Performify
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'.freeze
 end

data/performify.gemspec

@@ -1,37 +1,37 @@
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'performify/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "performify"
-  spec.version       = Performify::VERSION
-  spec.authors       = ["Sergey Tsvetkov"]
-  spec.email         = ["sergey.a.tsvetkov@gmail.com"]
+  spec.name = "performify"
+  spec.version = Performify::VERSION
+  spec.authors = ["Sergey Tsvetkov"]
+  spec.email = ["sergey.a.tsvetkov@gmail.com"]
 
-  spec.summary       = %q{
-    Service classes that makes your life easier
-  }
+  spec.summary = "Service classes that makes your life easier"
 
-  spec.description   = %q{
-    Performify helps you to define your app logic in separated and isolated service classes
-    that is easy to use, test and maitain.
-  }
+  spec.description = "Performify helps you to define your app logic in separated and isolated \
+                      service classes that is easy to use, test and maitain."
 
-  spec.homepage      = "https://github.com/kimrgrey/performify"
-  spec.license       = "MIT"
+  spec.homepage = "https://github.com/kimrgrey/performify"
+  spec.license = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activerecord", ">= 4.0.0"
+  spec.add_dependency "dry-validation", ">= 0.10.7"
 
-  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "sqlite3", "~> 1.3.13"
   spec.add_development_dependency "bundler", "~> 1.14"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "rubocop", "~> 0.48"
+  spec.add_development_dependency "byebug", "~> 9.0.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: performify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergey Tsvetkov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-29 00:00:00.000000000 Z
+date: 2017-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -25,19 +25,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 4.0.0
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: dry-validation
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: 0.10.7
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.7
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.13
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.13
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,8 +94,36 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.5'
-description: "\n    Performify helps you to define your app logic in separated and
-  isolated service classes\n    that is easy to use, test and maitain.\n  "
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.48'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.48'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.0.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.0.6
+description: Performify helps you to define your app logic in separated and isolated                       service
+  classes that is easy to use, test and maitain.
 email:
 - sergey.a.tsvetkov@gmail.com
 executables: []
@@ -90,6 +132,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
@@ -98,10 +141,12 @@ files:
 - bin/console
 - bin/rake
 - bin/rspec
+- bin/rubocop
 - bin/setup
 - lib/performify.rb
 - lib/performify/base.rb
 - lib/performify/callbacks.rb
+- lib/performify/validation.rb
 - lib/performify/version.rb
 - performify.gemspec
 homepage: https://github.com/kimrgrey/performify