light-service 0.10.3 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 35d148e9bdcc089cd30046a2a99eff468ec77fde
-  data.tar.gz: 95b6d152ab5eca62471cfb245be0f60c2d4bfc73
+SHA256:
+  metadata.gz: f400829da41766f56e7f0cb9cfe95aa028ef8ab34bf0bc5794bfafcff3cdcfb1
+  data.tar.gz: 41dbd504ac39a0804eb445b4af086dbcf9986264077994277e17fde98b7bdc3d
 SHA512:
-  metadata.gz: 20fe035e150978da67f5cc624c9e142fc5299c7b20cc1f71d89c90a665577daa85ec73e32f695950f7d5d52ce0a4604159b08d367b195d27191819c18f497b38
-  data.tar.gz: 829ccc813a76c16da7ceb7aaa02262d30c555b5486224212b016588a45c2f172e050e6a2c6adc0c2ebef2c28ce5e9f3968a6c791fbc30c2cf4bee2f2a336824d
+  metadata.gz: e9a1148b82b6e1a0813400b0d23b013ff6f06965f3204bb3fa95101adc8a749223dd334887f7543622b4a829fd17f190c21dd5f601df3aecde8d8451459a76af
+  data.tar.gz: f0aec690e94896dcc13d6caa774003e49ddfa6b74c5acf9272fb7b9d3710d28db4a29601e725e3729deba820013c62b740739d5c6052c4c5ae93fd885cec6fda

data/.gitignore

@@ -17,3 +17,4 @@ test/version_tmp
 tmp
 vendor/bundle
 bin
+.idea

data/.rubocop.yml

@@ -1,4 +1,7 @@
+require: rubocop-performance
+
 AllCops:
+  TargetRubyVersion: 2.3
   Exclude:
     - 'lib/light-service.rb'
     - 'vendor/bundle/**/*'
@@ -46,3 +49,6 @@ Metrics/BlockLength:
 
 Layout/TrailingBlankLines:
   Enabled: false
+
+Layout/EndOfLine:
+  EnforcedStyle: lf

data/.travis.yml

@@ -4,16 +4,15 @@ env:
   - RUN_COVERAGE_REPORT=true
 
 rvm:
-  - 2.2.2
-  - 2.3.3
-  - 2.4.1
-  - 2.5.0
+  - 2.4.2
+  - 2.5.3
+  - 2.6.0
+  - 2.7.0
 
 before_install:
   - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'
   - gem install bundler
-  - bundle update simplecov
-  - bundle install --path vendor/bundle
+  - bundle install --clean --path vendor/bundle
 
 # uncomment this line if your project needs to run something other than `rake`:
 script:
@@ -21,13 +20,15 @@ script:
   - bundle exec rubocop
 
 gemfile:
-  - gemfiles/activesupport_3.gemfile
   - gemfiles/activesupport_4.gemfile
   - gemfiles/activesupport_5.gemfile
+  - gemfiles/activesupport_6.gemfile
 
 matrix:
   exclude:
-  - rvm: 2.1.8
-    gemfile: gemfiles/activesupport_5.gemfile
-  - rvm: 2.2.2
-    gemfile: gemfiles/activesupport_5.gemfile
+  - rvm: 2.4.2
+    gemfile: gemfiles/activesupport_6.gemfile
+  - rvm: 2.7.0
+    gemfile: gemfiles/activesupport_3.gemfile
+  - rvm: 2.7.0
+    gemfile: gemfiles/activesupport_4.gemfile

data/Appraisals

@@ -1,7 +1,3 @@
-appraise "activesupport-3" do
-  gem "activesupport", "~> 3.0"
-end
-
 appraise "activesupport-4" do
   gem "activesupport", "~> 4.0"
 end
@@ -9,3 +5,7 @@ end
 appraise "activesupport-5" do
   gem "activesupport", "~> 5.0"
 end
+
+appraise "activesupport-6" do
+  gem "activesupport", "~> 6.0"
+end

data/Gemfile

@@ -2,5 +2,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in light_service.gemspec
 gemspec
-
-gem 'appraisal', '~> 2.0'

data/README.md

@@ -1,12 +1,13 @@
 ![LightService](https://raw.githubusercontent.com/adomokos/light-service/master/resources/light-service.png)
 
 [![Gem Version](https://img.shields.io/gem/v/light-service.svg)](https://rubygems.org/gems/light-service)
-[![Build Status](https://secure.travis-ci.org/adomokos/light-service.png)](http://travis-ci.org/adomokos/light-service)
-[![Code Climate](https://codeclimate.com/github/adomokos/light-service.png)](https://codeclimate.com/github/adomokos/light-service)
-[![Dependency Status](https://beta.gemnasium.com/badges/github.com/adomokos/light-service.svg)](https://beta.gemnasium.com/projects/github.com/adomokos/light-service)
+[![Build Status](https://secure.travis-ci.org/adomokos/light-service.svg)](http://travis-ci.org/adomokos/light-service)
+[![codecov](https://codecov.io/gh/adomokos/light-service/branch/master/graph/badge.svg)](https://codecov.io/gh/adomokos/light-service)
+[![Code Climate](https://codeclimate.com/github/adomokos/light-service.svg)](https://codeclimate.com/github/adomokos/light-service)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
+[![Download Count](https://ruby-gem-downloads-badge.herokuapp.com/light-service?type=total)](https://rubygems.org/gems/light-service)
 
-<br><br>
+<br>
 
 ![Orchestrators-Deprecated](resources/orchestrators_deprecated.svg)
 <br>Version 0.9.0 deprecates Orchestrators and moves all their functionalities into Organizers. Please check out [this PR](https://github.com/adomokos/light-service/pull/132) to see the changes.
@@ -15,6 +16,11 @@
 
 ## Table of Content
 * [Why LightService?](#why-lightservice)
+* [Getting Started](#getting-started)
+    * [Requirements](#requirements)
+    * [Installation](#installation)
+    * [Your first action](#your-first-action)
+    * [Your first organizer](#your-first-organizer)
 * [Stopping the Series of Actions](#stopping-the-series-of-actions)
     * [Failing the Context](#failing-the-context)
     * [Skipping the Rest of the Actions](#skipping-the-rest-of-the-actions)
@@ -27,7 +33,7 @@
 * [Localizing Messages](#localizing-messages)
 * [Orchestrator Logic in Organizers](#orchestrator-logic-in-organizers)
 * [ContextFactory for Faster Action Testing](#contextfactory-for-faster-action-testing)
-
+* [Rails support](#rails-support)
 
 ## Why LightService?
 
@@ -79,7 +85,7 @@ Wouldn't it be nice to see this instead?
 (
   LooksUpTaxPercentage,
   CalculatesOrderTax,
-  ChecksFreeShipping
+  ProvidesFreeShipping
 )
 ```
 
@@ -175,7 +181,143 @@ end
 I gave a [talk at RailsConf 2013](http://www.adomokos.com/2013/06/simple-and-elegant-rails-code-with.html) on
 simple and elegant Rails code where I told the story of how LightService was extracted from the projects I had worked on.
 
+## Getting started
+
+### Requirements
+
+This gem requires ruby 2.x. Use of [generators](#rails-support) requires Rails 5+ (tested on Rails 5.x & 6.x only. Will probably work on
+Rails versions as old as 3.2)
+
+### Installation
+
+In your Gemfile:
+
+```ruby
+gem 'light-service'
+```
+
+And then
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install light-service
+```
+
+### Your first action
+
+LightService's building blocks are actions that are normally composed within an organizer, but can be run independently.
+Let's make a simple greeter action. Each action can take an optional list of expected inputs and promised outputs. If
+these are specified and missing at action start and stop respectively, an exception will be thrown.
+
+```ruby
+class GreetsPerson
+  extend ::LightService::Action
+
+  expects :name
+  promises :greeting
+
+  executed do |context|
+    context.greeting = "Hey there, #{name}. You enjoying LightService so far?"
+  end
+end
+```
 
+When an action is run, you have access to its returned context, and the status of the action. You can invoke an
+action by calling `.execute` on its class with `key: value` arguments, and inspect its status and context like so:
+
+```ruby
+outcome = GreetsPerson.execute(name: "Han")
+
+if outcome.success?
+  puts outcome.greeting # which was a promised context value
+elsif outcome.failure?
+  puts "Rats... I can't say hello to you"
+end
+```
+
+You will notice that actions are set up to promote simplicity, i.e. they either succeed or fail, and they have
+very clear inputs and outputs. Ideally, they should do [exactly one thing](https://en.wikipedia.org/wiki/Single-responsibility_principle). This makes them as easy to test as unit tests.
+
+### Your first organizer
+
+LightService provides a facility to compose actions using organizers. This is great when you have a business process
+to execute that has multiple steps. By composing actions that do exactly one thing, you can sequence simple
+actions together to perform complex multi-step business processes in a clear manner that is very easy
+to reason about.
+
+There are advanced ways to sequence actions that can be found later in the README, but we'll keep this simple for now.
+First, let's add a second action that we can sequence to run after the `GreetsPerson` action from above:
+
+```ruby
+class RandomlyAwardsPrize
+  extend ::LightService::Action
+
+  expects :name, :greeting
+  promises :did_i_win
+
+  executed do |context|
+    prize_num  = "#{context.name}__#{context.greeting}".length
+    prizes     = ["jelly beans", "ice cream", "pie"]
+    did_i_win  = rand((1..prize_num)) % 7 == 0
+    did_i_lose = rand((1..prize_num)) % 13 == 0
+
+    if did_i_lose
+      # When failing, send a message as an argument, readable from the return context
+      context.fail!("you are exceptionally unlucky")
+    else
+      # You can specify 'optional' context items by treating context like a hash.
+      # Useful for when you may or may not be returning extra data. Ideally, selecting
+      # a prize should be a separate action that is only run if you win.
+      context[:prize]   = "lifetime supply of #{prizes.sample}" if did_i_win
+      context.did_i_win = did_i_win
+    end
+  end
+end
+```
+
+And here's the organizer that ties the two together. You implement a `call` class method that takes some arguments and
+from there sends them to `with` in `key: value` format which forms the initial state of the context. From there, chain
+`reduce` to `with` and send it a list of action class names in sequence. The organizer will call each action, one
+after the other, and build up the context as it goes along.
+
+```ruby
+class WelcomeAPotentiallyLuckyPerson
+  extend LightService::Organizer
+
+  def self.call(name)
+    with(:name => name).reduce(GreetsPerson, RandomlyAwardsPrize)
+  end
+end
+```
+
+When an organizer is run, you have access to the context as it passed through all actions, and the overall status
+of the organized execution. You can invoke an organizer by calling `.call` on the class with the expected arguments,
+and inspect its status and context just like you would an action:
+
+```ruby
+outcome = WelcomeAPotentiallyLuckyPerson.call("Han")
+
+if outcome.success?
+  puts outcome.greeting # which was a promised context value
+
+  if outcome.did_i_win
+    puts "And you've won a prize! Lucky you. Please see the front desk for your #{outcome.prize}."
+  end
+else # outcome.failure? is true, and we can pull the failure message out of the context for feedback to the user.
+  puts "Rats... I can't say hello to you, because #{outcome.message}."
+end
+```
+
+Because organizers generally run through complex business logic, and every action has the potential to cause a failure,
+testing an organizer is functionally equivalent to an integration test.
+
+For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki) and review
+the ["Why LightService" section](#why-lightservice) above.
 
 ## Stopping the Series of Actions
 When nothing unexpected happens during the organizer's call, the returned `context` will be successful. Here is how you can check for this:
@@ -295,14 +437,16 @@ Consider this code:
 class SomeOrganizer
   extend LightService::Organizer
 
-  def call(ctx)
+  def self.call(ctx)
     with(ctx).reduce(actions)
   end
 
-  def actions
-    OneAction,
-    TwoAction,
-    ThreeAction
+  def self.actions
+    [
+      OneAction,
+      TwoAction,
+      ThreeAction
+    ]
   end
 end
 
@@ -346,14 +490,16 @@ class SomeOrganizer
                           end
                         end)
 
-  def call(ctx)
+  def self.call(ctx)
     with(ctx).reduce(actions)
   end
 
-  def actions
-    OneAction,
-    TwoAction,
-    ThreeAction
+  def self.actions
+    [
+      OneAction,
+      TwoAction,
+      ThreeAction
+    ]
   end
 end
 
@@ -452,9 +598,9 @@ class AnOrganizer
 
   def self.call(order)
     with(:order => order).reduce(
-        AnAction,
-        AnotherAction,
-      )
+      AnAction,
+      AnotherAction,
+    )
   end
 end
 
@@ -535,6 +681,15 @@ I, [DATE]  INFO -- : [LightService] - ;-) <TestDoubles::MakesLatteAction> has de
 I, [DATE]  INFO -- : [LightService] - context message: Can't make a latte with a fatty milk like that!
 ```
 
+You can specify the logger on the organizer level, so the organizer does not use the global logger.
+
+```ruby
+class FooOrganizer
+  extend LightService::Organizer
+  log_with Logger.new("/my/special.log")
+end
+```
+
 ## Error Codes
 You can add some more structure to your error handling by taking advantage of error codes in the context.
 Normally, when something goes wrong in your actions, you fail the process by setting the context to failure:
@@ -611,7 +766,28 @@ Using the `rolled_back` macro is optional for the actions in the chain. You shou
 
 The actions are rolled back in reversed order from the point of failure starting with the action that triggered it.
 
-See [this](spec/acceptance/rollback_spec.rb) acceptance test to learn more about this functionality.
+See [this acceptance test](spec/acceptance/rollback_spec.rb) to learn more about this functionality.
+
+You may find yourself directly using an action that can roll back by calling `.execute` instead of using it from within an Organizer.
+If this action fails and attempts a rollback, a `FailWithRollbackError` exception will be raised. This is so that the organizer can
+rollback the actions one by one. If you don't want to wrap your call to the action with a `begin, rescue FailWithRollbackError`
+block, you can introspect the context like so, and keep your usage of the action clean:
+
+```ruby
+class FooAction
+  extend LightService::Action
+
+  executed do |context|
+    # context.organized_by will be nil if run from an action,
+    # or will be the class name if run from an organizer
+    if context.organized_by.nil?
+      context.fail!
+    else
+      context.fail_with_rollback!
+    end
+  end
+end
+```
 
 ## Localizing Messages
 By default LightService provides a mechanism for easily translating your error or success messages via I18n.  You can also provide your own custom localization adapter if your application's logic is more complex than what is shown here.
@@ -746,13 +922,15 @@ end
 
 This code is much easier to reason about, it's less noisy and it captures the goal of LightService well: simple, declarative code that's easy to understand.
 
-The 5 different orchestrator constructs an organizer can have:
+The 7 different orchestrator constructs an organizer can have:
 
 1. `reduce_until`
 2. `reduce_if`
 3. `iterate`
 4. `execute`
 5. `with_callback`
+6. `add_to_context`
+7. `add_aliases`
 
 `reduce_until` behaves like a while loop in imperative languages, it iterates until the provided predicate in the lambda evaluates to true. Take a look at [this acceptance test](spec/acceptance/organizer/reduce_until_spec.rb) to see how it's used.
 
@@ -764,6 +942,10 @@ To take advantage of another organizer or action, you might need to tweak the co
 
 Use `with_callback` when you want to execute actions with a deferred and controlled callback. It works similar to a Sax parser, I've used it for processing large files. The advantage of it is not having to keep large amount of data in memory. See [this acceptance test](spec/acceptance/organizer/with_callback_spec.rb) as a working example.
 
+`add_to_context` can add key-value pairs on the fly to the context. This functionality is useful when you need a value injected into the context under a specific key right before the subsequent actions are executed. [This test](spec/acceptance/organizer/add_to_context_spec.rb) describes its functionality.
+
+Your action needs a certain key in the context but it's under a different one? Use the function `add_aliases` to alias an existing key in the context under the desired key. Take a look at [this test](spec/acceptance/organizer/add_aliases_spec.rb) to see an example.
+
 ## ContextFactory for Faster Action Testing
 
 As the complexity of your workflow increases, you will find yourself spending more and more time creating a context (LightService::Context it is) for your action tests. Some of this code can be reused by clever factories, but still, you are using a context that is artificial, and can be different from what the previous actions produced. This is especially true, when you use LightService in ETLs, where you start out with initial data and your actions are mutating its state.
@@ -817,28 +999,52 @@ This context then can be passed to the action under test, freeing you up from th
 
 In case your organizer has more logic in its `call` method, you could create your own test organizer in your specs like you can see it in this [acceptance test](spec/acceptance/testing/context_factory_spec.rb#L4-L11). This is reusable in all your action tests.
 
-## Requirements
+## Rails support
 
-This gem requires ruby 2.x
+LightService includes Rails generators for creating both Organizers and Actions along with corresponding tests. Currently only RSpec is
+supported ([PR's for supporting MiniTest are welcome](https://github.com/adomokos/light-service/pulls))
 
-## Installation
-Add this line to your application's Gemfile:
+Note: Generators are namespaced to `light_service` not `light-service` due to Rake name constraints.
 
-    gem 'light-service'
+### Organizer generation
 
-And then execute:
+```shell
+rails generate light_service:organizer My::SuperFancy::Organizer
+# -- or
+rails generate light_service:organizer my/super_fancy/organizer
+```
 
-    $ bundle
+Options for this generator are:
 
-Or install it yourself as:
+* `--dir=<SOME_DIR>`. `<SOME_DIR>` defaults to `organizers`. Will write organizers to `/app/organizers`, and specs to `/spec/organizers`
+* `--no-tests`. Default is `--tests`. Will generate a test file matching the namespace you've supplied.
+
+### Action generation
 
-    $ gem install light-service
+```shell
+rails generate light_service:action My::SuperFancy::Action
+# -- or
+rails generate light_service:action my/super_fancy/action
+```
+
+Options for this generator are:
+
+* `--dir=<SOME_DIR>`. `<SOME_DIR>` defaults to `actions`. Will write actions to `/app/actions`, and specs to `/spec/actions`
+* `--no-tests`. Defaults is `--tests`. Will generate a test file matching the namespace you've supplied.
+* `--no-roll-back`. Default is `--roll-back`. Will generate a `rolled_back` block for you to implement with [roll back functionality](#action-rollback).
+
+### Advanced action generation
+
+You are able to optionally specify `expects` and/or `promises` keys during generation
+
+```shell
+rails generate light_service:action CrankWidget expects:one_fish,two_fish promises:red_fish,blue_fish
+```
 
-## Usage
-Based on the refactoring example above, just create an organizer object that calls the
-actions in order and write code for the actions. That's it.
+When specifying `expects`, convenience variables will be initialized in the `executed` block so that you don't have to call
+them through the context. A stub context will be created in the test file using these keys too.
 
-For further examples, please visit the project's [Wiki](https://github.com/adomokos/light-service/wiki).
+When specifying `promises`, specs will be created testing for their existence after executing the action.
 
 ## Contributing
 1. Fork it