simple_service 1.4.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f173ba72cf1c5abefb364936804cef31b6ce102c
-  data.tar.gz: dc9ca5da527f09a06a7b1bfb4167ae0911814e65
+  metadata.gz: 0e3f3509cf01d669899e4b014dfd78117a99f0e0
+  data.tar.gz: 728f0043ddfc2e9d9c8d031416f900b2c4bba888
 SHA512:
-  metadata.gz: ff4e0f4bc3503e57ad6d91c97ecbc4cedc0cd089e5b73a3f0d3c8e6fd5e6155f511e20ac43c85117bd677b7d657187ed8d926e87075be3e1b34494b2c007719e
-  data.tar.gz: '08fb83a60818d0926f4883b1f43bd18249755616b805450feada31e2b7fe906c8db3a5e684eabc1eedac0dc4e15634c285c4a662aebcaa14fc4f5548bad91e56'
+  metadata.gz: 83f503070b874dd3f590e1ef8bcec3c806615a415b3f31a3f1c4c5735a5dc594bff649dc7bd20a031451a8a1b981b2e08aac7e7fc0141e5b9fcd248d1bdea9ef
+  data.tar.gz: d0b1f1da0d55f45d8ef5192bc3beb5d9fc924e8a2f03f51ab33141d6973019bf596e341fd5ef4ea06e9ef561e2ac443a4240937a7129e8063fbb17133fe85a0b

data/.travis.yml

@@ -1,8 +1,7 @@
 language: ruby
 rvm:
   - jruby-19mode
-  - 2.0.0
   - 2.1.0
-  - 2.2.0
   - 2.3.0
   - 2.3.3
+  - 2.4.2

data/README.md

@@ -6,169 +6,157 @@
 [![Build Status](https://travis-ci.org/jspillers/simple_service.svg?branch=master)](https://travis-ci.org/jspillers/simple_service)
 <!--![](http://ruby-gem-downloads-badge.herokuapp.com/jspillers/simple_service)-->
 
-SimpleService provides a way to organize Ruby service objects into highly reusable
-and composable classes that are easy to implement and easy to read.  Instead of 
-writing large service objects that perform multiple tasks, SimpleService 
-helps you breakdown tasks into a set of sequentially performed "Command" objects. 
-Commands are very small classes that perform exactly one task. When properly designed, 
-these command objects can be reused in multiple organizers minimizing code duplication.
-
-When an organizer is instantiated a hash is passed in containing initial arguments. 
-This hash is referred to as the context.  The context hash is carried along throughout 
-the sequence of command executions and modified by each command. After a 
-successful run, the keys specified are returned. If keys are not specified, the 
-entire context hash is returned.
-
-# Setup
-
-First, setup an Organizer class. An Organizer needs the following things defined:
-
-  * expects: keys that are required to be passed into initialize when an 
-    instance of organizer is created. If not defined the organizer will 
-    accept arbitrary arguments.
-  * returns: keys that will be returned when the organizer has called all of 
-    its commands
-  * commands: classes that define all the steps that the organizer will call. 
-    The organizer will execute #call on each command in order and the context 
-    hash is passed to each of these commands. Any keys within the context that 
-    are modified will be merged back into the organizer and passed along to the 
-    next command.
+SimpleService facilitates the creation of Ruby service objects into highly discreet, reusable,
+and composable units of business logic. The core concept of SimpleService is the definition of 
+"Command" objects/methods. Commands are very small classes or methods that perform exactly one task. 
+When properly designed, these command objects can be composited together or even nested to create
+complex flows.
 
-```ruby
-class ProcessSomethingComplex < SimpleService::Organizer
+## Installation
 
-  # optional - ensures the following keys are provided during instantiation
-  # leave out to accept any arguments/keys
-  expects :something, :another_thing
+Add this line to your application's Gemfile:
 
-  # optional - specifies which keys get returned after #call is executed on
-  # an organizer instance
-  returns :modified_thing
+    gem 'simple_service'
 
-  # what steps comprise this service
-  # #call will be executed on an instance of each class in sequence
-  commands DoSomethingImportant, DoAnotherStep
+And then execute:
 
-end
-```
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install simple_service
+
+# Setup and Basic Usage:
 
-Next, define all command classes that make up the service. Each should inherit 
-from SimpleService::Command and define similar things to the organizer:
+* load the gem
+* include the SimpleService module into your service object class
+* define one or more comamnds that it will perform, must accept either keyword arguments or a hash argument
+* call `#success` or `#failure` with any values you wish to pass along to the next command (or wish to return if it is the last command)
 
 ```ruby
-class DoSomethingImportant < SimpleService::Command
-  
-  # optional - creates getter/setter for each key specified, 
-  # leave blank to accept arbitrary args
-  expects :something
-
-  # optional - creates getter/setter for each key specified, 
-  # leave blank to return entire context hash
-  returns :modified_something, :another_thing
-
-  # required - this is where the work gets done, should only
-  # do one thing (single responsibility principle)
-  # getters and setters are available for each key specified
-  # in expects and returns. If not using expects and returns
-  # simply interact with the context hash directly
-  def call
-    # uses getters and setters to modify the context
-    self.modified_something = self.something.to_i + 1
-
-    # or act directly on the context hash
-    context[:modified_something] = context[:something].to_i + 1
-
-    # no need to return anything specific, either the keys 
-    # specified in returns will be returned or the entire 
-    # context if no returns are defined
+require 'rubygems'
+require 'simple_service'
+
+class DoStuff
+  include SimpleService
+
+  commands :do_something_important, :do_another_important_thing
+
+  def do_something_important(name:)
+    message = "hey #{name}"
+
+    success(message: message)
   end
 
-end
+  def do_another_important_thing(message:)
+    new_message = "#{message}, we are doing something important!"
 
-class DoSomethingImportant < SimpleService::Command
-  ...
+    success(the_final_result: new_message)
+  end
 end
+
+result = DoStuff.call(name: 'Alice')
+result.success? #=> true
+result.value #=> {:the_final_result=>"hey Alice, we are doing something important!"}
 ```
 
-Within any command you can call ```#failure!``` and then return in order to
-abort execution of subsequent commands within the organizer.
+A failure:
 
 ```ruby
-class DemonstrateFailure < SimpleService::Command
-  
-  expects :something
+require 'rubygems'
+require 'simple_service'
 
-  returns :good_stuff
+class DoFailingStuff
+  include SimpleService
 
-  def call
-    if good_stuff_happens
-      self.good_stuff = 'yeah, success!'
-    else
-      failure!('something not so good happened; no more commands should be called')
-    end
-  end
+  commands :fail_at_something
 
+  def fail_at_something(name:)
+    message = "hey #{name}, things went wrong."
+
+    failure(message: message)
+  end
 end
+
+result = DoStuff.call(name: 'Bob')
+result.success? #=> false
+result.failure? #=> true
+result.value #=> {:message=>"hey Bob, things went wrong."}
 ```
 
-## Usage
+You can also use ClassNames as commands and to organize them into other files:
 
-Using the service is straight forward - just instantiate it, passing in the 
-intial context hash, and then call.
+```ruby 
+require 'rubygems'
+require 'simple_service'
 
-```ruby
-starting_context = {
-  something: '1', 
-  :another_thing: AnotherThing.new
-}
-modified_context = ProcessSomethingComplex.new(starting_context).call
+class CommandOne
+  include SimpleService
 
-# alternatively, you can call directly from the service class
-modified_context = ProcessSomethingComplex.call(starting_context)
+  command :add_stuff
 
-modified_context[:modified_thing] # => 2
-```
+  def add_stuff(one:, two:)
+    success(three: one + two)
+  end
+end
 
-If you are using this with a Rails app, placing top level services in 
-app/services/ and all commands in app/services/commands/ is recommended. If
-not using rails, a similar structure would also be recommended.
+class CommandTwo
+  include SimpleService
 
-For further examination of usage, here are a few examples:
+  command :add_more_stuff
 
-* [hello world example](example/hello_world.rb)
-* [nested services example](example/nested_services.rb)
-* [override #call on the organizer](example/override_organizer_call_method.rb)
+  def add_more_stuff(three:)
+    binding.pry
+    success(seven: three + 4)
+  end
+end
 
-## Inspiration and Rationale
+class DoNestedStuff
+  include SimpleService
 
-This gem is heavily inspired by two very nice gems: 
-[mutations](https://github.com/cypriss/mutations) and
-[light-service](https://github.com/adomokos/light-service). 
+  commands CommandOne, CommandTwo
+end
 
-Mutations is a great gem, but lacks the concept of a top level organizer. 
-LightService brings in the notion of the organizer object, but doesn't create 
-instances of its action objects (what are referred to as commands here). Using 
-instances rather than class level #call definitions allows the use of private 
-methods within the command for more complex commands that still do a single thing.
+result = DoNestedStuff.call(one: 1, two: 2)
+result.success? #=> true
+result.value #=> {:seven=>7}
+```
 
-The other goal of this gem is to do as little as possible above and beyond 
-just using plain old Ruby objects (PORO's).  Things like error handling, logging, 
-and context status will be left up to the individual to implement in a way that 
-best suits their use case.
+If you would like your service to process an enumerable you can override `#call`
+on your service object. Invoking `#super` in your definition and passing along 
+the appropriate arguments will allow your command chain to proceed as normal, but
+called multiple times via a loop. The Result object returned from each call to `#super`
+can be passed in as an argument to the next iteration or you can collect the result objects
+yourself and then do any post processing required.
 
-## Installation
+```ruby
+require 'rubygems'
+require 'simple_service'
 
-Add this line to your application's Gemfile:
+class LoopingService
+  include SimpleService
 
-    gem 'simple_service'
+  commands :add_one
 
-And then execute:
+  def call(kwargs)
+    count = kwargs
 
-    $ bundle
+    3.times do
+      count = super(count)
+    end
 
-Or install it yourself as:
+    count
+  end
 
-    $ gem install simple_service
+  def add_one(count:)
+    success(count: count + 1)
+  end
+end
+```
+
+If you are using this with a Rails app, placing top level services in 
+`app/services/` and all nested commands in `app/services/commands/` is 
+recommended. Even if not using rails, a similar structure also works well.
 
 ## Contributing
 

data/lib/simple_service.rb

@@ -1,12 +1,82 @@
-require 'simple_service/service_base'
-require 'simple_service/command'
-require 'simple_service/organizer'
-require 'simple_service/exceptions'
-require 'simple_service/commands/validates_commands_not_empty'
-require 'simple_service/commands/validates_commands_properly_inherit'
-require 'simple_service/commands/validates_expected_keys'
-require 'simple_service/ensure_organizer_is_valid'
+require 'simple_service/result'
+require 'simple_service/configuration'
 require 'simple_service/version'
 
 module SimpleService
+  def self.included(klass)
+    klass.extend ClassMethods
+    klass.include InstanceMethods
+    self.configure
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  module ClassMethods
+    def call(**kwargs)
+      service = self.new
+
+      if service.method(:call).arity.zero?
+        service.call
+      else
+        service.call(kwargs)
+      end
+    end
+
+    def command(command_name)
+      @commands ||= []
+      @commands << command_name
+    end
+
+    def commands(*args)
+      @commands ||= []
+      @commands += args
+    end
+  end
+
+  module InstanceMethods
+    def result
+      @result ||= Result.new
+    end
+
+    def commands
+      self.class.instance_variable_get('@commands')
+    end
+
+    def call(kwargs)
+      result.value = kwargs.is_a?(Result) ? kwargs.value : kwargs
+
+      commands.each do |command|
+        @current_command = command
+
+        command_output = if command.is_a?(Class)
+          command.new.call(result.value)
+        elsif command.is_a?(Symbol)
+          method(command).call(result.value)
+        end
+
+        if command_output.is_a?(Result)
+          result.append_result(command_output)
+        end
+
+        break if result.failure?
+      end
+
+      result
+    end
+
+    def success(result_value)
+      result.success!(self.class, @current_command, result_value)
+    end
+
+    def failure(result_value)
+      result.failure!(self.class, @current_command, result_value)
+    end
+  end
 end

data/lib/simple_service/configuration.rb

@@ -0,0 +1,9 @@
+module SimpleService
+  class Configuration
+    attr_accessor :verbose_tracking
+
+    def initialize
+      @verbose_tracking = false
+    end
+  end
+end

data/lib/simple_service/result.rb

@@ -0,0 +1,56 @@
+module SimpleService
+  class Result
+    attr_accessor :value, :recorded_commands
+
+    def initialize()
+      @recorded_commands = []
+      @verbose_tracking = SimpleService.configuration.verbose_tracking
+    end
+
+    def success!(klass, command_name, result_value)
+      record_command(klass, command_name, result_value, :success)
+    end
+
+    def failure!(klass, command_name, result_value)
+      record_command(klass, command_name, result_value, :failure)
+    end
+
+    def append_result(other_result)
+      self.value = other_result.value
+      self.recorded_commands += other_result.recorded_commands
+    end
+
+    def commands
+      self.recorded_commands.map {|rc| rc[:command_name] }
+    end
+
+    def successes
+      self.recorded_commands.map {|rc| rc.has_key?(:success) }
+    end
+
+    def success?
+      successes.all?
+    end
+
+    def failure?
+      !success?
+    end
+
+    private
+
+    attr_reader :verbose_tracking
+
+    def record_command(klass, command_name, result_value, success_or_failure)
+      command_attrs = {
+        class_name: klass.to_s,
+        command_name: command_name,
+      }
+
+      command_attrs[:received_args] = self.value if verbose_tracking
+      command_attrs[success_or_failure] = verbose_tracking ? result_value : true
+
+      self.recorded_commands << command_attrs
+      self.value = result_value
+    end
+  end
+end