zen-service 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afe0cafc3b91d39c26b6eb9a24e4494b2310301ba94929dc1f49bced4f22b3d9
+  data.tar.gz: c57a4f0e6f0fb4b7cda8493be297134bc255f607fdab5d4841d12942a835eb2b
+SHA512:
+  metadata.gz: 242f523601adf176f3adeae447c3319123af3d6cf32afd5ee320d7b53c70932874e49e6fd30b92bd1c6c56bf9b675436d6022a165cf276a4c354de20d60996c0
+  data.tar.gz: 98ad8deaa278b44038b3adfe1284d92919eaa0acfe334cbba1e288844fbf1742dbf9cc43a2d1ba9a9adff5850e4ff680a3afa5055e975ae6c21fa28a963828ab

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.rspec_status
+.ruby-version
+.ruby-gemset

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: disable
+  TargetRubyVersion: 2.4
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+
+Style/Documentation:
+  Enabled: false
+
+Style/LambdaCall:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Layout/LineLength:
+  Exclude:
+    - 'spec/**/*.rb'

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.16.0

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem"s dependencies in zen-service.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Artem Kuzko
+
+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,284 @@
+# Zen::Service
+
+Flexible and highly extensible Service Objects for business logic organization.
+
+[![build status](https://secure.travis-ci.org/akuzko/zen-service.png)](http://travis-ci.org/akuzko/zen-service)
+[![github release](https://img.shields.io/github/release/akuzko/zen-service.svg)](https://github.com/akuzko/zen-service/releases)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zen-service'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zen-service
+
+## Preface
+
+From the beginning of Rails times, proper business logic code organization has always
+been a problem. Some code was placed in models, some in controllers, and complexity of
+both made applications hard to maintain. Then, patterns like "decorators", "facades" and
+"presenters" appeared to take care of certain part of logic. Finally, multiple service
+object solutions were proposed by many developers. This gem is one of such solutions, but
+with a significant difference.
+
+`Zen` services are aimed to take care of *all* business logic in your application, no
+matter what it is aimed for, and how complicated it is. From simplest cases of managing
+single model, to the most complicated logic related with external requests, `Zen` services
+got you covered. They are highly extendable due to plugin-based approach, composable and
+debuggable.
+
+Side note: as can be seen from commit history, this gem was initially called as `excom`,
+which stood for **Ex**ecutable **Com**and.
+
+## Usage
+
+General idea behind every `Zen` service is simple: each service can have optional attributes,
+and should define `execute!` method that is called during service execution. Executed service
+responds to `success?` and has `result`.
+
+The very basic usage of `Zen` services can be shown with following example:
+
+```rb
+# app/services/todos/update.rb
+module Todos
+  class Update < Zen::Service
+    attributes :todo, :params
+
+    delegate :errors, to: :todo
+
+    def execute!
+      todo.update(params)
+    end
+  end
+end
+
+# app/controllers/todos/controller
+class TodosController < ApplicationController
+  def update
+    service = Todos::Update.new(todo, params: todo_params)
+
+    if service.execute.success?
+      # class .[] method initializes service with passed arguments, executes it and returns it's result
+      render json: Todos::Show[service.result]
+    else
+      render json: service.errors, status: service.status
+    end
+  end
+end
+```
+
+### Service attributes
+
+Read full version on [wiki](https://github.com/akuzko/zen-service/wiki#instantiating-service-with-attributes).
+
+`Zen` services are initialized with _attributes_. To specify list of available attributes, use `attributes`
+class method. All attributes are optional during service initialization. It is possible to omit keys during
+initialization, and pass attributes as parameters - in this case attributes will be filled in correspondance
+to the order they were defined. However, you cannot pass more attributes than declared attributes list, as
+well as cannot pass single attribute multiple times (as parameter and as named attribute) or attributes that
+were not declared with `attributes` class method.
+
+```rb
+class MyService < Zen::Service
+  attributes :foo, :bar
+
+  def execute!
+    # do something
+  end
+
+  def foo
+    super || 5
+  end
+end
+
+s1 = MyService.new
+s1.foo # => 5
+s1.bar # => nil
+
+s2 = MyService.new(6)
+s2.foo # => 6
+
+s3 = s2.with_attributes(foo: 1, bar: 2)
+s3.foo # => 1
+s3.bar # => 2
+```
+
+### Service Execution
+
+Read full version on [wiki](https://github.com/akuzko/zen-service/wiki#service-execution).
+
+At the core of each service's execution lies `execute!` method. By default, you can use
+`success`, `failure` and `result` methods to set execution success flag and result. If none
+were used, result and success flag will be set based on `execute!` method's return value.
+
+Example:
+
+```rb
+class Users::Create < Zen::Service
+  attributes :params
+
+  def execute!
+    result { User.create(params) } # explicit result assignment
+
+    send_invitation_email if success?
+  end
+end
+
+class Users::Update < Zen::Service
+  attributes :user, :params
+
+  def execute!
+    user.update(params) # implicit result assignment
+  end
+end
+
+service = Users::Create.new(valid_params)
+service.execute.success? # => true
+service.result # => instance of User
+```
+
+### Core API
+
+Please read about core API and available class and instance methods on [wiki](https://github.com/akuzko/zen-service/wiki#core-api)
+
+### Service Extensions (Plugins)
+
+Read full version on [wiki](https://github.com/akuzko/zen-service/wiki/Plugins).
+
+`zen-service` is built with extensions in mind. Even core functionality is organized in plugins that are
+used in base `Zen::Service` class. Bellow you can see a list of plugins with some description
+and examples that are shipped with the gem:
+
+- [`:status`](https://github.com/akuzko/zen-service/wiki/Plugins#status) - Adds `status` execution state
+property to the service, as well as helper methods and behavior to set it. `status` property is not
+bound to the "success" flag of execution state and can have any value depending on your needs. It
+is up to you to setup which statuses correspond to successful execution and which are not. Generated
+status helper methods allow to atomically and more explicitly assign both status and result at
+the same time:
+
+```rb
+class Posts::Update < Zen::Service
+  use :status,
+    success: [:ok],
+    failure: [:unprocessable_entity]
+
+  attributes :post, :params
+
+  delegate :errors, to: :post
+
+  def execute!
+    if post.update(params)
+      ok { post.as_json }
+    else
+      unprocessable_entity
+    end
+  end
+end
+
+service = Posts::Update.(post, post_params)
+# in case params were valid you will have:
+service.success? # => true
+service.status # => :ok
+service.result # => {'id' => 1, ...}
+```
+
+Note that just like `success`, `failure`, or `result` methods, status helpers accept result value
+as result of yielded block.
+
+- [`:context`](https://github.com/akuzko/zen-service/wiki/Plugins#context) - Allows you to set an execution
+context for a block that will be available to any service that uses this plugin via `context` method.
+
+```rb
+# application_controller.rb
+around_action :with_context
+
+def with_context
+  Zen::Service.with_context(current_user: current_user) do
+    yield
+  end
+end
+```
+
+```rb
+class Posts::Archive < Zen::Service
+  use :context
+
+  attributes :post
+
+  def execute!
+    post.update(archived: true, archived_by: context[:current_user])
+  end
+end
+```
+
+- [`:policies`](https://github.com/akuzko/zen-service/wiki/Plugins#policies) - Allows you to define permission
+checks within a service that can be used in other services for checks and guard violations. Much like
+[pundit](https://github.com/elabs/pundit) Policies (hence the name), but more. Where pundit governs only
+authorization logic, `zen-service`'s "policy" services can have any denial reason you find appropriate, and declare
+logic for different denial reasons in single place. It also defines `#execute!` method that will result in
+hash with all permission checks.
+
+```rb
+class Posts::Policies < Zen::Service
+  use :policies
+
+  attributes :post, :user
+
+  deny_with :unauthorized do
+    def publish?
+      # only author can publish a post
+      post.author_id == user.id
+    end
+
+    def delete?
+      publish?
+    end
+  end
+
+  deny_with :unprocessable_entity do
+    def delete?
+      # disallow to destroy posts that are older than 1 hour
+      (post.created_at + 1.hour).past?
+    end
+  end
+end
+
+policies = Posts::Policies.new(outdated_post, user)
+policies.can?(:publish)     # => true
+policies.can?(:delete)      # => false
+policies.why_cant?(:delete) # => :unprocessable_entity
+policies.guard!(:delete)    # => raises Zen::Service::Plugins::Policies::GuardViolationError, :unprocessable_entity
+policies.execute.result     # => {'publish' => true, 'delete' => false}
+```
+
+- [`:assertions`](https://github.com/akuzko/zen-service/wiki/Plugins#assertions) - Provides `assert` method that
+can be used for different logic checks during service execution.
+
+- [`:execution_cache`](https://github.com/akuzko/zen-service/wiki/Plugins#execution_cache) - Simple plugin that will prevent
+re-execution of service if it already has been executed, and will immediately return result.
+
+- [`:rescue`](https://github.com/akuzko/zen-service/wiki/Plugins#rescue) - Provides `:rescue` execution option.
+If set to `true`, any error occurred during service execution will not be raised outside.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akuzko/zen-service.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "zen/service"
+
+class Show < Zen::Service
+  use :execution_cache
+
+  attributes :foo
+
+  def execute!
+    sleep(1)
+    { foo: foo }
+  end
+end
+
+class MyErrors < Hash
+  def add(key, message)
+    (self[key] ||= []) << message
+  end
+end
+
+class Policies < Zen::Service
+  use :policies
+
+  attributes :foo, :bar, :threshold
+
+  deny_with :unauthorized do
+    def save?
+      foo != 6
+    end
+  end
+
+  deny_with :unprocessable_entity do
+    def save?
+      foo != 7
+    end
+
+    def bar?
+      bar && bar > threshold
+    end
+  end
+end
+
+class Save < Zen::Service
+  use :status
+  use :validation, errors_class: MyErrors
+  use :assertions
+
+  attributes :foo, :bar
+
+  def foo
+    super || 6
+  end
+
+  def execute!
+    result { foo * 2 }
+    assert { foo > bar }
+  end
+
+  private def validate
+    errors.add(:foo, "invalid") unless policies.can?(:save)
+    errors.add(:bar, "too small") unless policies.can?(:bar)
+  end
+
+  private def policies
+    @policies ||= Policies.new(foo: foo, bar: bar, threshold: 0)
+  end
+end
+
+require "pry"
+Pry.start