light-service 0.8.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa927bdc5eaab0a8eed9f198bf61c28c042dc530
-  data.tar.gz: 6855d34240f37a93ef2ece590074eabd30ff901d
+  metadata.gz: 30ef43a9d6e26800b7599546ffea8b1cb15b1533
+  data.tar.gz: 28ee4863b5ea1a859c9e4ca288c20b23f99bc4e9
 SHA512:
-  metadata.gz: 5bb0724f04a18663620795c3f53fa048e88a6a07d441dd2250f1e0121f68f5b7f3d108aeb4ff64155ec83f6151756efc2f695df071d2f77dc14c3519380abddb
-  data.tar.gz: be037dc8236f1d38b860e912226e28a951db55be761c6b3f8591adf4404c1d61b367538ee4bd9c6595d546e50d206604529b71ed6ddefe59cd93e0a7a68cb5e6
+  metadata.gz: dab3019cc90cecb1d97b2d36dcf5ad97dde57a22424eefbe91978d024205ea90215df4045594e8744fc9af5ae58ffd45f9c9727d921aee8af1bae50b0df754d3
+  data.tar.gz: 528fc079179b6e276aa6b4ec331326b51c279c3e234a0fc5998b336098375ad189c0bc274a616446d9aa851f10cda8653901d7f9e13a2e5ee0251f2f037e9324

data/.travis.yml

@@ -1,5 +1,8 @@
 language: ruby
 
+env:
+  - RUN_COVERAGE_REPORT=true
+
 rvm:
   - 2.1.8
   - 2.2.2

data/README.md

@@ -3,6 +3,15 @@
 [![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><br>
 
 What do you think of this code?
 
@@ -157,7 +166,7 @@ simple and elegant Rails code where I told the story of how LightService was ext
 * [Error Codes](#error-codes)
 * [Action Rollback](#action-rollback)
 * [Localizing Messages](#localizing-messages)
-* [Orchestrators](#orchestrators)
+* [Orchestrator Logic in Organizers](#orchestrator-logic-in-organizers)
 * [ContextFactory for Faster Action Testing](#contextfactory-for-faster-action-testing)
 
 ## Stopping the Series of Actions
@@ -576,7 +585,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,13 +616,13 @@ 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)
+  def self.call(connection)
     with(:connection => connection).reduce(steps)
   end
 
-  def self.steps
+  def self.actions
     [
       RetrievesConnectionInfo,
       PullsDataFromRemoteApi,
@@ -632,40 +641,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,8 @@
 A brief list of new features and changes introduced with the specified version.
 
+### 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/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/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

data/lib/light-service/organizer.rb

@@ -17,7 +17,7 @@ module LightService
     # In case this module is included
     module ClassMethods
       def with(data = {})
-        VerifyCallMethodExists.call(self, caller(1..1).first)
+        VerifyCallMethodExists.run(self, caller(1..1).first)
         data[:_aliases] = @aliases if @aliases
         WithReducerFactory.make(self).with(data)
       end
@@ -26,29 +26,24 @@ module LightService
         with({}).reduce(actions)
       end
 
-      # We need to make sure existing users will
-      # use `call` method name going forward.
-      # This should be removed eventually.
-      class VerifyCallMethodExists
-        def self.call(klass, first_caller = '')
-          invoker_method = caller_method(first_caller)
-          return if invoker_method == 'call'
+      def reduce_if(condition_block, steps)
+        ReduceIf.run(self, condition_block, steps)
+      end
 
-          call_method_exists = klass.methods.include?(:call)
-          return if call_method_exists
+      def reduce_until(condition_block, steps)
+        ReduceUntil.run(self, condition_block, steps)
+      end
 
-          warning_msg = "The <#{klass.name}> class is an organizer, " \
-                        "its entry method (the one that calls with & reduce) " \
-                        "should be named `call`. " \
-                        "Please use #{klass}.call going forward."
-          ActiveSupport::Deprecation.warn(warning_msg)
-        end
+      def iterate(collection_key, steps)
+        Iterate.run(self, collection_key, steps)
+      end
 
-        def self.caller_method(first_caller)
-          return nil unless first_caller =~ /`(.*)'/
+      def execute(code_block)
+        Execute.run(code_block)
+      end
 
-          Regexp.last_match[1]
-        end
+      def with_callback(action, steps)
+        WithCallback.run(self, action, steps)
       end
     end
 

data/lib/light-service/organizer/execute.rb

@@ -0,0 +1,14 @@
+module LightService
+  module Organizer
+    class Execute
+      def self.run(code_block)
+        lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
+          code_block.call(ctx)
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/iterate.rb

@@ -0,0 +1,22 @@
+module LightService
+  module Organizer
+    class Iterate
+      extend ScopedReducable
+
+      def self.run(organizer, collection_key, steps)
+        lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
+          collection = ctx[collection_key]
+          item_key = collection_key.to_s.singularize.to_sym
+          collection.each do |item|
+            ctx[item_key] = item
+            ctx = scoped_reduce(organizer, ctx, steps)
+          end
+
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/reduce_if.rb

@@ -0,0 +1,17 @@
+module LightService
+  module Organizer
+    class ReduceIf
+      extend ScopedReducable
+
+      def self.run(organizer, condition_block, steps)
+        lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
+          ctx = scoped_reduce(organizer, ctx, steps) \
+                  if condition_block.call(ctx)
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/reduce_until.rb

@@ -0,0 +1,20 @@
+module LightService
+  module Organizer
+    class ReduceUntil
+      extend ScopedReducable
+
+      def self.run(organizer, condition_block, steps)
+        lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
+          loop do
+            ctx = scoped_reduce(organizer, ctx, steps)
+            break if condition_block.call(ctx) || ctx.failure?
+          end
+
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/scoped_reducable.rb

@@ -0,0 +1,13 @@
+module LightService
+  module Organizer
+    module ScopedReducable
+      def scoped_reduce(organizer, ctx, steps)
+        ctx.reset_skip_remaining! unless ctx.failure?
+        ctx = organizer.with(ctx).reduce([steps])
+        ctx.reset_skip_remaining! unless ctx.failure?
+
+        ctx
+      end
+    end
+  end
+end

data/lib/light-service/organizer/verify_call_method_exists.rb

@@ -0,0 +1,28 @@
+module LightService
+  module Organizer
+    # We need to make sure existing users will
+    # use `call` method name going forward.
+    # This should be removed eventually.
+    class VerifyCallMethodExists
+      def self.run(klass, first_caller = '')
+        invoker_method = caller_method(first_caller)
+        return if invoker_method == 'call'
+
+        call_method_exists = klass.methods.include?(:call)
+        return if call_method_exists
+
+        warning_msg = "The <#{klass.name}> class is an organizer, " \
+                      "its entry method (the one that calls with & reduce) " \
+                      "should be named `call`. " \
+                      "Please use #{klass}.call going forward."
+        ActiveSupport::Deprecation.warn(warning_msg)
+      end
+
+      def self.caller_method(first_caller)
+        return nil unless first_caller =~ /`(.*)'/
+
+        Regexp.last_match[1]
+      end
+    end
+  end
+end

data/lib/light-service/organizer/with_callback.rb

@@ -0,0 +1,26 @@
+module LightService
+  module Organizer
+    class WithCallback
+      extend ScopedReducable
+
+      def self.run(organizer, action, steps)
+        lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
+          # This will only allow 2 level deep nesting of callbacks
+          previous_callback = ctx[:callback]
+
+          ctx[:callback] = lambda do |context|
+            ctx = scoped_reduce(organizer, context, steps)
+            ctx
+          end
+
+          ctx = action.execute(ctx)
+          ctx[:callback] = previous_callback
+
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/light-service/organizer/with_reducer.rb

@@ -1,7 +1,7 @@
 module LightService
   module Organizer
     class WithReducer
-      attr_reader :context, :around_each_handler
+      attr_reader :context
 
       def with(data = {})
         @context = LightService::Context.make(data)
@@ -13,6 +13,14 @@ module LightService
         self
       end
 
+      def around_each_handler
+        @around_each_handler ||= Class.new do
+          def self.call(_context)
+            yield
+          end
+        end
+      end
+
       def reduce(*actions)
         raise "No action(s) were provided" if actions.empty?
         actions.flatten!
@@ -46,10 +54,12 @@ module LightService
       private
 
       def invoke_action(current_context, action)
-        return action.execute(current_context) unless around_each_handler
-
         around_each_handler.call(current_context) do
-          action.execute(current_context)
+          if action.respond_to?(:call)
+            action.call(current_context)
+          else
+            action.execute(current_context)
+          end
         end
       end