simple_ruby_service 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 665fbb0eacfb11a6e7d863e72a0e091ad96831c0ce72644fb5467b592c567524
-  data.tar.gz: 98c5caa24124671cd21f56a0f625f8c340e198c3847d05454b9cb41c633ff64b
+  metadata.gz: e42ccf4f74e452f3da1dddc21eafd66c9c20a84386bfd2e0434b19d97393db46
+  data.tar.gz: 92f5a6025b72f92144896272378d308e223474103dab3abfee7304eb11432fa5
 SHA512:
-  metadata.gz: f11211b2e212d4324a9c55a09f2a366c152f5e3d53c5069c35d7b77876844cbc6db397e5bb888ceba36d1165ad27cc3dd09c8751cbd3bb838123f68c5695c4b5
-  data.tar.gz: c1b45fe0900d696f739540cd9cd8f90d9c31133d8df14ebb2a60ad4743b90360241334c102dc70f1d26d4a8ee9415eb564d9631c401a3f633d7502b9b6b2c6be
+  metadata.gz: 4a983c65b09b6219e4ce3636e53837affde6667c3f5ffa888bc66742c7c7533590ba702515bb8340e326d5d9558114c22aada7d0d925645b8a8d616b7bb377e9
+  data.tar.gz: 18da46473f59e5c8ff97a36dea127fafd48cb71686d9d3a2f29deee80dc1843304d29b8c5ec10d6d09dce3d5fa6df3142f90bd472860f77579dccb0f4d150008

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 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,13 @@
 [![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:
 
 1. Incorporates ActiveModel validations and error handling
 2. Encourages a succinct, idiomatic coding style 
-3. Ducktypes Service Objects as Procs
+3. Allows Service Objects to ducktype as Procs
 
 ## Requirements
 
@@ -37,10 +37,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,6 +53,7 @@ class SomeController < ApplicationController
     authorize! resource
     resource.do_something
     value = resource.do_something_related
+    raise unless resource.errors
     render value
   end
 end
@@ -61,12 +64,39 @@ end
 # 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: Just one, readable line of code
+    render DoSomething.call!(params)
+  end
+end
+```
+ 
+#### ::Alternate After:: Refactored using a 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
+```
 
+### Taking a peek under the hood
 
+Similar to `ActiveRecord::Base#save!`, `DoSomething.call!(params)`:
+- creates an instance of `DoSomething`
+- initializes `instance.attributes` with `params`
+- raises `SimpleRubyService::Invalid` if `instance.invalid?`
+- sends `instance.call`
+- raises `SimpleRubyService::Failed` if `instance.failed?`
+- returns `instance.value` directly to the caller
+
+
+### Anatomy of a Simple Ruby Service Object
+```ruby
 # in app/service_objects/do_something.rb
 class DoSomething
   include SimpleRubyService::ServiceObject
@@ -74,33 +104,26 @@ class DoSomething
   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 +131,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 +173,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 +231,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 +285,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 +313,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)
@@ -323,9 +354,9 @@ end
 
 ### Why should I use Services & SOs?
 
-[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.
+[LMGTFY](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.
 
-**TLDR; fat models and fat controllers are bad! Services and Service Objects help you DRY things up.**
+**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?
 
@@ -416,6 +447,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/version.rb

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

data/simple_ruby_service.gemspec

@@ -10,8 +10,8 @@ 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 provides a simple DSL that:\n  a) incorporates ActiveModel validations and error handling;\n  b) encourages a succinct, idiomatic coding style;\n  c) allows Service Objects to ducktype as Procs.'
   spec.homepage      = 'https://github.com/amazing-jay/simple_ruby_service'
   spec.license       = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_ruby_service
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Jay Crouch
@@ -304,10 +304,10 @@ 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 provides a simple DSL that:\n  a)
+  incorporates ActiveModel validations and error handling;\n  b) encourages a succinct,
+  idiomatic coding style;\n  c) allows Service Objects to ducktype as Procs.
 email:
 - i.jaycrouch@gmail.com
 executables: []
@@ -358,6 +358,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: []