light-service 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dd24b40af28ef32897e621b863de7499a4c34038
-  data.tar.gz: 9ad9f2f66757c15d6d43197ba8e4537eef8df788
+  metadata.gz: 65ef2c9c99bebb3e4b19a0fbfc63c893381fbfe4
+  data.tar.gz: 6962376a614207f0475112a1f21c1872876ec865
 SHA512:
-  metadata.gz: 56d906cf2ad3d3e3ba7cdcdcf606120fa3421a0e8b552b0af958bebff23038b5a1bdf3769f2f1e529c57f1fad09a8236e2a1d68374b841983cf7faa506e47669
-  data.tar.gz: 68361c87eb7dd8a731cd28f14bf3e8d71012f5f23106b15f4c18a4402bfd78fd273132ebdef4fe80770ffa938833b825066fe0a244dfcb1d864917193b07b05c
+  metadata.gz: 7ea257de8c459ecccbcb0d702c61c603f45c3d6bc50f2a829925ecbe2af4e1fbeb0eee277a9005c99a1f928087610ce02e8317b63e13e329f8b4c2328958b997
+  data.tar.gz: 768698a21f441add9d09ec47eed6cc8384b1babb232c1778a3abbdf0531ac8179eb3b47c75c16e07db77b2fe14870fd29e65cd022b45f9b458e02e8a92a9d77e

data/README.md

@@ -187,6 +187,9 @@ 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.
+This will immediately leave the block, you don't need to call `next context` to return from the block.
+
 Here is an example:
 ```ruby
 class SubmitsOrderAction
@@ -195,10 +198,10 @@ class SubmitsOrderAction
 
   executed do |context|
     unless context.order.submit_order_successful?
-      context.fail!("Failed to submit the order")
-      next context
+      context.fail_and_return!("Failed to submit the order")
     end
 
+    # This won't be executed
     context.mailer.send_order_notification!
   end
 end
@@ -641,15 +644,16 @@ Orchestrators
 
 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 5 different constructs an orchestrator can have:
+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 interaction, it behaves similarly to organizers' `reduce` method.
+The `reduce` method needs no introduction, it behaves similarly to organizers' `reduce` method.
 
 `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.
 
@@ -659,6 +663,8 @@ The `reduce` method needs no interaction, it behaves similarly to organizers' `r
 
 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.
 
+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.
+
 ** 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.
 
 ## 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.8.2
+* A better way to [inspect](https://github.com/adomokos/light-service/pull/110) the context.
+* [Short-circuiting](https://github.com/adomokos/light-service/pull/113) the Orchestrator methods.
+* [Fail and return - with one call](https://github.com/adomokos/light-service/pull/115), no `and next` is needed.
+* Adding [with_callback](https://github.com/adomokos/light-service/pull/116) to Orchestrators, allows us to process large data in smaller chunks.
+
 ### 0.8.1
 * Renaming `skip_all!` to [skip_remaining!](https://github.com/adomokos/light-service/pull/103).
 * Adding [ContextFactory](https://github.com/adomokos/light-service/pull/107) for easier testing.

data/lib/light-service/action.rb

@@ -41,7 +41,9 @@ module LightService
           Context::KeyVerifier.verify_keys(action_context, self) do
             action_context.define_accessor_methods_for_keys(all_keys)
 
-            yield(action_context)
+            catch(:jump_when_failed) do
+              yield(action_context)
+            end
           end
         end
       end

data/lib/light-service/context.rb

@@ -87,6 +87,11 @@ module LightService
       @outcome = Outcomes::FAILURE
     end
 
+    def fail_and_return!(*args)
+      fail!(*args)
+      throw(:jump_when_failed, *args)
+    end
+
     def fail_with_rollback!(message = nil, error_code = nil)
       fail!(message, error_code)
       raise FailWithRollbackError
@@ -138,6 +143,23 @@ module LightService
     def fetch(key, default_or_block = nil)
       self[key] ||= super(key, default_or_block)
     end
+
+    def inspect
+      "#{self.class}(#{self}, " \
+      + "success: #{success?}, " \
+      + "message: #{check_nil(message)}, " \
+      + "error_code: #{check_nil(error_code)}, " \
+      + "skip_remaining: #{@skip_remaining}, " \
+      + "aliases: #{@aliases}" \
+      + ")"
+    end
+
+    private
+
+    def check_nil(value)
+      return 'nil' unless value
+      "'#{value}'"
+    end
   end
   # rubocop:enable ClassLength
 end

data/lib/light-service/orchestrator.rb

@@ -24,6 +24,8 @@ module LightService
 
       def reduce_until(condition_block, steps)
         lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
           loop do
             ctx = scoped_reduction(ctx, steps)
             break if condition_block.call(ctx) || ctx.failure?
@@ -35,6 +37,8 @@ module LightService
 
       def reduce_if(condition_block, steps)
         lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
           ctx = scoped_reduction(ctx, steps) if condition_block.call(ctx)
           ctx
         end
@@ -42,6 +46,8 @@ module LightService
 
       def execute(code_block)
         lambda do |ctx|
+          return ctx if ctx.stop_processing?
+
           ctx = code_block.call(ctx)
           ctx
         end
@@ -49,6 +55,8 @@ module LightService
 
       def iterate(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|
@@ -60,6 +68,24 @@ module LightService
         end
       end
 
+      def with_callback(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|
+            reduce(steps, context)
+          end
+
+          ctx = action.execute(ctx)
+          ctx[:callback] = previous_callback
+
+          ctx
+        end
+      end
+
       private
 
       def scoped_reduction(ctx, steps)

data/lib/light-service/version.rb

@@ -1,3 +1,3 @@
 module LightService
-  VERSION = "0.8.1".freeze
+  VERSION = "0.8.2".freeze
 end

data/light-service.gemspec

@@ -20,6 +20,6 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency("rspec", "~> 3.0")
   gem.add_development_dependency("simplecov", "~> 0.14.1")
-  gem.add_development_dependency("rubocop", "~> 0.42")
+  gem.add_development_dependency("rubocop", "0.46")
   gem.add_development_dependency("pry", "~> 0.10")
 end

data/spec/acceptance/fail_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+RSpec.describe "fail! returns immediately from executed block" do
+  class FailAction
+    extend LightService::Action
+    promises :one, :two
+
+    executed do |ctx|
+      ctx.one = 1
+      # Have to set it in Context
+      ctx.two = nil
+
+      ctx.fail_and_return!('Something went wrong')
+      ctx.two = 2
+    end
+  end
+
+  it "returns immediately from executed block" do
+    result = FailAction.execute
+
+    expect(result).to be_failure
+    expect(result.two).to be_nil
+  end
+end

data/spec/acceptance/orchestrator/context_failure_and_skipping_spec.rb

@@ -14,11 +14,11 @@ describe LightService::Orchestrator do
 
     def self.run_skip_after
       with(:number => 1).reduce([
-                                  TestDoubles::SkipAllAction,
+                                  TestDoubles::AddOneAction,
                                   reduce_until(->(ctx) { ctx.number == 3 }, [
-                                                 TestDoubles::AddOneAction,
-                                                 TestDoubles::SkipAllAction
+                                                 TestDoubles::AddOneAction
                                                ]),
+                                  TestDoubles::SkipAllAction,
                                   TestDoubles::AddOneAction
                                 ])
     end
@@ -33,18 +33,18 @@ describe LightService::Orchestrator do
     end
   end
 
-  it 'does not skip nested contexts' do
+  it 'skips all the rest of the actions' do
     result = TestSkipState.run_skip_before
 
     expect(result).to be_success
-    expect(result.number).to eq(3)
+    expect(result[:number]).to eq(1)
   end
 
-  it 'does not skip after a nested context' do
+  it 'skips after an action in nested context' do
     result = TestSkipState.run_skip_after
 
     expect(result).to be_success
-    expect(result.number).to eq(4)
+    expect(result[:number]).to eq(3)
   end
 
   it 'respects failure across all nestings' do

data/spec/acceptance/orchestrator/execute_spec.rb

@@ -19,6 +19,8 @@ describe LightService::Orchestrator do
     end
   end
 
+  let(:empty_context) { LightService::Context.make }
+
   it 'calls the lambda in the execute block using the context' do
     result = TestExecute.run(:number => 0)
 
@@ -26,4 +28,19 @@ describe LightService::Orchestrator do
     expect(result.number).to eq(3)
     expect(result[:something]).to eq('hello')
   end
+
+  it 'will not execute a failed context' do
+    empty_context.fail!('Something bad happened')
+
+    result = TestExecute.run(empty_context)
+
+    expect(result).to be_failure
+  end
+
+  it 'does not execute over a skipped context' do
+    empty_context.skip_remaining!('No more needed')
+
+    result = TestExecute.run(empty_context)
+    expect(result).to be_success
+  end
 end

data/spec/acceptance/orchestrator/iterate_spec.rb

@@ -20,6 +20,8 @@ describe LightService::Orchestrator do
     end
   end
 
+  let(:empty_context) { LightService::Context.make }
+
   it 'reduces each item of a collection and singularizes the collection key' do
     result = TestIterate.run(:numbers => [1, 2, 3, 4])
 
@@ -33,4 +35,19 @@ describe LightService::Orchestrator do
     expect(result).to be_success
     expect(result.number).to eq(5)
   end
+
+  it 'will not iterate over a failed context' do
+    empty_context.fail!('Something bad happened')
+
+    result = TestIterate.run(empty_context)
+
+    expect(result).to be_failure
+  end
+
+  it 'does not iterate over a skipped context' do
+    empty_context.skip_remaining!('No more needed')
+
+    result = TestIterate.run(empty_context)
+    expect(result).to be_success
+  end
 end

data/spec/acceptance/orchestrator/reduce_if_spec.rb

@@ -18,17 +18,34 @@ describe LightService::Orchestrator do
     end
   end
 
+  let(:empty_context) { LightService::Context.make }
+
   it 'reduces if the block evaluates to true' do
     result = TestReduceIf.run(:number => 0)
 
     expect(result).to be_success
-    expect(result.number).to eq(2)
+    expect(result[:number]).to eq(2)
   end
 
   it 'does not reduce if the block evaluates to false' do
     result = TestReduceIf.run(:number => 2)
 
     expect(result).to be_success
-    expect(result.number).to eq(3)
+    expect(result[:number]).to eq(3)
+  end
+
+  it 'will not reduce over a failed context' do
+    empty_context.fail!('Something bad happened')
+
+    result = TestReduceIf.run(empty_context)
+
+    expect(result).to be_failure
+  end
+
+  it 'does not reduce over a skipped context' do
+    empty_context.skip_remaining!('No more needed')
+
+    result = TestReduceIf.run(empty_context)
+    expect(result).to be_success
   end
 end

data/spec/acceptance/orchestrator/reduce_until_spec.rb

@@ -5,8 +5,8 @@ RSpec.describe LightService::Orchestrator do
   class TestReduceUntil
     extend LightService::Orchestrator
 
-    def self.run
-      with(:number => 1).reduce(steps)
+    def self.run(context)
+      with(context).reduce(steps)
     end
 
     def self.steps
@@ -17,10 +17,27 @@ RSpec.describe LightService::Orchestrator do
     end
   end
 
+  let(:empty_context) { LightService::Context.make }
+
   it 'reduces until the block evaluates to true' do
-    result = TestReduceUntil.run
+    context = { :number => 1 }
+    result = TestReduceUntil.run(context)
 
     expect(result).to be_success
     expect(result.number).to eq(3)
   end
+
+  it 'does not execute on failed context' do
+    empty_context.fail!('Something bad happened')
+
+    result = TestReduceUntil.run(empty_context)
+    expect(result).to be_failure
+  end
+
+  it 'does not execute a skipped context' do
+    empty_context.skip_remaining!('No more needed')
+
+    result = TestReduceUntil.run(empty_context)
+    expect(result).to be_success
+  end
 end

data/spec/acceptance/orchestrator/with_callback_spec.rb

@@ -0,0 +1,169 @@
+require 'spec_helper'
+require 'test_doubles'
+
+describe LightService::Orchestrator do
+  class TestWithCallback
+    extend LightService::Orchestrator
+
+    def self.run(context = {})
+      with(context).reduce(steps)
+    end
+
+    def self.steps
+      [
+        SetUpContextAction,
+        with_callback(IterateCollectionAction,
+                      [IncrementCountAction,
+                       AddToTotalAction])
+      ]
+    end
+  end
+
+  class SetUpContextAction
+    extend LightService::Action
+    promises :numbers, :counter, :total
+
+    executed do |ctx|
+      ctx.numbers = [1, 2, 3]
+      ctx.counter = 0
+      ctx.total = 0
+    end
+  end
+
+  class IterateCollectionAction
+    extend LightService::Action
+    expects :numbers, :callback
+    promises :number
+
+    executed do |ctx|
+      ctx.numbers.each do |number|
+        ctx.number = number
+        ctx.callback.call(ctx)
+      end
+    end
+  end
+
+  class IncrementCountAction
+    extend LightService::Action
+    expects :counter
+
+    executed do |ctx|
+      ctx.counter = ctx.counter + 1
+    end
+  end
+
+  class AddToTotalAction
+    extend LightService::Action
+    expects :number, :total
+
+    executed do |ctx|
+      ctx.total += ctx.number
+    end
+  end
+
+  describe 'a simple case with a single callback' do
+    it 'calls the actions defined with callback' do
+      result = TestWithCallback.run
+
+      expect(result.counter).to eq(3)
+      expect(result.total).to eq(6)
+    end
+  end
+
+  describe 'a more complex example with nested callbacks' do
+    class TestWithNestedCallback
+      extend LightService::Orchestrator
+
+      def self.run(context = {})
+        with(context).reduce(steps)
+      end
+
+      def self.steps
+        [
+          SetUpNestedContextAction,
+          with_callback(IterateOuterCollectionAction,
+                        [IncrementOuterCountAction,
+                         with_callback(IterateCollectionAction,
+                                       [IncrementCountAction,
+                                        AddToTotalAction])])
+        ]
+      end
+    end
+
+    class SetUpNestedContextAction
+      extend LightService::Action
+      promises :outer_numbers, :outer_counter,
+               :numbers, :counter, :total
+
+      executed do |ctx|
+        ctx.outer_numbers = [12, 17]
+        ctx.outer_counter = 0
+        ctx.numbers = [1, 2, 3]
+        ctx.counter = 0
+        ctx.total = 0
+      end
+    end
+
+    class IterateOuterCollectionAction
+      extend LightService::Action
+      expects :outer_numbers, :callback
+      promises :outer_number
+
+      executed do |ctx|
+        ctx.outer_numbers.each do |outer_number|
+          ctx.outer_number = outer_number
+          ctx.callback.call(ctx)
+        end
+      end
+    end
+
+    class IncrementOuterCountAction
+      extend LightService::Action
+      expects :outer_counter
+
+      executed do |ctx|
+        ctx.outer_counter = ctx.outer_counter + 1
+      end
+    end
+
+    it 'calls both the action and the nested callbacks' do
+      result = TestWithNestedCallback.run
+
+      expect(result.outer_counter).to eq(2)
+      # Counts and total are the duplicates of
+      # what you'll see in the simple spec,
+      # as the internal callback logic is called
+      # twice due to 2 items in the outer_numbers
+      # collection.
+      expect(result.counter).to eq(6)
+      expect(result.total).to eq(12)
+    end
+  end
+
+  describe 'with failed or skipped context' do
+    class TestWithFailureCallback
+      extend LightService::Orchestrator
+
+      def self.run(context = {})
+        with(context).reduce(steps)
+      end
+
+      def self.steps
+        [
+          SetUpContextAction,
+          with_callback(IterateCollectionAction,
+                        [IncrementCountAction,
+                         TestDoubles::FailureAction])
+        ]
+      end
+    end
+
+    it 'will not process the routine' do
+      result = TestWithFailureCallback.run
+
+      expect(result).to be_failure
+      expect(result.counter).to eq(1)
+      expect(result.total).to eq(0)
+    end
+  end
+end

data/spec/context/inspect_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+require 'test_doubles'
+
+RSpec.describe LightService::Context do
+  subject(:context) { LightService::Context.make }
+
+  describe 'to_s' do
+    it 'prints the context hash' do
+      expect(context.to_s).to eq('{}')
+    end
+  end
+
+  describe '#inspect' do
+    it 'inspects the hash with all the fields' do
+      inspected_context =
+        'LightService::Context({}, ' \
+        + 'success: true, ' \
+        + 'message: \'\', ' \
+        + 'error_code: nil, ' \
+        + 'skip_remaining: false, ' \
+        + 'aliases: {}' \
+        + ')'
+
+      expect(context.inspect).to eq(inspected_context)
+    end
+
+    it 'prints the error message' do
+      context.fail!('There was an error')
+
+      inspected_context =
+        'LightService::Context({}, ' \
+        + 'success: false, ' \
+        + 'message: \'There was an error\', ' \
+        + 'error_code: nil, ' \
+        + 'skip_remaining: false, ' \
+        + 'aliases: {}' \
+        + ')'
+
+      expect(context.inspect).to eq(inspected_context)
+    end
+
+    it 'prints skip_remaining' do
+      context.skip_remaining!('No need to process')
+
+      inspected_context =
+        'LightService::Context({}, ' \
+        + 'success: true, ' \
+        + 'message: \'No need to process\', ' \
+        + 'error_code: nil, ' \
+        + 'skip_remaining: true, ' \
+        + 'aliases: {}' \
+        + ')'
+
+      expect(context.inspect).to eq(inspected_context)
+    end
+  end
+end

data/spec/context_spec.rb

@@ -1,7 +1,7 @@
-require "spec_helper"
+require 'spec_helper'
 require 'test_doubles'
 
-describe LightService::Context do
+RSpec.describe LightService::Context do
   let(:context) { LightService::Context.make }
 
   describe "can be made" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: light-service
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Attila Domokos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-28 00:00:00.000000000 Z
+date: 2017-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -56,16 +56,16 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '0.46'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '0.46'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -126,6 +126,7 @@ files:
 - resources/skip_actions.png
 - spec/acceptance/add_numbers_spec.rb
 - spec/acceptance/around_each_spec.rb
+- spec/acceptance/fail_spec.rb
 - spec/acceptance/include_warning_spec.rb
 - spec/acceptance/log_from_organizer_spec.rb
 - spec/acceptance/message_localization_spec.rb
@@ -136,6 +137,7 @@ files:
 - spec/acceptance/orchestrator/organizer_action_combination_spec.rb
 - spec/acceptance/orchestrator/reduce_if_spec.rb
 - spec/acceptance/orchestrator/reduce_until_spec.rb
+- spec/acceptance/orchestrator/with_callback_spec.rb
 - spec/acceptance/rollback_spec.rb
 - spec/acceptance/skip_all_warning_spec.rb
 - spec/acceptance/testing/context_factory_spec.rb
@@ -143,6 +145,7 @@ files:
 - spec/action_expects_and_promises_spec.rb
 - spec/action_promised_keys_spec.rb
 - spec/action_spec.rb
+- spec/context/inspect_spec.rb
 - spec/context_spec.rb
 - spec/localization_adapter_spec.rb
 - spec/organizer/with_reducer_spec.rb
@@ -186,6 +189,7 @@ summary: A service skeleton with an emphasis on simplicity
 test_files:
 - spec/acceptance/add_numbers_spec.rb
 - spec/acceptance/around_each_spec.rb
+- spec/acceptance/fail_spec.rb
 - spec/acceptance/include_warning_spec.rb
 - spec/acceptance/log_from_organizer_spec.rb
 - spec/acceptance/message_localization_spec.rb
@@ -196,6 +200,7 @@ test_files:
 - spec/acceptance/orchestrator/organizer_action_combination_spec.rb
 - spec/acceptance/orchestrator/reduce_if_spec.rb
 - spec/acceptance/orchestrator/reduce_until_spec.rb
+- spec/acceptance/orchestrator/with_callback_spec.rb
 - spec/acceptance/rollback_spec.rb
 - spec/acceptance/skip_all_warning_spec.rb
 - spec/acceptance/testing/context_factory_spec.rb
@@ -203,6 +208,7 @@ test_files:
 - spec/action_expects_and_promises_spec.rb
 - spec/action_promised_keys_spec.rb
 - spec/action_spec.rb
+- spec/context/inspect_spec.rb
 - spec/context_spec.rb
 - spec/localization_adapter_spec.rb
 - spec/organizer/with_reducer_spec.rb