tzu 0.1.0.0 → 0.1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9fc0ed30a4b98b00a486d4fa819753e2c3903975
-  data.tar.gz: 79ec5b04b569d4463d0d7f4c88e9b5271476fed3
+  metadata.gz: b65373fa789405d5d165a29c71bd15b3a227450b
+  data.tar.gz: e7a9845bc66eba286135a9e7cbb64b9c197fa409
 SHA512:
-  metadata.gz: 2918e22b6a49c4d9d878413621fa0d1456f369a41fe84adafc0fdcbc2d9996caaf531e42a102cb11fc1b1a6d07d8ec311dc3c6b0904cfbcc792dd21792824a0f
-  data.tar.gz: b3007e68797f9b89bfa75682eda9ceab964598e548e404c8e23039db2ee9e563e81fb19f99b4a47ffa3994114caa0f1afa36533e881230db6de7273d167ee656
+  metadata.gz: a9a239244309bd5eae81848753bbdcdad5b22aac74b070ff73cb4ea843be47c1715a19758e06bcf6ed0025066423c2f6cace651b1f84f4f8b02888e767a09044
+  data.tar.gz: 14b6723526bfa3dbe24a36d5dc65caa122cbc5f2e12eb2c7891aacedb6d89542736809ecca93044da744e2296e8ff190995695b05a49d042e15e4f883756815d

data/README.md

@@ -1,5 +1,36 @@
 # Tzu
 
+Tzu provides a simple interface for writing classes that encapsulate a single command.
+
+**Commands should:**
+
+- Do exactly one thing (Single Responsibility Priciple)
+- Be self-documenting
+- Be testable
+- Be easy to mock and stub
+
+**Benefits**
+
+- File and class names say what your code *actually does*, making onboarding and debugging a much simpler process.
+- Minimize the instances of persistence logic throughout the application
+- The Rails 'where do I put...?' question is solved. Models, Controllers, Workers and even Rake Tasks become slim.
+- Maintain all of the benefits of Object Oriented programming while executing a procedural action, or Sequence of procedural actions.
+
+**Documentation**
+
+- [Usage](#usage)
+- [Validation](#validation)
+- [Passing Blocks](#passing-blocks)
+- [Hooks](#hooks)
+- [Request Objects](#request-objects)
+
+**Sequences**
+- [Configure](#configure)
+- [Execute](#execute)
+- [Integrating Non Tzu Classes](#integrating-non-tzu-classes)
+- [Hooks for Sequences](#hooks-for-sequences)
+- [Mocking and Stubbing](#mocking-and-stubbing)
+
 ## Usage
 
 Tzu commands must include Tzu and implement a `#call` method.
@@ -79,7 +110,11 @@ outcome = MyRescueCommand.run!(params_that_cause_error)
 
 Note that if you pass a string to `invalid!`, it will coerce the result into a hash of the form:
 
-```
+```ruby
+# Invoking:
+invalid!('Error String')
+
+# Translates to:
 { errors: 'Error String' }
 ```
 
@@ -149,9 +184,7 @@ MyCommand.run(message: 'Hello!')
 #=> End Around 1
 ```
 
-
-
-## Request objects
+## Request Objects
 
 You can define a request object for your command using the `#request_object` method.
 
@@ -196,6 +229,7 @@ Virtus.model validates the types of your inputs, and also makes them available v
 class MyRequestObject
   include Virtus.model
   include ActiveModel::Validations
+
   validates :name, :age, presence: :true
 
   attribute :name, String
@@ -225,7 +259,9 @@ outcome.type? #=> :validation
 outcome.result #=> {:age=>["can't be blank"]}
 ```
 
-# Configure a sequence of Tzu commands
+# Execute Commands in Sequence
+
+## Configure
 
 Tzu provides a declarative way of encapsulating sequential command execution.
 
@@ -249,7 +285,7 @@ class MakeMeSoundImportant
 end
 ```
 
-The Tzu::Sequence provides a DSL for executing them in sequence:
+Tzu::Sequence provides a DSL for executing them in sequence:
 
 ```ruby
 class ProclaimMyImportance
@@ -276,7 +312,7 @@ Each command to be executed is defined as the first argument of `step`.
 The `receives` method inside the `step` block allows you to mutate the parameters being passed into the command.
 It is passed both the original parameters and a hash containing the results of prior commands.
 
-By default, the keys of the `prior_results` hash are underscored/symbolized command names.
+By default, the keys of the `prior_results` hash are demodulized/underscored/symbolized command names.
 You can define your own keys using the `as` method.
 
 ```ruby
@@ -288,9 +324,15 @@ step SayMyName do
 end
 ```
 
-# Executing the sequence
+If you don't need to mutate the parameters for the command, simply omit `receives`.
+
+```ruby
+step SayMyName
+```
 
-By default, Sequences return the result of the final command within an Outcome object,
+## Execute
+
+By default, Sequences return the result of the final command.
 
 ```ruby
 outcome = ProclaimMyImportance.run(name: 'Jessica', country: 'Azerbaijan')
@@ -363,7 +405,95 @@ outcome.result
 #=> { name: 'Jessica', original_message: 'Hello, Jessica', message: 'BULLETIN: Hello, Jessica! You are the most important citizen of Azerbaijan!' }
 ```
 
-# Hooks for Sequences
+## Integrating Non Tzu Classes
+
+Sometimes there is a need to combine non-Tzu classes with Tzu classes in a sequence.
+
+As an example, let's say I wanted to query a record, update it, and pass the updated record to a Tzu command.
+To do this, I'll use the [Get](https://github.com/onfido/get) and [Tradesman](https://github.com/onfido/tradesman/) libraries.
+
+When invoked on its own, Get looks like this:
+```ruby
+Get::UserByName.run(name)
+```
+
+Tradesman Update looks like this:
+```ruby
+Tradesman::UpdateUser.go(user_id, update_params)
+```
+
+The integration of Get into `Tzu::Sequence` is easy, as it only expects one parameter, and it's invoked with `#run`.
+Tradesman is more complicated; it expects two parameters - a User ID and a hash to update that record with - and it's invoked with `#go`.
+
+Tradesman offers the `invoke_with` and `receives_many` arguments to deal with these differences.
+
+`invoke_with` is self-explanatory, and defaults to `#run`.
+
+The `receives_many` block must return an array, which will be passed as a splat to the `invoke_with` method.
+```ruby
+class NonTzuSequence
+  include Tzu::Sequence
+
+  step Get::UserByName do
+    receives do |params|
+      params[:name]
+    end
+  end
+
+  step Tradesman::UpdateUser do
+    invoke_with :go
+
+    receives_many do |params, prior_results|
+      [
+        prior_results[:user_by_name].id,
+        params[:update_params]
+      ]
+    end
+  end
+
+  step SayMyName do
+    receives do |params, prior_results|
+      prior_results[:update_user].name
+    end
+  end
+end
+
+outcome = NonTzuSequence.run(name: 'Blake', update_params: { name: 'Morgan' })
+outcome.result #=> 'Hello, Morgan'
+```
+
+You can pass multiple parameters to `Tzu::Sequence` instead of a parameters hash, just make sure you add the correct amount of arguments to your `receives` and `receives_many` blocks.
+
+```ruby
+class NonTzuSequence
+  include Tzu::Sequence
+
+  step Get::UserByName do
+    receives do |name, update_params|
+      name
+    end
+  end
+
+  step Tradesman::UpdateUser do
+    invoke_with :go
+
+    receives_many do |name, update_params, prior_results|
+      [prior_results[:user_by_name].id, update_params]
+    end
+  end
+
+  step SayMyName do
+    receives do |name, update_params, prior_results|
+      prior_results[:update_user].name
+    end
+  end
+end
+
+outcome = NonTzuSequence.run('Blake', { name: 'Morgan' })
+outcome.result #=> 'Hello, Morgan'
+```
+
+## Hooks for Sequences
 
 Tzu sequences have the same `before`, `after`, and `around` hooks available in Tzu commands.
 This is particularly useful for wrapping multiple commands in a transaction.
@@ -394,3 +524,7 @@ class ProclaimMyImportance
   end
 end
 ```
+
+## Mocking and Stubbing
+
+Tzu has a specialized (and well-documented) gem for mocking/stubbing, [TzuMock](https://github.com/onfido/tzu_mock).

data/lib/tzu/errors.rb

@@ -0,0 +1,4 @@
+module Tzu
+  class InvalidSequence < StandardError
+  end
+end

data/lib/tzu/hooks.rb

@@ -37,12 +37,12 @@ module Tzu
       end
     end
 
-    def with_hooks(params, &block)
+    def with_hooks(*params, &block)
       result = nil
       run_around_hooks do
-        run_before_hooks(params)
-        result = yield(params)
-        run_after_hooks(params)
+        run_before_hooks(*params)
+        result = yield(*params)
+        run_after_hooks(*params)
       end
       result
     end

data/lib/tzu/run_methods.rb

@@ -25,8 +25,8 @@ module Tzu
       end
     end
 
-    def method_missing(method, *args, &block)
-      @request_klass = args.first if method == :request_object
+    def request_object(klass)
+      @request_klass = klass
     end
   end
 end

data/lib/tzu/sequence.rb

@@ -7,13 +7,8 @@ module Tzu
         class << self
           attr_reader :steps, :result_block
 
-          def run(params)
-            new(params).run
-          end
-
-          def method_missing(method, *args, &block)
-            return add_step(args.first, &block) if method == :step
-            super
+          def run(*params)
+            new(*params).run
           end
 
           def type
@@ -25,19 +20,20 @@ module Tzu
             @type = type
           end
 
-          def add_step(klass, &block)
+          def step(klass, &block)
             @steps = [] unless @steps
 
             step = Step.new(klass)
-            step.instance_eval(&block)
+            step.instance_eval(&block) if block
 
             @steps << step
           end
         end
 
-        def initialize(params)
+        def initialize(*params)
           @params = params
           @last_outcome = nil
+          @prior_results = {}
         end
 
         def run
@@ -50,15 +46,25 @@ module Tzu
         def sequence_results
           with_hooks(@params) do |params|
             self.class.steps.reduce({}) do |prior_results, step|
-              @last_outcome = step.run(params, prior_results)
-              break if @last_outcome.failure?
-              prior_results.merge!(step.name => @last_outcome.result)
+              @last_outcome = step.run(*params, prior_results)
+              break if last_outcome_is_failure?
+              merge_last_outcome_into_prior_results(step, prior_results)
             end
           end
         end
 
         private
 
+        def last_outcome_is_failure?
+          return true if (@last_outcome.respond_to?(:failure?) && @last_outcome.failure?)
+          false
+        end
+
+        def merge_last_outcome_into_prior_results(step, prior_results)
+          result = @last_outcome.respond_to?(:result) ? @last_outcome.result : @last_outcome
+          prior_results.merge(step.name => result)
+        end
+
         def mutated_result(results)
           Outcome.new(true, instance_exec(@params, results, &self.class.result_block))
         end

data/lib/tzu/step.rb

@@ -1,34 +1,64 @@
 module Tzu
   class Step
+    DOUBLE_MUTATOR = 'You cannot define both receives and receives_many'
+
     String.send(:include, ::Tzu::CoreExtensions::String)
-    attr_reader :klass, :param_mutator
+    attr_reader :klass, :single_mutator, :splat_mutator
 
     def initialize(klass)
       @klass = klass
+      @invoke_method = :run
     end
 
-    def run(params, prior_results)
-      command_params = process(params, prior_results)
-      @klass.run(command_params)
+    def run(*params, prior_results)
+      # Forward parameters as splat if no mutators are defined
+      return @klass.send(@invoke_method, *params) if mutator.nil?
+
+      command_params = process(*params, prior_results)
+
+      return @klass.send(@invoke_method, command_params) unless splat?
+      @klass.send(@invoke_method, *command_params)
     end
 
     def name
       return @name if @name && @name.is_a?(Symbol)
-      @klass.to_s.symbolize
+      @klass.to_s.split('::').last.symbolize
     end
 
     def receives(&block)
-      @param_mutator = block
+      double_mutator_error if splat?
+      @single_mutator = block
+    end
+
+    def receives_many(&block)
+      double_mutator_error if @single_mutator.present?
+      @splat_mutator = block
     end
 
     def as(name)
       @name = name
     end
 
+    def invoke_with(method)
+      @invoke_method = method
+    end
+
     private
 
-    def process(params, prior_results)
-      instance_exec(params, prior_results, &@param_mutator)
+    def double_mutator_error
+      raise Tzu::InvalidSequence.new(DOUBLE_MUTATOR)
+    end
+
+    def mutator
+      @single_mutator || @splat_mutator
+    end
+
+    def splat?
+      @splat_mutator.present?
+    end
+
+    def process(*params, prior_results)
+      instance_exec(*params, prior_results, &mutator)
     end
   end
 end

data/lib/tzu.rb

@@ -1,4 +1,5 @@
 require 'tzu/core_extensions/string'
+require 'tzu/errors'
 require 'tzu/run_methods'
 require 'tzu/failure'
 require 'tzu/hooks'

data/spec/sequence_spec.rb

@@ -16,7 +16,7 @@ class MakeMeSoundImportant
   end
 end
 
-class InvalidCommand
+class ThrowInvalidError
   include Tzu
 
   def call(params)
@@ -24,6 +24,14 @@ class InvalidCommand
   end
 end
 
+class ConstructGreeting
+  class << self
+    def go(greeting, name)
+      "#{greeting}, #{name}"
+    end
+  end
+end
+
 class MultiStepSimple
   include Tzu::Sequence
 
@@ -43,14 +51,33 @@ class MultiStepSimple
   end
 end
 
+class MultiStepNonTzu
+  include Tzu::Sequence
+
+  step ConstructGreeting do
+    as :say_my_name
+    invoke_with :go
+
+    receives_many do |greeting, name, country|
+      [greeting, name]
+    end
+  end
+
+  step MakeMeSoundImportant do
+    receives do |greeting, name, country, prior_results|
+      {
+        boring_message: prior_results[:say_my_name],
+        country: country
+      }
+    end
+  end
+end
+
 class MultiStepComplex
   include Tzu::Sequence
 
   step SayMyName do
     as :first_command
-    receives do |params|
-      { name: params[:name] }
-    end
   end
 
   step MakeMeSoundImportant do
@@ -71,9 +98,6 @@ class MultiStepProcessResults
 
   step SayMyName do
     as :first_command
-    receives do |params|
-      { name: params[:name] }
-    end
   end
 
   step MakeMeSoundImportant do
@@ -97,13 +121,9 @@ end
 class MultiStepInvalid
   include Tzu::Sequence
 
-  step SayMyName do
-    receives do |params|
-      { name: params[:name] }
-    end
-  end
+  step SayMyName
 
-  step InvalidCommand do
+  step ThrowInvalidError do
     receives do |params, prior_results|
       { answer: "#{params[:name]}!!! #{prior_results[:say_my_name]}" }
     end
@@ -128,16 +148,16 @@ describe Tzu::Sequence do
         steps.each { |step| expect(step.is_a? Tzu::Step).to be true }
       end
 
-      it 'passes the appropriate klass, name, and param_mutator to each step' do
+      it 'passes the appropriate klass, name, and param_mutators to each step' do
         say_my_name = steps.first
         expect(say_my_name.klass).to eq SayMyName
         expect(say_my_name.name).to eq :say_my_name
-        expect(say_my_name.param_mutator.is_a? Proc).to be true
+        expect(say_my_name.single_mutator.is_a? Proc).to be true
 
         make_me_sound_important = steps.last
         expect(make_me_sound_important.klass).to eq MakeMeSoundImportant
         expect(make_me_sound_important.name).to eq :make_me_sound_important
-        expect(make_me_sound_important.param_mutator.is_a? Proc).to be true
+        expect(make_me_sound_important.single_mutator.is_a? Proc).to be true
       end
     end
 
@@ -148,16 +168,15 @@ describe Tzu::Sequence do
         steps.each { |step| expect(step.is_a? Tzu::Step).to be true }
       end
 
-      it 'passes the appropriate klass, name, and param_mutator to each step' do
+      it 'passes the appropriate klass, name, and param_mutators to each step' do
         say_my_name = steps.first
         expect(say_my_name.klass).to eq SayMyName
         expect(say_my_name.name).to eq :first_command
-        expect(say_my_name.param_mutator.is_a? Proc).to be true
 
         make_me_sound_important = steps.last
         expect(make_me_sound_important.klass).to eq MakeMeSoundImportant
         expect(make_me_sound_important.name).to eq :final_command
-        expect(make_me_sound_important.param_mutator.is_a? Proc).to be true
+        expect(make_me_sound_important.single_mutator.is_a? Proc).to be true
       end
     end
   end
@@ -177,6 +196,13 @@ describe Tzu::Sequence do
       end
     end
 
+    context MultiStepNonTzu do
+      it 'returns the outcome of the last command' do
+        outcome = MultiStepNonTzu.run('Greetings', 'Christopher', 'Canada')
+        expect(outcome.result).to eq 'Greetings, Christopher! You are the most important citizen of Canada!'
+      end
+    end
+
     context MultiStepComplex do
       it 'returns the outcome of the last command' do
         outcome = MultiStepComplex.run(params)

data/spec/step_spec.rb

@@ -21,4 +21,36 @@ describe Tzu::Step do
       end
     end
   end
+
+  context '#receives' do
+    context 'when splat_mutator is already defined' do
+      let(:step) { Tzu::Step.new(:step_name) }
+
+      before do
+        step.receives_many do |variable|
+          [1, 2, 3]
+        end
+      end
+
+      it 'throws error' do
+        expect { step.receives { |var| 'foo'} } .to raise_error(Tzu::InvalidSequence)
+      end
+    end
+  end
+
+  context '#receives_many' do
+    context 'when single_mutator is already defined' do
+      let(:step) { Tzu::Step.new(:step_name) }
+
+      before do
+        step.receives do |var|
+          'hello'
+        end
+      end
+
+      it 'throws error' do
+        expect { step.receives_many { |var| [1, 2, 3] } } .to raise_error(Tzu::InvalidSequence)
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tzu
 version: !ruby/object:Gem::Version
-  version: 0.1.0.0
+  version: 0.1.1.0
 platform: ruby
 authors:
 - Morgan Bruce
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-24 00:00:00.000000000 Z
+date: 2015-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -109,7 +109,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Encapsulate your database queries with dynamically generated classes
+description: Tzu is a library for issuing commands in Ruby
 email: morgan@onfido.com
 executables: []
 extensions: []
@@ -119,6 +119,7 @@ files:
 - README.md
 - lib/tzu.rb
 - lib/tzu/core_extensions/string.rb
+- lib/tzu/errors.rb
 - lib/tzu/failure.rb
 - lib/tzu/hooks.rb
 - lib/tzu/invalid.rb
@@ -159,8 +160,7 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Get is a library designed to encapsulate Rails database queries and prevent
-  query pollution in the view layer.
+summary: Standardise and encapsulate your application's actions
 test_files:
 - spec/hooks_spec.rb
 - spec/outcome_spec.rb