simple_ruby_service 1.0.2 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 665fbb0eacfb11a6e7d863e72a0e091ad96831c0ce72644fb5467b592c567524
-  data.tar.gz: 98c5caa24124671cd21f56a0f625f8c340e198c3847d05454b9cb41c633ff64b
+  metadata.gz: 93055c8359bf7677e53e99e5cae18f128e17f643770b51e207cdfd4892bf1ac2
+  data.tar.gz: 916d16d46e8c43ca5815e40b940df3d768e9d22fec56990fa29fb4c0610235a7
 SHA512:
-  metadata.gz: f11211b2e212d4324a9c55a09f2a366c152f5e3d53c5069c35d7b77876844cbc6db397e5bb888ceba36d1165ad27cc3dd09c8751cbd3bb838123f68c5695c4b5
-  data.tar.gz: c1b45fe0900d696f739540cd9cd8f90d9c31133d8df14ebb2a60ad4743b90360241334c102dc70f1d26d4a8ee9415eb564d9631c401a3f633d7502b9b6b2c6be
+  metadata.gz: d68822b1a43f2a664c9e4b6f48a7b0a81de97686d346147e5b1d9bc6163e69d3df83a199908a82da6f2f694b704821aab54c019e35f35f3bfefed47c71499f42
+  data.tar.gz: cc1b27bbb4d6fd18dfb161d504787a4828a27a0babe4550f0864f1f9f9d740749a0e7983792b8e92d9f030ad7b1afa23be0220ee239939e4cf7cda3b11bb7d96

data/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
+## 1.0.5 (22-Dec-21)
+
+* Added setting to control automatically setting self.value with result of service methods
+
+## 1.0.4 (02-Jul-21)
+
+* Polished README (again)
+
 ## 1.0.3 (01-Jul-21)
 
-* Finished Travis CI and Codecov integration
+* Polished README
 
 ## 1.0.2 (01-Jul-21)
 

data/README.md

@@ -3,13 +3,31 @@
 [![Build Status](https://travis-ci.com/amazing-jay/simple_ruby_service.svg?branch=master)](https://travis-ci.com/amazing-jay/simple_ruby_service)
 [![Test Coverage](https://codecov.io/gh/amazing-jay/simple_ruby_service/graph/badge.svg)](https://codecov.io/gh/amazing-jay/simple_ruby_service)
 
-Simple Ruby Service is a lightweight framework for Ruby that makes it easy to create Services and Service Objects (SOs).
+Simple Ruby Service is a lightweight framework for creating Services and Service Objects (SOs) in Ruby.
 
-The framework provides a simple DSL that:
+The framework makes Services and SOs look and feel like ActiveModels, complete with:
 
-1. Incorporates ActiveModel validations and error handling
-2. Encourages a succinct, idiomatic coding style 
-3. Ducktypes Service Objects as Procs
+1. Validations and robust error handling
+2. Workflows and method chaining
+3. Consistent interfaces
+
+Additionally, Simple Ruby Service Objects can stand in for Procs, wherever Procs are expected (via ducktyping).
+
+#### What problem does Simple Ruby Service solve?
+
+Currently, most ruby developers roll their own services from scratch. As a result, most services are hastely built (in isolation), and this leads to inconsistant interfaces that are difficult to read. Also, error handling tends to vary wildly within an application, and support code tends to be implemented over and over again.
+
+Simple Ruby Service addresses these problems and encourages succinct, idiomatic coding styles.
+
+#### Should I be using Services & SOs in Ruby / Rails?
+
+[LMGTFY](https://www.google.com/search?q=service+object+pattern+rails&rlz=1C5CHFA_enUS893US893&oq=service+object+pattern+rails) to learn more about Services & SOs.
+
+**TLDR** - Fat models and fat controllers are bad! Services and Service Objects help you DRY things up.
+
+#### How is a Service different from an SO?
+
+An SO is just a Service that encapsulates a single operation (i.e. **one, and only one, responsibility**).
 
 ## Requirements
 
@@ -37,10 +55,12 @@ Source code can be downloaded on GitHub
   [github.com/amazing-jay/simple_ruby_service/tree/master](https://github.com/amazing-jay/simple_ruby_service/tree/master)
 
 
-### The following examples illustrate how to refactor complex business logic with Simple Ruby Service
+## Quick Start
 
 See [Usage](https://github.com/amazing-jay/simple_ruby_service#usage) & [Creating Simple Ruby Services](https://github.com/amazing-jay/simple_ruby_service#creating-simple-ruby-services) for more information.
 
+### How to refactor complex business logic with Simple Ruby Service
+
 #### ::Before:: Vanilla Rails with a fat controller (a contrived example)
 ```ruby
 # in app/controllers/some_controller.rb
@@ -51,56 +71,85 @@ class SomeController < ApplicationController
     authorize! resource
     resource.do_something
     value = resource.do_something_related
+    raise unless resource.errors
     render value
   end
 end
 ```
 
-#### ::After:: Refactored using an SO
+#### ::After:: Refactored using an Simple Ruby Service Object
+```ruby
+# in app/controllers/some_controller.rb
+class SomeController < ApplicationController
+  def show
+    # NOTE: That's right... just one, readable line of code
+    render DoSomething.call!(params)
+  end
+end
+```
+ 
+#### ::Alternate After:: Refactored using a Simple Ruby Service
 ```ruby
 # in app/controllers/some_controller.rb
 class SomeController < ApplicationController
   def show
-    # NOTE: Simple Ruby Service Objects ducktype as Procs and do not need to be instantiated
-    render DoSomething.call(params).value
+    # NOTE: Simple Ruby Service methods can be chained together
+    render SomeService.new(params)
+      .do_something
+      .do_something_related
+      .value
   end
 end
+```
+
+### Taking a peek under the hood
+
+`DoSomething.call!(params)` is deliberately designed to look and feel like `ActiveRecord::Base#save!`.
+
+The following (simplified) implementation illustrates what happens under the hood:
 
+```ruby
+module SimpleRubyService::Object
+  def self.call!(params)
+    instance = new(params)
+    raise Invalid unless instance.valid?
+    self.value = instance.call
+    raise Invalid unless instance.failed?
+    value
+  end
+end
+```
 
+### Anatomy of a Simple Ruby Service Object
+```ruby
 # in app/service_objects/do_something.rb
 class DoSomething
   include SimpleRubyService::ServiceObject
   
+  # `attribute` behaves similar to ActiveRecord::Base#attribute, but is not typed, or bound to persistant storage
   attribute :id
   attr_accessor :resource
 
-  # NOTE: Validations are executed prior to the business logic encapsulated in `perform`
+  # Validations are executed prior to the business logic encapsulated in `perform`
   validate do                                 
     @resource ||= SomeModel.find(id)
     authorize! resource
   end
   
-  # NOTE: The return value of `perform` is automatically stored as the SO's `value`
+  # The result of `perform` is automatically stored as the SO's `value`
   def perform
-    resource.do_something
-    resource.do_something_related
+    resource.do_something    
+    result = resource.do_something_related  
+    
+    # Adding any kind of error indicates failure
+    add_errors_from_object resource    
+    result
   end
 end
 ```
 
-#### ::Alternate Form:: Refactored using a Service
+### Anatomy of a Simple Ruby Service
 ```ruby
-# in app/controllers/some_controller.rb
-class SomeController < ApplicationController
-  def show
-    # NOTE: Simple Ruby Service methods can be chained together
-    render SomeService.new(params)
-      .do_something
-      .do_something_related
-      .value
-  end
-end
-
 # in app/services/do_something.rb
 class SomeService
   include SimpleRubyService::Service
@@ -108,25 +157,38 @@ class SomeService
   attribute :id
   attr_accessor :resource
 
-  # NOTE: Validations are executed prior to the first service method called
+  # Similar to SOs, validations are executed prior to the first service method called
   validate do
     @resource ||= SomeModel.find(id)
     authorize! @resource
   end
   
+  # Unlike SOs, Services can define an arbitrary number of service methods with arbitrary names
   service_methods do
     def do_something
-      resource.do_something_related
+      resource.do_something      
     end
 
-    # NOTE: Unlike SOs, `value` must be explicitely set for Service methods
+    # Unlike SOs, `value` must be explicitely set for Service methods
     def do_something_related
       self.value ||= resource.tap &:do_something_related
+      add_errors_from_object resource
     end
   end
 end
 ```
 
+## A special note about Simple Ruby Service Objects, Procs, and Ducktyping
+
+Simple Ruby Service Objects respond to (`#call`) so they can stand in for Procs, i.e.:
+```ruby
+# in app/models/some_model.rb
+class SomeModel < ApplicationRecord
+  validates :some_attribute, if: SomeServiceObject
+  [...]
+```
+_See [To bang!, or not to bang](https://github.com/amazing-jay/simple_ruby_service/tree/master#to-bang-or-not-to-bang) to learn about `.call!` vs. `.call`._
+
 ## Usage
 
 ### Service Objects
@@ -137,8 +199,6 @@ Service Object names should begin with a verb and should not include the words `
 
 Also, only one operation should be made public, it should always be named `call`, and it should not accept arguments (except for an optional block).
 
-_See [To bang!, or not to bang](https://github.com/amazing-jay/simple_ruby_service/tree/master#to-bang-or-not-to-bang) to learn about `.call!` vs. `.call`._
-
 #### Short form (_recommended_)
 
 ```ruby
@@ -197,9 +257,6 @@ Unlike Service Objects, Service class names should begin with a noun (and may in
 
 Also, any number of operations may be made public, any of these operations may be named `call`, and any of these operations may accept arguments.
 
-_See [To bang!, or not to bang](https://github.com/amazing-jay/simple_ruby_service/tree/master#to-bang-or-not-to-bang) to learn about `.service_method_name!` vs. `.service_method_name`._
-
-
 #### Short form
 
 _not available for Services_
@@ -254,7 +311,7 @@ end
 ## Creating Simple Ruby Services
 
 ### Service Objects
-To implement an Simple Ruby Service Object:
+To implement a Simple Ruby Service Object:
 
   1. include `SimpleRubyService::ServiceObject`
   2. declare attributes with the `attribute` keyword (class level DSL)
@@ -282,7 +339,7 @@ end
 ```
 
 ### Services
-To implement an Simple Ruby Service:
+To implement a Simple Ruby Service:
 
   1. include `SimpleRubyService::Service`
   2. declare attributes with the `attribute` keyword (class level DSL)
@@ -319,19 +376,46 @@ class SomeService
 end
 ```
 
-## FAQ
+### Workflows
+Simple Ruby Services are inherently a good fit for workflows because they support chaining, i.e.:
 
-### Why should I use Services & SOs?
+```ruby
+SomeService.new(params)
+  .do_something
+  .do_something_related
+  .value
+```
 
-[Click here](https://www.google.com/search?q=service+object+pattern+rails&rlz=1C5CHFA_enUS893US893&oq=service+object+pattern+rails) to learn more about the Services & SO design pattern.
+But SOs can also implement various workflows with dependency injection:
 
-**TLDR; fat models and fat controllers are bad! Services and Service Objects help you DRY things up.**
+```ruby
+class PerformSomeWorkflow < SimpleRubyService::ServiceObject
+  def perform
+    dependency = SimpleRubyService1.call!
+    result = SimpleRubyService2.call(dependency)
+    raise unless result.success?                 
+    SimpleRubyService3(dependency, result.value).call!
+  end
+end
+```
 
-### How is a Service different from an SO?
+## MISC
 
-An SO is just a Service that encapsulates a single operation (i.e. **one, and only one, responsibility**).
+### To bang!, or not to bang
+
+Use the bang! version of an operation whenever you expect the operation to succeed more often than fail, and you don't need to chain operations together.
+
+Similar in pattern to `ActiveRecord#save!`, the bang version of each operation:
+* raises `SimpleRubyService::Invalid` if `valid?` is falsey
+* raises `SimpleRubyService::Failure` if the block provided returns a falsey value
+* returns `@value`
 
-### When should I choose a Service over an SO, and vice-versa?
+Whereas, similar in pattern to `ActiveRecord#save`, the regular version of each operation:
+* doesn't raise any exceptions
+* passes the return value of the block provided to `#success?` 
+* returns self << _note: this is unlike `ActiveRecord#save`_
+
+### Service or SO?
 
 Use a `Service` when encapsulating related operations that share dependencies & validations.
 
@@ -342,9 +426,6 @@ i.e.:
 
 _note: Things get fuzzy when operations share some, but not all, dependencies & validations. Use your best judgement when operation `A` and operation `B` are related but `A` acts on a `User` while `B` acts on both a `User` & a `Company`._
 
-### Atomicity
-The framework does not include transaction support by default. You are responsible for wrapping with a transaction if atomicity is desired.
-
 ### Control Flow
 Rescue exceptions that represent internal control flow and propogate the rest.
 
@@ -352,7 +433,7 @@ For example, if an internal call to User.create! is expected to always succeed,
 
 Example::
 ```ruby
-class DoSomethingDangerous < SimpleRubyService::ObjectBase
+class DoSomethingDangerous < SimpleRubyService::ServiceObject
   attribute :attr1, :attr2             # should include all params required to execute
   validates_presence_of :attr1         # validate params to call
 
@@ -368,38 +449,6 @@ class DoSomethingDangerous < SimpleRubyService::ObjectBase
 end
 ```
 
-## Workflows
-SOs often need to call other SOs in order to implement various workflows:
-```ruby
-class PerformSomeWorkflow < SimpleRubyService::ObjectBase
-  def perform
-    dependency = SimpleRubyService1.call!
-    result = SimpleRubyService2.call(dependency)
-    raise unless result.success?                 
-    SimpleRubyService3(dependency, result.value).call!
-  end
-end
-```
-
-## MISC
-
-### Attributes
-The `attribute` and `attributes` keywords behaves similar to [ActiveRecord::Base.attribute](https://api.rubyonrails.org/v6.1.3.1/classes/ActiveRecord/Attributes/ClassMethods.html), but they are not typed or bound to persistant storage.
-
-### To bang!, or not to bang
-
-Use the bang! version of an operation whenever you expect the operation to succeed more often than fail, and you don't need to chain operations together.
-
-Similar in pattern to `ActiveRecord#save!`, the bang version of each operation:
-* raises `SimpleRubyService::Invalid` if `valid?` is falsey
-* raises `SimpleRubyService::Failure` if the block provided returns a falsey value
-* returns `@value`
-
-Whereas, similar in pattern to `ActiveRecord#save`, the regular version of each operation:
-* doesn't raise any exceptions
-* passes the return value of the block provided to `#success?` 
-* returns self << _note: this is unlike `ActiveRecord#save`_
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -416,6 +465,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## DEVELOPMENT ROADMAP
 
-1. Create a helper to dynamically generate default SOs for ActiveRecord models (`create`, `update`, and `destroy`) _(when used in a project that includes [ActiveRecord](https://github.com/rails/rails/tree/main/activerecord))_.
-2. Consider isolating validation errors from execution errors (so that invalid? is not always true when failed? is true)
+1. Create a class level DSL to stop before each Service method unless errors.empty?
+2. Create a helper to dynamically generate default SOs for ActiveRecord models (`create`, `update`, and `destroy`) _(when used in a project that includes [ActiveRecord](https://github.com/rails/rails/tree/main/activerecord))_.
+3. Consider isolating validation errors from execution errors (so that invalid? is not always true when failed? is true)
 

data/lib/simple_ruby_service/service.rb

@@ -6,9 +6,13 @@ module SimpleRubyService
     extend ActiveSupport::Concern
     include ActiveModel::AttributeAssignment
     include ActiveModel::Validations
+    include ActiveModel::Validations::Callbacks
 
     included do
       attr_accessor :value
+
+      class_attribute :set_value_when_service_methods_return
+      self.set_value_when_service_methods_return = true
     end
 
     class_methods do
@@ -32,7 +36,7 @@ module SimpleRubyService
       # Class level DSL that wraps the methods defined in inherited classes.
       def service_methods(&blk)
         Module.new.tap do |m| # Using anonymous modules so that super can be used to extend service methods
-          m.module_eval &blk
+          m.module_eval(&blk)
           include m
 
           m.instance_methods.each do |service_method|
@@ -41,7 +45,8 @@ module SimpleRubyService
             # Returns self (for chainability).
             # Evaluates validity prior to executing the block provided.
             define_method service_method do |*args, **kwargs, &callback|
-              perform(service_method, *args, **kwargs, &callback) if valid?
+              result = perform(service_method, *args, **kwargs, &callback) if valid?
+              self.value = result if set_value_when_service_methods_return
 
               self
             end
@@ -130,5 +135,3 @@ module SimpleRubyService
     end
   end
 end
-
-

data/lib/simple_ruby_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleRubyService
-  VERSION = '1.0.2'
+  VERSION = '1.0.6'
 end

data/simple_ruby_service.gemspec

@@ -10,8 +10,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jay Crouch"]
   spec.email         = ["i.jaycrouch@gmail.com"]
 
-  spec.summary       = 'Simple Ruby Service is a lightweight framework for Ruby that makes it easy to create Services and Service Objects (SOs).'
-  spec.description   = 'Simple Ruby Service is a lightweight framework for Ruby that makes it easy to create Services and Service Objects (SOs). The framework provides a simple DSL that: incorporates ActiveModel validations and error handling; encourages a succinct, idiomatic coding style; Ducktypes Service Objects as Procs.'
+  spec.summary       = 'Simple Ruby Service is a lightweight framework for creating Services and Service Objects (SOs) in Ruby.'
+  spec.description   = 'Simple Ruby Service is a lightweight framework for creating Services and Service Objects (SOs) in Ruby. ' \
+                       'The framework makes Services and SOs look and feel like ActiveModels, complete with: 1. validations and robust error handling; 2. workflows and method chaining; and 3. consistent interfaces. Additionally, Simple Ruby Service Objects can stand in for Procs, wherever Procs are expected (via ducktyping).'
   spec.homepage      = 'https://github.com/amazing-jay/simple_ruby_service'
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_ruby_service
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.6
 platform: ruby
 authors:
 - Jay Crouch
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-02 00:00:00.000000000 Z
+date: 2021-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -304,10 +304,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: 'Simple Ruby Service is a lightweight framework for Ruby that makes it
-  easy to create Services and Service Objects (SOs). The framework provides a simple
-  DSL that: incorporates ActiveModel validations and error handling; encourages a
-  succinct, idiomatic coding style; Ducktypes Service Objects as Procs.'
+description: 'Simple Ruby Service is a lightweight framework for creating Services
+  and Service Objects (SOs) in Ruby. The framework makes Services and SOs look and
+  feel like ActiveModels, complete with: 1. validations and robust error handling;
+  2. workflows and method chaining; and 3. consistent interfaces. Additionally, Simple
+  Ruby Service Objects can stand in for Procs, wherever Procs are expected (via ducktyping).'
 email:
 - i.jaycrouch@gmail.com
 executables: []
@@ -358,6 +359,6 @@ requirements: []
 rubygems_version: 3.0.9
 signing_key:
 specification_version: 4
-summary: Simple Ruby Service is a lightweight framework for Ruby that makes it easy
-  to create Services and Service Objects (SOs).
+summary: Simple Ruby Service is a lightweight framework for creating Services and
+  Service Objects (SOs) in Ruby.
 test_files: []