simple_ruby_service 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e42ccf4f74e452f3da1dddc21eafd66c9c20a84386bfd2e0434b19d97393db46
-  data.tar.gz: 92f5a6025b72f92144896272378d308e223474103dab3abfee7304eb11432fa5
+  metadata.gz: a993ee0ea8d8f8e40588b27286699aa0e4cf0196b530d864493921146339434b
+  data.tar.gz: d42d0b36699eea8126f56f4ca9fa5dda415cf16fe132b47da2bda7c13642c2ca
 SHA512:
-  metadata.gz: 4a983c65b09b6219e4ce3636e53837affde6667c3f5ffa888bc66742c7c7533590ba702515bb8340e326d5d9558114c22aada7d0d925645b8a8d616b7bb377e9
-  data.tar.gz: 18da46473f59e5c8ff97a36dea127fafd48cb71686d9d3a2f29deee80dc1843304d29b8c5ec10d6d09dce3d5fa6df3142f90bd472860f77579dccb0f4d150008
+  metadata.gz: 135157ecda108ae98dd379db2fb597e78fff0e5ce84dd8a663d064b0af44f5dfb0f259f9a893013c87a49ec0d6559281eda87f683d647d535924fa6a8a32cba4
+  data.tar.gz: 5f2f41813dddb117d7f2e3bb5aa40edcd180ea89901bce182d2e6f5e76eb3665d234a5a8ddb5e5fc3cff2cc15e5d34a544518921dd2e7f363bce245f25ee75bc

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.4 (02-Jul-21)
+
+* Polished README (again)
+
 ## 1.0.3 (01-Jul-21)
 
 * Polished README

data/README.md

@@ -5,11 +5,29 @@
 
 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. Allows Service Objects to ducktype 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
 
@@ -59,18 +77,18 @@ class SomeController < ApplicationController
 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: Just one, readable line of code
+    # NOTE: That's right... just one, readable line of code
     render DoSomething.call!(params)
   end
 end
 ```
  
-#### ::Alternate After:: Refactored using a Service
+#### ::Alternate After:: Refactored using a Simple Ruby Service
 ```ruby
 # in app/controllers/some_controller.rb
 class SomeController < ApplicationController
@@ -86,14 +104,21 @@ 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
+`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
@@ -101,6 +126,7 @@ Similar to `ActiveRecord::Base#save!`, `DoSomething.call!(params)`:
 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
 
@@ -350,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
+```
 
-[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.
+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
 
-### When should I choose a Service over an SO, and vice-versa?
+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`_
+
+### Service or SO?
 
 Use a `Service` when encapsulating related operations that share dependencies & validations.
 
@@ -373,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.
 
@@ -383,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
 
@@ -399,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.

data/lib/simple_ruby_service/version.rb

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

data/simple_ruby_service.gemspec

@@ -11,7 +11,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["i.jaycrouch@gmail.com"]
 
   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.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_ruby_service
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Jay Crouch
@@ -304,10 +304,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-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.
+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: []