light-service 0.8.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa927bdc5eaab0a8eed9f198bf61c28c042dc530
-  data.tar.gz: 6855d34240f37a93ef2ece590074eabd30ff901d
+  metadata.gz: 24c5a758ab50b3cd0ec404ef0b8a426a3e77e42b
+  data.tar.gz: 03ec6d27e900c9685bd141340c2b191df781ab84
 SHA512:
-  metadata.gz: 5bb0724f04a18663620795c3f53fa048e88a6a07d441dd2250f1e0121f68f5b7f3d108aeb4ff64155ec83f6151756efc2f695df071d2f77dc14c3519380abddb
-  data.tar.gz: be037dc8236f1d38b860e912226e28a951db55be761c6b3f8591adf4404c1d61b367538ee4bd9c6595d546e50d206604529b71ed6ddefe59cd93e0a7a68cb5e6
+  metadata.gz: ef89eee65b07381b629c9f4b8e5aad0e4e719e370e8aa84c32a23f65824d42c3e9c14424810b8518a244df4769b3f2e4f22a1752f6c498e44e146b803041bff3
+  data.tar.gz: 3476522df0af4775eff555a986d0dffbfed8dad3c0cd77a7a5eb19ca25b39c7109c8da8756a30625d39bf89e10fb7a54fd6212c15955bc544c37e66f2be6293d

data/.travis.yml

@@ -1,10 +1,13 @@
 language: ruby
 
+env:
+  - RUN_COVERAGE_REPORT=true
+
 rvm:
-  - 2.1.8
   - 2.2.2
   - 2.3.3
-  - 2.4.0
+  - 2.4.1
+  - 2.5.0
 
 before_install:
   - 'echo ''gem: --no-ri --no-rdoc'' > ~/.gemrc'

data/README.md

@@ -3,6 +3,33 @@
 [![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)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
+
+<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.
+
+<br>
+
+## Table of Content
+* [Why LightService?](#why-lightservice)
+* [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)
+* [Benchmarking Actions with Around Advice](#benchmarking-actions-with-around-advice)
+* [Before and After Action Hooks](#before-and-after-action-hooks)
+* [Key Aliases](#key-aliases)
+* [Logging](#logging)
+* [Error Codes](#error-codes)
+* [Action Rollback](#action-rollback)
+* [Localizing Messages](#localizing-messages)
+* [Orchestrator Logic in Organizers](#orchestrator-logic-in-organizers)
+* [ContextFactory for Faster Action Testing](#contextfactory-for-faster-action-testing)
+
+
+## Why LightService?
 
 What do you think of this code?
 
@@ -107,8 +134,10 @@ class CalculatesOrderTaxAction
   extend ::LightService::Action
   expects :order, :tax_percentage
 
-  executed do |context|
-    order.tax = (order.total * (tax_percentage/100)).round(2)
+  # I am using ctx as an abbreviation for context
+  executed do |ctx|
+    order = ctx.order
+    order.tax = (order.total * (ctx.tax_percentage/100)).round(2)
   end
 
 end
@@ -117,9 +146,9 @@ class ProvidesFreeShippingAction
   extend LightService::Action
   expects :order
 
-  executed do |context|
-    if order.total_with_tax > 200
-      order.provide_free_shipping!
+  executed do |ctx|
+    if ctx.order.total_with_tax > 200
+      ctx.order.provide_free_shipping!
     end
   end
 end
@@ -147,18 +176,6 @@ I gave a [talk at RailsConf 2013](http://www.adomokos.com/2013/06/simple-and-ele
 simple and elegant Rails code where I told the story of how LightService was extracted from the projects I had worked on.
 
 
-## Table of Content
-* [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)
-* [Benchmarking Actions with Around Advice](#benchmarking-actions-with-around-advice)
-* [Key Aliases](#key-aliases)
-* [Logging](#logging)
-* [Error Codes](#error-codes)
-* [Action Rollback](#action-rollback)
-* [Localizing Messages](#localizing-messages)
-* [Orchestrators](#orchestrators)
-* [ContextFactory for Faster Action Testing](#contextfactory-for-faster-action-testing)
 
 ## 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:
@@ -187,7 +204,7 @@ When something goes wrong in an action and you want to halt the chain, you need
 The context's `fail!` method can take an optional message argument, this message might help describing what went wrong.
 In case you need to return immediately from the point of failure, you have to do that by calling `next context`.
 
-In case you want to fail the context and stop the execution of the executed block, use the `fail_and_return!('something went wront')` method.
+In case you want to fail the context and stop the execution of the executed block, use the `fail_and_return!('something went wrong')` method.
 This will immediately leave the block, you don't need to call `next context` to return from the block.
 
 Here is an example:
@@ -268,6 +285,103 @@ end
 
 Any object passed into `around_each` must respond to #call with two arguments: the action name and the context it will execute with. It is also passed a block, where LightService's action execution will be done in, so the result must be returned. While this is a little work, it also gives you before and after state access to the data for any auditing and/or checks you may need to accomplish.
 
+## Before and After Action Hooks
+
+In case you need to inject code right before and after the actions are executed, you can use the `before_actions` and `after_actions` hooks. It accepts one or multiple lambdas that the Action implementation will invoke. This addition to LightService is a great way to decouple instrumentation from business logic.
+
+Consider this code:
+
+```ruby
+class SomeOrganizer
+  extend LightService::Organizer
+
+  def call(ctx)
+    with(ctx).reduce(actions)
+  end
+
+  def actions
+    OneAction,
+    TwoAction,
+    ThreeAction
+  end
+end
+
+class TwoAction
+  extend LightService::Action
+  expects :user, :logger
+
+  executed do |ctx|
+    # Logging information
+    if ctx.user.role == 'admin'
+       ctx.logger.info('admin is doing something')
+    end
+
+    ctx.user.do_something
+  end
+end
+```
+
+The logging logic makes `TwoAction` more complex, there is more code for logging than for business logic.
+
+You have two options to decouple instrumentation from real logic with `before_actions` and `after_actions` hooks:
+
+1. Declare your hooks in the Organizer
+2. Attach hooks to the Organizer from the outside
+
+This is how you can declaratively add before and after hooks to the Organizer:
+
+```ruby
+class SomeOrganizer
+  extend LightService::Organizer
+  before_actions (lambda do |ctx|
+                           if ctx.current_action == TwoAction
+                             return unless ctx.user.role == 'admin'
+                             ctx.logger.info('admin is doing something')
+                           end
+                         end)
+  after_actions (lambda do |ctx|
+                          if ctx.current_action == TwoAction
+                            return unless ctx.user.role == 'admin'
+                            ctx.logger.info('admin is DONE doing something')
+                          end
+                        end)
+
+  def call(ctx)
+    with(ctx).reduce(actions)
+  end
+
+  def actions
+    OneAction,
+    TwoAction,
+    ThreeAction
+  end
+end
+
+class TwoAction
+  extend LightService::Action
+  expects :user
+
+  executed do |ctx|
+    ctx.user.do_something
+  end
+end
+```
+
+Note how the action has no logging logic after this change. Also, you can target before and after action logic for specific actions, as the `ctx.current_action` will have the class name of the currently processed action. In the example above, logging will occur only for `TwoAction` and not for `OneAction` or `ThreeAction`.
+
+Here is how you can declaratively add `before_hooks` or `after_hooks` to your Organizer from the outside:
+
+```ruby
+SomeOrganizer.before_actions =
+  lambda do |ctx|
+    if ctx.current_action == TwoAction
+      return unless ctx.user.role == 'admin'
+      ctx.logger.info('admin is doing something')
+    end
+  end
+```
+
+These ideas are originally from Aspect Oriented Programming, read more about them [here](https://en.wikipedia.org/wiki/Aspect-oriented_programming).
 
 ## Expects and Promises
 The `expects` and `promises` macros are rules for the inputs/outputs of an action.
@@ -576,7 +690,7 @@ end
 
 To get the value of a `fail!` or `succeed!` message, simply call `#message` on the returned context.
 
-## Orchestrators
+## Orchestrator Logic in Organizers
 
 The Organizer - Action combination works really well for simple use cases. However, as business logic gets more complex, or when LightService is used in an ETL workflow, the code that routes the different organizers becomes very complex and imperative. Let's look at a piece of code that does basic data transformations:
 
@@ -607,20 +721,20 @@ The `LightService::Context` is initialized with the first action, that context i
 
 ```ruby
 class ExtractsTransformsLoadsData
-  extend LightService::Orchestrator
+  extend LightService::Organizer
 
-  def self.run(connection)
-    with(:connection => connection).reduce(steps)
+  def self.call(connection)
+    with(:connection => connection).reduce(actions)
   end
 
-  def self.steps
+  def self.actions
     [
       RetrievesConnectionInfo,
       PullsDataFromRemoteApi,
       reduce_if(->(ctx) { ctx.retrieved_items.empty? }, [
         NotifiesEngineeringTeamAction
       ]),
-      iterate(:retrieved_item, [
+      iterate(:retrieved_items, [
         TransformsData
       ]),
       LoadsData,
@@ -632,40 +746,23 @@ 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.
 
-Our convention for naming the public methods on the different items at different levels is this:
-```
-Orchestrators
-   |-> run - steps
-   Organizers
-       |-> call - actions
-       Actions
-           |-> execute
-```
-
-You can mix organizers with actions in the orchestrator steps, but mixing other organizers with actions in an organizer is discouraged for the sake of simplicity.
-
-The 6 different constructs an orchestrator can have:
-
-1. `reduce`
-2. `reduce_until`
-3. `reduce_if`
-4. `iterate`
-5. `execute`
-6. `with_callback`
-
-The `reduce` method needs no introduction, it behaves similarly to organizers' `reduce` method.
+The 5 different orchestrator constructs an organizer can have:
 
-`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/orchestrator/reduce_until_spec.rb) to see how it's used.
+1. `reduce_until`
+2. `reduce_if`
+3. `iterate`
+4. `execute`
+5. `with_callback`
 
-`reduce_if` will reduce the included organizers and/or actions if the predicate in the lambda evaluates to true. [This acceptance test](spec/acceptance/orchestrator/reduce_if_spec.rb) describes this functionality.
+`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.
 
-`iterate` gives your iteration logic, the symbol you define there has to be in the context as a key. For example. to iterate over items you will use `iterate(:items)` in your steps, the context needs to have `items` as a key, otherwise it will fail. The orchestrator will singularize the collection name and will put the actual item into the context under that name. Remaining with the example above, each element will be accessible by the name `item` for the actions in the `iterate` steps. [This acceptance test](spec/acceptance/orchestrator/iterate_spec.rb) should provide you with an example.
+`reduce_if` will reduce the included organizers and/or actions if the predicate in the lambda evaluates to true. [This acceptance test](spec/acceptance/organizer/reduce_if_spec.rb) describes this functionality.
 
-To take advantage of another organizer or action, you might need to tweak the context a bit. Let's say you have a hash, and you need to iterate over its values in a series of action. To alter the context and have the values assigned into a variable, you need to create a new action with 1 line of code in it. That seems a lot of ceremony for a simple change. You can do that in a `execute` method like this `execute(->(ctx) { ctx[:some_values] = ctx.some_hash.values })`. [This test](spec/acceptance/orchestrator/execute_spec.rb) describes how you can use it.
+`iterate` gives your iteration logic, the symbol you define there has to be in the context as a key. For example, to iterate over items you will use `iterate(:items)` in your steps, the context needs to have `items` as a key, otherwise it will fail. The organizer will singularize the collection name and will put the actual item into the context under that name. Remaining with the example above, each element will be accessible by the name `item` for the actions in the `iterate` steps. [This acceptance test](spec/acceptance/organizer/iterate_spec.rb) should provide you with an example.
 
-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/orchestrator/with_callback_spec.rb) as a working example.
+To take advantage of another organizer or action, you might need to tweak the context a bit. Let's say you have a hash, and you need to iterate over its values in a series of action. To alter the context and have the values assigned into a variable, you need to create a new action with 1 line of code in it. That seems a lot of ceremony for a simple change. You can do that in a `execute` method like this `execute(->(ctx) { ctx[:some_values] = ctx.some_hash.values })`. [This test](spec/acceptance/organizer/execute_spec.rb) describes how you can use it.
 
-** Thanks to [@bwvoss](https://github.com/bwvoss) for writing most of the Orchestrators code, I only ported his changes to LS and submitted the PR.
+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.
 
 ## ContextFactory for Faster Action Testing
 

data/RELEASES.md

@@ -1,5 +1,11 @@
 A brief list of new features and changes introduced with the specified version.
 
+### 0.10.0
+* Adding [before_actions and after_actions hooks](https://github.com/adomokos/light-service/pull/144).
+
+### 0.9.0
+* [Deprecate Orchestrator](https://github.com/adomokos/light-service/pull/132) by moving its functionality to Organizers.
+
 ### 0.8.4
 * Only pass [default argument](https://github.com/adomokos/light-service/pull/123) to Hash#fetch in context if no block given.
 

data/gemfiles/activesupport_3.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "appraisal", "~> 2.0"
 gem "activesupport", "~> 3.0"
+gem "appraisal", "~> 2.0"
 
 gemspec :path => "../"

data/gemfiles/activesupport_4.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "appraisal", "~> 2.0"
 gem "activesupport", "~> 4.0"
+gem "appraisal", "~> 2.0"
 
 gemspec :path => "../"

data/gemfiles/activesupport_5.gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gem "appraisal", "~> 2.0"
 gem "activesupport", "~> 5.0"
+gem "appraisal", "~> 2.0"
 
 gemspec :path => "../"

data/lib/light-service.rb

@@ -7,9 +7,16 @@ require 'light-service/configuration'
 require 'light-service/localization_adapter'
 require 'light-service/context'
 require 'light-service/context/key_verifier'
+require 'light-service/organizer/scoped_reducable'
 require 'light-service/organizer/with_reducer'
 require 'light-service/organizer/with_reducer_log_decorator'
 require 'light-service/organizer/with_reducer_factory'
+require 'light-service/organizer/reduce_if'
+require 'light-service/organizer/reduce_until'
+require 'light-service/organizer/iterate'
+require 'light-service/organizer/execute'
+require 'light-service/organizer/with_callback'
+require 'light-service/organizer/verify_call_method_exists'
 require 'light-service/action'
 require 'light-service/organizer'
 require 'light-service/orchestrator'

data/lib/light-service/action.rb

@@ -23,11 +23,11 @@ module LightService
       end
 
       def expected_keys
-        @_expected_keys ||= []
+        @expected_keys ||= []
       end
 
       def promised_keys
-        @_promised_keys ||= []
+        @promised_keys ||= []
       end
 
       def executed
@@ -42,7 +42,9 @@ module LightService
             action_context.define_accessor_methods_for_keys(all_keys)
 
             catch(:jump_when_failed) do
+              call_before_action(action_context)
               yield(action_context)
+              call_after_action(action_context)
             end
           end
         end
@@ -70,6 +72,24 @@ module LightService
       def all_keys
         expected_keys + promised_keys
       end
+
+      def call_before_action(context)
+        invoke_callbacks(context[:_before_actions], context)
+      end
+
+      def call_after_action(context)
+        invoke_callbacks(context[:_after_actions], context)
+      end
+
+      def invoke_callbacks(callbacks, context)
+        return context unless callbacks
+
+        callbacks.each do |cb|
+          cb.call(context)
+        end
+
+        context
+      end
     end
   end
 end

data/lib/light-service/orchestrator.rb

@@ -11,11 +11,13 @@ module LightService
       end
 
       def reduce(steps, context = @context)
+        issue_deprecation_warning_for(__method__)
+
         steps.each_with_object(context) do |step, ctx|
-          if step.respond_to?(:execute)
-            step.execute(ctx)
-          elsif step.respond_to?(:call)
+          if step.respond_to?(:call)
             step.call(ctx)
+          elsif step.respond_to?(:execute)
+            step.execute(ctx)
           else
             raise 'Pass either an action or organizer'
           end
@@ -23,6 +25,8 @@ module LightService
       end
 
       def reduce_until(condition_block, steps)
+        issue_deprecation_warning_for(__method__)
+
         lambda do |ctx|
           return ctx if ctx.stop_processing?
 
@@ -36,6 +40,8 @@ module LightService
       end
 
       def reduce_if(condition_block, steps)
+        issue_deprecation_warning_for(__method__)
+
         lambda do |ctx|
           return ctx if ctx.stop_processing?
 
@@ -45,6 +51,8 @@ module LightService
       end
 
       def execute(code_block)
+        issue_deprecation_warning_for(__method__)
+
         lambda do |ctx|
           return ctx if ctx.stop_processing?
 
@@ -54,6 +62,8 @@ module LightService
       end
 
       def iterate(collection_key, steps)
+        issue_deprecation_warning_for(__method__)
+
         lambda do |ctx|
           return ctx if ctx.stop_processing?
 
@@ -69,6 +79,8 @@ module LightService
       end
 
       def with_callback(action, steps)
+        issue_deprecation_warning_for(__method__)
+
         lambda do |ctx|
           return ctx if ctx.stop_processing?
 
@@ -100,6 +112,12 @@ module LightService
 
         ctx
       end
+
+      def issue_deprecation_warning_for(method_name)
+        msg = "`Orchestrator##{method_name}` is DEPRECATED and will be " \
+          "removed, please switch to `Organizer##{method_name} instead. "
+        ActiveSupport::Deprecation.warn(msg)
+      end
     end
   end
 end