light-service 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 481bcf8e63d44965c219dff04ab8889681ffb592
-  data.tar.gz: b34c8d452cc394a8608b8d1387c83eb49b3fc807
+  metadata.gz: 713b37be5e541d42ebed24537f656289ed6d5ab6
+  data.tar.gz: dbf4a703cbfa397562d59a1f61ca8c08136a7111
 SHA512:
-  metadata.gz: 40c7652d305c27fe6f07bcd21c8b4478e534f4f0efa5298a9cb076333fcab02b76ee6d6f841e76ed3eaf38103525fe598f697c9fb64c0b3cab60e1606568fa8c
-  data.tar.gz: 824c92c2b6117867bb9e1a40d087249838622872162be5f28d6b7f1197b98787b6cf4bb6e4dc2bee9e10c53d88a288c08b95d15ca333b2e45e06901245cc7739
+  metadata.gz: 5040578df5d4f0bbce8f530a31f67fe1baacdd12658d3c20b4e936dc0f53511efe666858a491134d604ed246ff76d119c09cebfbbf802bb4ce95aeaad69dff0f
+  data.tar.gz: aa4adc93839de21f98b0e275da0d28e0dfbc5fe1f1114ac2bdb14b267bbff6208a19754357ed5c713861cba542229ad0ce0ac9033469b5f41c14ee887f49bdfe

data/.travis.yml

@@ -1,5 +1,5 @@
 language: ruby
 rvm:
-  - "1.9.2"
+  - "1.9.3"
 # uncomment this line if your project needs to run something other than `rake`:
 script: bundle exec rspec spec

data/README.md

@@ -49,11 +49,11 @@ The order of these tasks matters: you can't calculate the order tax without the
 Wouldn't it be nice to see this instead?
 
 ```ruby
-[
-  LooksUpTaxPercentage,
-  CalculatesOrderTax,
-  ChecksFreeShipping
-]
+(
+  LooksUpTaxPercentageAction,
+  CalculatesOrderTaxAction,
+  ChecksFreeShippingAction
+)
 ```
 
 This block of code should tell you the "story" of what's going on in this workflow.
@@ -69,30 +69,28 @@ class CalculatesTax
   include LightService::Organizer
 
   def self.for_order(order)
-    with(order: order).reduce \
-      [
+    with(:order => order).reduce(
         LooksUpTaxPercentageAction,
         CalculatesOrderTaxAction,
         ProvidesFreeShippingAction
-      ]
+      )
   end
 end
 
 class LooksUpTaxPercentageAction
   include LightService::Action
+  expects :order
+  promises :tax_percentage
 
   executed do |context|
-    order = context.fetch(:order)
-    tax_ranges = TaxRange.for_region(order.region)
+    tax_ranges = TaxRange.for_region(self.order.region)
+    self.tax_percentage = 0
 
     next context if object_is_nil?(tax_ranges, context, 'The tax ranges were not found')
 
-    order = context.fetch(:order)
-    tax_percentage = tax_ranges.for_total(order.total)
-
-    next context if object_is_nil?(tax_percentage, context, 'The tax percentage was not found')
+    self.tax_percentage = tax_ranges.for_total(self.order.total)
 
-    context[:tax_percentage] = tax_percentage
+    next context if object_is_nil?(self.tax_percentage, context, 'The tax percentage was not found')
   end
 
   def self.object_is_nil?(object, context, message)
@@ -103,16 +101,13 @@ class LooksUpTaxPercentageAction
 
     false
   end
-
 end
 
 class CalculatesOrderTaxAction
   include ::LightService::Action
+  expects :order, :tax_percentage
 
   executed do |context|
-    order = context.fetch(:order)
-    tax_percentage = context.fetch(:tax_percentage)
-
     order.tax = (order.total * (tax_percentage/100)).round(2)
   end
 
@@ -120,10 +115,9 @@ end
 
 class ProvidesFreeShippingAction
   include LightService::Action
+  expects :order
 
   executed do |context|
-    order = context.fetch(:order)
-
     if order.total_with_tax > 200
       order.provide_free_shipping!
     end
@@ -152,6 +146,60 @@ 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.
 
+## Expects and Promises
+Let me introduce to you the `expects` and `promises` macros. Think of these as a rule set of inputs/outputs for the action.
+`expects` describes what keys it needs to execute and `promises` makes sure the keys are in the context after the
+action is reduced. If either of them are violated, a custom exception is thrown.
+
+This is how it's used:
+```ruby
+class FooAction
+  include LightService::Action
+  expects :baz
+  promises :bar
+
+  executed do |context|
+    baz = context.fetch :baz
+
+    bar = baz + 2
+    context[:bar] = bar
+  end
+end
+```
+
+The `expects` macro does a bit more for you: it pulls the value with the expected key from the context, and
+makes it available to you through a reader. You can refactor the action like this:
+
+```ruby
+class FooAction
+  include LightService::Action
+  expects :baz
+  promises :bar
+
+  executed do |context|
+    bar = self.baz + 2
+    context[:bar] = bar
+  end
+end
+```
+
+The `promises` macro will not only check if the context has the promised keys, it also sets it for you in the context if
+you use the accessor with the same name. The code above can be further simplified:
+
+```ruby
+class FooAction
+  include LightService::Action
+  expects :baz
+  promises :bar
+
+  executed do |context|
+    self.bar = self.baz + 2
+  end
+end
+```
+
+Take a look at [this spec](spec/action_expects_and_promises_spec.rb) to see the refactoring in action.
+
 ## Requirements
 
 This gem requires ruby 1.9.x
@@ -188,6 +236,9 @@ For further examples, please visit the project's [Wiki](https://github.com/adomo
 Huge thanks to the [contributors](https://github.com/adomokos/light-service/graphs/contributors)!
 
 ## Release Notes
+### 0.3.0
+* Adding the `expects` and `promises` macros - Read more about it in [this blog post](http://www.adomokos.com/2014/05/expects-and-promises-in-lightservice.html)
+
 ### 0.2.2
 * Adding the gem version icon to README
 * Actions can be invoked now [without arguments](https://github.com/adomokos/light-service/commit/244d5f03b9dbf61c97c1fdb865e6587f9aea177d), this makes it super easy to play with an action in the command line

data/lib/light-service.rb

@@ -1,5 +1,6 @@
 require "light-service/version"
 
 require 'light-service/context'
+require 'light-service/context_key_verifier'
 require 'light-service/action'
 require 'light-service/organizer'

data/lib/light-service/action.rb

@@ -6,26 +6,67 @@ module LightService
     end
 
     module Macros
+      def expects(*args)
+        @_expected_keys = args
+      end
+
+      def promises(*args)
+        @_promised_keys = args
+      end
+
       def executed
         define_singleton_method "execute" do |context = {}|
           action_context = create_action_context(context)
-          return action_context if action_context.failure? || action_context.skip_all?
+          return action_context if action_context.stop_processing?
+
+          ContextKeyVerifier.verify_expected_keys_are_in_context(action_context, @_expected_keys)
+
+          define_expectations_readers(context)
+          define_promises_accessors(context)
 
           yield(action_context)
 
-          action_context
+          set_promises_in_context(action_context)
+          ContextKeyVerifier.verify_promised_keys_are_in_context(action_context, @_promised_keys)
         end
       end
 
       private
 
       def create_action_context(context)
-        if context.respond_to? :failure?
+        if context.is_a? ::LightService::Context
           return context
         end
 
         LightService::Context.make(context)
       end
+
+      def define_expectations_readers(context)
+        context.keys.each do |key|
+          define_singleton_method key do
+            context.fetch(key)
+          end
+        end
+      end
+
+      def define_promises_accessors(context)
+        return unless @_promised_keys
+        @_promised_keys.each do |key|
+          instance_variable_set("@#{key}", VALUE_NOT_SET)
+          self.class.send(:attr_accessor, key)
+        end
+      end
+
+      def set_promises_in_context(context)
+        return unless @_promised_keys
+        @_promised_keys.each do |key|
+          value = instance_variable_get("@#{key}")
+          next if value == VALUE_NOT_SET
+          context[key] = value
+        end
+      end
+
+      VALUE_NOT_SET = "___value_was_not_set___"
     end
 
   end

data/lib/light-service/context.rb

@@ -70,5 +70,8 @@ module LightService
       @skip_all = true
     end
 
+    def stop_processing?
+      failure? || skip_all?
+    end
   end
 end

data/lib/light-service/context_key_verifier.rb

@@ -0,0 +1,37 @@
+module LightService
+  class ExpectedKeysNotInContextError < StandardError; end
+  class PromisedKeysNotInContextError < StandardError; end
+
+  class ContextKeyVerifier
+    class << self
+      def verify_expected_keys_are_in_context(context, expected_keys)
+        verify_keys_are_in_context(context, expected_keys) do |not_found_keys|
+          fail ExpectedKeysNotInContextError, "expected #{format_keys(not_found_keys)} to be in the context"
+        end
+      end
+
+      def verify_promised_keys_are_in_context(context, promised_keys)
+        verify_keys_are_in_context(context, promised_keys) do |not_found_keys|
+          fail PromisedKeysNotInContextError, "promised #{format_keys(not_found_keys)} to be in the context"
+        end
+      end
+
+      private
+
+      def verify_keys_are_in_context(context, keys)
+        keys ||= context.keys
+
+        not_found_keys = keys - context.keys
+        unless not_found_keys.empty?
+          yield not_found_keys
+        end
+
+        context
+      end
+
+      def format_keys(keys)
+        keys.map{|k| ":#{k}"}.join(', ')
+      end
+    end
+  end
+end

data/lib/light-service/version.rb

@@ -1,3 +1,3 @@
 module LightService
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/spec/acceptance/add_numbers_spec.rb

@@ -14,34 +14,40 @@ end
 
 class AddsOneAction
   include LightService::Action
+  expects :number
+  promises :number
 
   executed do |context|
-    number = context.fetch :number
+    number = self.number
     number += 1
 
-    context[:number] = number
+    self.number = number
   end
 end
 
 class AddsTwoAction
   include LightService::Action
+  expects :number
+  promises :number
 
   executed do |context|
-    number = context.fetch :number
+    number = self.number
     number += 2
 
-    context[:number] = number
+    self.number = number
   end
 end
 
 class AddsThreeAction
   include LightService::Action
+  expects :number
+  promises :number
 
   executed do |context|
-    number = context.fetch :number
+    number = self.number
     number += 3
 
-    context[:number] = number
+    self.number = number
   end
 end
 

data/spec/action_expected_keys_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+module LightService
+  describe ":expects macro" do
+    class DummyActionForKeysToExpect
+      include LightService::Action
+      expects :tea, :milk
+      promises :milk_tea
+
+      executed do |context|
+        context[:milk_tea] = "#{self.tea} - #{milk}"
+      end
+    end
+
+    context "when expected keys are in the context" do
+      it "can access the keys as class methods" do
+        resulting_context = DummyActionForKeysToExpect.execute(
+          :tea => "black",
+          :milk => "full cream",
+          :something => "else"
+        )
+        expect(resulting_context[:milk_tea]).to eq("black - full cream")
+      end
+    end
+
+    context "when expected keys are not in the context" do
+      it "raises an error" do
+        exception_error_text = "expected :milk to be in the context"
+        expect {
+          DummyActionForKeysToExpect.execute(:tea => "black")
+        }.to raise_error(ExpectedKeysNotInContextError, exception_error_text)
+      end
+    end
+  end
+end

data/spec/action_expects_and_promises_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+
+module LightService
+  describe ":expects and :promises macros" do
+    describe "actions are backward compatible" do
+      class FooAction
+        include LightService::Action
+
+        executed do |context|
+          baz = context.fetch :baz
+
+          bar = baz + 2
+          context[:bar] = bar
+        end
+      end
+      it "works without expects and promises" do
+        result = FooAction.execute(:baz => 3)
+        expect(result).to be_success
+        expect(result[:bar]).to eq(5)
+      end
+    end
+
+    context "when expected keys are not in context" do
+      class FooNoExpectedKeyAction
+        include LightService::Action
+        expects :baz
+
+        executed do |context|
+          baz = context.fetch :baz
+
+          bar = baz + 2
+          context[:bar] = bar
+        end
+      end
+      it "throws an ExpectedKeysNotInContextError" do
+        # FooAction invoked with nothing in the context
+        expect { FooNoExpectedKeyAction.execute }.to \
+          raise_error(ExpectedKeysNotInContextError)
+      end
+    end
+
+    describe "expected keys" do
+      class FooWithReaderAction
+        include LightService::Action
+        expects :baz
+
+        executed do |context|
+          # Notice how I use `self.baz` here
+          bar = self.baz + 2
+          context[:bar] = bar
+        end
+      end
+      it "can be accessed through a reader" do
+        result = FooWithReaderAction.execute(:baz => 3)
+        expect(result).to be_success
+        expect(result[:bar]).to eq(5)
+      end
+    end
+
+    context "when promised keys are not in context" do
+      class FooNoPromisedKeyAction
+        include LightService::Action
+        expects :baz
+        promises :bar
+
+        executed do |context|
+          # I am not adding anything to the context
+        end
+      end
+      it "throws a PromisedKeysNotInContextError" do
+        # FooAction invoked with nothing placed in the context
+        expect { FooNoPromisedKeyAction.execute(:baz => 3) }.to \
+          raise_error(PromisedKeysNotInContextError)
+      end
+    end
+
+    describe "promised keys" do
+      class FooWithExpectsAndPromisesAction
+        include LightService::Action
+        expects :baz
+        promises :bar
+
+        executed do |context|
+          # Notice how I use `self.bar` here
+          self.bar = self.baz + 2
+        end
+      end
+      it "puts the value through the accessor into the context" do
+        result = FooWithExpectsAndPromisesAction.execute(:baz => 3)
+        expect(result).to be_success
+        expect(result[:bar]).to eq(5)
+      end
+    end
+  end
+end

data/spec/action_promised_keys_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+module LightService
+  describe ":promises macro" do
+    class DummyActionForKeysToPromise
+      include LightService::Action
+      expects :tea, :milk
+      promises :milk_tea, :something_else
+
+      executed do |context|
+        context[:some_tea] = "#{self.tea} - #{self.milk}"
+      end
+    end
+
+    context "when the promised key is not in the context" do
+      it "raises an ArgumentError" do
+        exception_error_text = "promised :milk_tea, :something_else to be in the context"
+        expect {
+          DummyActionForKeysToPromise.execute(:tea => "black", :milk => "full cream")
+        }.to raise_error(PromisedKeysNotInContextError, exception_error_text)
+      end
+    end
+
+    context "when the promised key is in the context" do
+      class DummyActionSetsItemInContext
+        include LightService::Action
+        expects :tea, :milk
+        promises :milk_tea
+
+        executed do |context|
+          self.milk_tea = "#{self.tea} - #{self.milk}"
+          self.milk_tea += " hello"
+        end
+      end
+      it "sets in the context if it was set with not nil" do
+        result_context = DummyActionSetsItemInContext.execute(:tea => "black",
+                                                              :milk => "full cream")
+        expect(result_context).to be_success
+        expect(result_context[:milk_tea]).to eq("black - full cream hello")
+      end
+
+      class DummyActionNilNotSetInContext
+        include LightService::Action
+        expects :tea, :milk
+        promises :milk_tea
+
+        executed do |context|
+          self.milk_tea = nil
+        end
+      end
+      it "sets in the context if it was set with nil" do
+        result_context = DummyActionNilNotSetInContext.execute(:tea => "black",
+                                                              :milk => "full cream")
+        expect(result_context).to be_success
+        expect(result_context[:milk_tea]).to be_nil
+      end
+
+    end
+  end
+end

data/spec/action_spec.rb

@@ -18,6 +18,11 @@ module LightService
       end
     end
 
+    class PromisingAction
+      include LightService::Action
+      promises :milk_tea
+    end
+
     let(:context) { ::LightService::Context.make }
 
     context "when the action context has failure" do

data/spec/context_spec.rb

@@ -79,5 +79,19 @@ module LightService
       expect(context).to be_skip_all
     end
 
+    context "stopping additional processing in an action" do
+      let(:context) { Context.make }
+
+      it "flags processing to stop on failure" do
+        context.fail!("on purpose")
+        expect(context.stop_processing?).to be_true
+      end
+
+      it "flags processing to stop when remaining actions should be skipped" do
+        context.skip_all!
+        expect(context.stop_processing?).to be_true
+      end
+    end
+
   end
 end

data/spec/sample/tax/calculates_order_tax_action.rb

@@ -1,11 +1,8 @@
 class CalculatesOrderTaxAction
   include ::LightService::Action
+  expects :order, :tax_percentage
 
   executed do |context|
-    order = context.fetch(:order)
-    tax_percentage = context.fetch(:tax_percentage)
-
     order.tax = (order.total * (tax_percentage/100)).round(2)
   end
-
 end

data/spec/sample/tax/calculates_tax.rb

@@ -2,11 +2,10 @@ class CalculatesTax
   include LightService::Organizer
 
   def self.for_order(order)
-    with(order: order).reduce \
-      [
+    with(:order => order).reduce(
         LooksUpTaxPercentageAction,
         CalculatesOrderTaxAction,
         ProvidesFreeShippingAction
-      ]
+    )
   end
 end

data/spec/sample/tax/looks_up_tax_percentage_action.rb

@@ -1,18 +1,17 @@
 class LooksUpTaxPercentageAction
   include LightService::Action
+  expects :order
+  promises :tax_percentage
 
   executed do |context|
-    order = context.fetch(:order)
-    tax_ranges = TaxRange.for_region(order.region)
+    tax_ranges = TaxRange.for_region(self.order.region)
+    self.tax_percentage = 0
 
     next context if object_is_nil?(tax_ranges, context, 'The tax ranges were not found')
 
-    order = context.fetch(:order)
-    tax_percentage = tax_ranges.for_total(order.total)
+    self.tax_percentage = tax_ranges.for_total(self.order.total)
 
-    next context if object_is_nil?(tax_percentage, context, 'The tax percentage was not found')
-
-    context[:tax_percentage] = tax_percentage
+    next context if object_is_nil?(self.tax_percentage, context, 'The tax percentage was not found')
   end
 
   def self.object_is_nil?(object, context, message)
@@ -23,5 +22,4 @@ class LooksUpTaxPercentageAction
 
     false
   end
-
 end

data/spec/sample/tax/provides_free_shipping_action.rb

@@ -1,9 +1,8 @@
 class ProvidesFreeShippingAction
   include LightService::Action
+  expects :order
 
   executed do |context|
-    order = context.fetch(:order)
-
     if order.total_with_tax > 200
       order.provide_free_shipping!
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: light-service
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Attila Domokos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-12 00:00:00.000000000 Z
+date: 2014-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -69,18 +69,22 @@ files:
 - lib/light-service.rb
 - lib/light-service/action.rb
 - lib/light-service/context.rb
+- lib/light-service/context_key_verifier.rb
 - lib/light-service/organizer.rb
 - lib/light-service/version.rb
 - light-service.gemspec
 - resources/light-service.png
 - resources/organizer_and_actions.png
 - spec/acceptance/add_numbers_spec.rb
+- spec/action_expected_keys_spec.rb
+- spec/action_expects_and_promises_spec.rb
+- spec/action_promised_keys_spec.rb
 - spec/action_spec.rb
 - spec/context_spec.rb
 - spec/organizer_spec.rb
 - spec/sample/calculates_order_tax_action_spec.rb
 - spec/sample/calculates_tax_spec.rb
-- spec/sample/looks_up_tax_percentage_action.rb
+- spec/sample/looks_up_tax_percentage_action_spec.rb
 - spec/sample/provides_free_shipping_action_spec.rb
 - spec/sample/tax/calculates_order_tax_action.rb
 - spec/sample/tax/calculates_tax.rb
@@ -113,12 +117,15 @@ specification_version: 4
 summary: A service skeleton with an emphasis on simplicity
 test_files:
 - spec/acceptance/add_numbers_spec.rb
+- spec/action_expected_keys_spec.rb
+- spec/action_expects_and_promises_spec.rb
+- spec/action_promised_keys_spec.rb
 - spec/action_spec.rb
 - spec/context_spec.rb
 - spec/organizer_spec.rb
 - spec/sample/calculates_order_tax_action_spec.rb
 - spec/sample/calculates_tax_spec.rb
-- spec/sample/looks_up_tax_percentage_action.rb
+- spec/sample/looks_up_tax_percentage_action_spec.rb
 - spec/sample/provides_free_shipping_action_spec.rb
 - spec/sample/tax/calculates_order_tax_action.rb
 - spec/sample/tax/calculates_tax.rb