tzu 0.0.2.0 → 0.1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e476045f4ece3c811b3fdaedad37f1a035f12e13
-  data.tar.gz: b699bc51b73743dcaa26a42394fe8a086018dd7b
+  metadata.gz: 9fc0ed30a4b98b00a486d4fa819753e2c3903975
+  data.tar.gz: 79ec5b04b569d4463d0d7f4c88e9b5271476fed3
 SHA512:
-  metadata.gz: 2838ccd7ae2ed0cab8e6827ddeaa765520a55a49f42865f7739d96142e232dfbe96e4ea0d6ca20996f3a39fc6258124d90e39fde3adc0cdde769b341d2e0efdf
-  data.tar.gz: 337506517ab4d5e0dc25b6a1e7a6fab72aeb71dc47129d8adfbd304a7e579bb4416680440fe7b6109624ea0735ce3ce8381d80461773230bf49dc4d97426c18d
+  metadata.gz: 2918e22b6a49c4d9d878413621fa0d1456f369a41fe84adafc0fdcbc2d9996caaf531e42a102cb11fc1b1a6d07d8ec311dc3c6b0904cfbcc792dd21792824a0f
+  data.tar.gz: b3007e68797f9b89bfa75682eda9ceab964598e548e404c8e23039db2ee9e563e81fb19f99b4a47ffa3994114caa0f1afa36533e881230db6de7273d167ee656

data/README.md

@@ -1 +1,396 @@
 # Tzu
+
+## Usage
+
+Tzu commands must include Tzu and implement a `#call` method.
+
+```ruby
+class MyCommand
+  include Tzu
+
+  def call(params)
+    "My Command Response - #{params.message}"
+  end
+end
+```
+
+Tzu exposes `#run` at the class level, and returns an Outcome object.
+The Outcome's `result` will be the return value of the command's `#call` method.
+
+```ruby
+outcome = MyCommand.run(message: 'Hello!')
+#=> #<Tzu::Outcome @success=false, @result='My Command Response - Hello!'>
+
+outcome.success? #=> true
+outcome.failure? #=> false
+outcome.result #=> 'My Command Response - Hello!'
+```
+
+## Validation
+
+Tzu also provides an `invalid!` method that allows you to elegantly escape execution.
+
+```ruby
+class MyCommand
+  include Tzu
+
+  def call(params)
+    invalid!('You did not do it') unless params[:message] == 'I did it!'
+    "My Command Response - #{params[:message]}"
+  end
+end
+```
+
+When invoking Tzu with `#run`, `invalid!` will return an invalid Outcome.
+
+```ruby
+outcome = MyCommand.run(message: 'Hello!')
+outcome.success? #=> false
+outcome.failure? #=> true
+outcome.type #=> :validation
+outcome.result #=> { errors: 'You did not do it' }
+```
+
+When invoking Tzu with `#run!`, `invalid!` will throw a Tzu::Invalid error.
+
+```ruby
+outcome = MyCommand.run!(message: 'Hello!') #=> Tzu::Invalid: 'You did not do it'
+```
+
+If you use `invalid!` while catching an exception, you can pass the exception as an argument.
+The exception's `#message` value will be passed along to the outcome.
+
+```ruby
+class MyRescueCommand
+  include Tzu
+
+  def call(params)
+    raise StandardError.new('You did not do it')
+  rescue StandardError => e
+    invalid!(e)
+  end
+end
+```
+
+```ruby
+outcome = MyRescueCommand.run!(params_that_cause_error)
+#=> Tzu::Invalid: 'You did not do it'
+```
+
+Note that if you pass a string to `invalid!`, it will coerce the result into a hash of the form:
+
+```
+{ errors: 'Error String' }
+```
+
+Any other type will simply be passed through.
+
+## Passing Blocks
+
+You can also pass a block to Tzu commands.
+
+Successful commands will execute the `success` block, and invalid commands will execute the `invalid` block.
+This is particularly useful in controllers:
+
+```ruby
+MyCommand.run(message: params[:message]) do
+  success do |result|
+    render(json: {message: result}.to_json, status: 200)
+  end
+
+  invalid do |errors|
+    render(json: errors.to_json, status: 422)
+  end
+end
+```
+
+## Hooks
+
+Tzu commands accept `before`, `after`, and `around` hooks.
+All hooks are executed in the order they are declared.
+
+```ruby
+class MyCommand
+  include Tzu
+
+  around do |command|
+    puts 'Begin Around 1'
+    command.call
+    puts 'End Around 1'
+  end
+
+  around do |command|
+    puts 'Begin Around 2'
+    command.call
+    puts 'End Around 2'
+  end
+
+  before { puts 'Before 1' }
+  before { puts 'Before 2' }
+
+  after { puts 'After 1' }
+  after { puts 'After 2' }
+
+  def call(params)
+    puts "My Command Response - #{params[:message]}"
+  end
+end
+
+MyCommand.run(message: 'Hello!')
+
+#=> Begin Around 1
+#=> Begin Around 2
+#=> Before 1
+#=> Before 2
+#=> My Command Response - Hello!
+#=> After 1
+#=> After 2
+#=> End Around 2
+#=> End Around 1
+```
+
+
+
+## Request objects
+
+You can define a request object for your command using the `#request_object` method.
+
+```ruby
+class MyValidatedCommand
+  include Tzu, Tzu::Validation
+
+  request_object MyRequestObject
+
+  def call(request)
+    "Name: #{request.name}, Age: #{request.age}"
+  end
+end
+```
+
+Request objects must implement an initializer that accepts the command's parameters.
+
+If you wish to validate your parameters, the Request object must implement `#valid?` and `#errors`.
+
+```ruby
+class MySimpleRequestObject
+  def initialize(params)
+    @params = params
+  end
+
+  def valid?
+    # Validate Parameters
+  end
+
+  def errors
+    # Why aren't I valid?
+  end
+end
+```
+
+A very useful combination for request objects is Virtus.model and ActiveModel::Validations.
+
+ActiveModel::Validations exposes all of the validators used on Rails models.
+Virtus.model validates the types of your inputs, and also makes them available via dot notation.
+
+```ruby
+class MyRequestObject
+  include Virtus.model
+  include ActiveModel::Validations
+  validates :name, :age, presence: :true
+
+  attribute :name, String
+  attribute :age, Integer
+end
+```
+
+If your request object is invalid, Tzu will return an invalid outcome before reaching the `#call` method.
+The invalid Outcome's result is populated by the request object's `#errors` method.
+
+```ruby
+class MyValidatedCommand
+  include Tzu, Tzu::Validation
+
+  request_object MyRequestObject
+
+  def call(request)
+    "Name: #{request.name}, Age: #{request.age}"
+  end
+end
+
+outcome = MyValidatedCommand.run(name: 'Charles')
+#=> #<Command::Outcome @success=false, @result={:age=>["can't be blank"]}, @type=:validation>
+
+outcome.success? #=> false
+outcome.type? #=> :validation
+outcome.result #=> {:age=>["can't be blank"]}
+```
+
+# Configure a sequence of Tzu commands
+
+Tzu provides a declarative way of encapsulating sequential command execution.
+
+Consider the following commands:
+
+```ruby
+class SayMyName
+  include Tzu
+
+  def call(params)
+    "Hello, #{params[:name]}"
+  end
+end
+
+class MakeMeSoundImportant
+  include Tzu
+
+  def call(params)
+    "#{params[:boring_message]}! You are the most important citizen of #{params[:country]}!"
+  end
+end
+```
+
+The Tzu::Sequence provides a DSL for executing them in sequence:
+
+```ruby
+class ProclaimMyImportance
+  include Tzu::Sequence
+
+  step SayMyName do
+    receives do |params|
+      { name: params[:name] }
+    end
+  end
+
+  step MakeMeSoundImportant do
+    receives do |params, prior_results|
+      {
+        boring_message: prior_results[:say_my_name],
+        country: params[:country]
+      }
+    end
+  end
+end
+```
+
+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.
+You can define your own keys using the `as` method.
+
+```ruby
+step SayMyName do
+  as :first_command_key
+  receives do |params|
+    { name: params[:name] }
+  end
+end
+```
+
+# Executing the sequence
+
+By default, Sequences return the result of the final command within an Outcome object,
+
+```ruby
+outcome = ProclaimMyImportance.run(name: 'Jessica', country: 'Azerbaijan')
+outcome.success? #=> true
+outcome.result #=> 'Hello, Jessica! You are the most important citizen of Azerbaijan!'
+```
+
+Sequences can be configured to return the entire `prior_results` hash by passing `:take_all` to the `result` method.
+
+```ruby
+class ProclaimMyImportance
+  include Tzu::Sequence
+
+  step SayMyName do
+    receives do |params|
+      { name: params[:name] }
+    end
+  end
+
+  step MakeMeSoundImportant do
+    receives do |params, prior_results|
+      {
+        boring_message: prior_results[:say_my_name],
+        country: params[:country]
+      }
+    end
+  end
+
+  result :take_all
+end
+
+outcome = ProclaimMyImportance.run(name: 'Jessica', country: 'Azerbaijan')
+outcome.result
+#=> { say_my_name: 'Hello, Jessica', make_me_sound_important: 'Hello, Jessica! You are the most important citizen of Azerbaijan!' }
+```
+
+You can also mutate the result into any form you choose by passing a block to `result`.
+
+```ruby
+class ProclaimMyImportance
+  include Tzu::Sequence
+
+  step SayMyName do
+    receives do |params|
+      { name: params[:name] }
+    end
+  end
+
+  step MakeMeSoundImportant do
+    as :final_command
+    receives do |params, prior_results|
+      {
+        boring_message: prior_results[:say_my_name],
+        country: params[:country]
+      }
+    end
+  end
+
+  result do |params, prior_results|
+    {
+      name: params[:name],
+      original_message: prior_results[:say_my_name],
+      message: "BULLETIN: #{prior_results[:final_command]}"
+    }
+  end
+end
+
+outcome = ProclaimMyImportance.run(name: 'Jessica', country: 'Azerbaijan')
+outcome.result
+#=> { name: 'Jessica', original_message: 'Hello, Jessica', message: 'BULLETIN: Hello, Jessica! You are the most important citizen of Azerbaijan!' }
+```
+
+# 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.
+
+```ruby
+class ProclaimMyImportance
+  include Tzu::Sequence
+
+  around do |sequence|
+    ActiveRecord::Base.transaction do
+      sequence.call
+    end
+  end
+
+  step SayMyName do
+    receives do |params|
+      { name: params[:name] }
+    end
+  end
+
+  step MakeMeSoundImportant do
+    receives do |params, prior_results|
+      {
+        boring_message: prior_results[:say_my_name],
+        country: params[:country]
+      }
+    end
+  end
+end
+```

data/lib/tzu.rb

@@ -1,8 +1,11 @@
+require 'tzu/core_extensions/string'
+require 'tzu/run_methods'
 require 'tzu/failure'
 require 'tzu/hooks'
 require 'tzu/invalid'
 require 'tzu/match'
-require 'tzu/organizer'
+require 'tzu/sequence'
+require 'tzu/step'
 require 'tzu/outcome'
 require 'tzu/validation'
 require 'tzu/validation_result'
@@ -10,45 +13,14 @@ require 'tzu/validation_result'
 module Tzu
   def self.included(base)
     base.class_eval do
-      extend ClassMethods
+      extend RunMethods
       include Hooks
+      include Validation
     end
   end
 
-  module ClassMethods
-    def run(params, *context, &block)
-      result = get_instance(*context).run(params)
-      if block
-        result.handle(&block)
-      else
-        result
-      end
-    end
-
-    def run!(params, *context)
-      get_instance(*context).run!(params)
-    end
-
-    def get_instance(*context)
-      method = respond_to?(:build) ? :build : :new
-      send(method, *context)
-    end
-
-    def command_name(value = nil)
-      if value.nil?
-        @name ||= name.underscore.to_sym
-      else
-        @name = (value.presence && value.to_sym)
-      end
-    end
-  end
-
-  def command_name
-    self.class.command_name
-  end
-
   def run(params)
-    run!(request_object(params))
+    run!(init_request_object(params))
   rescue Failure => f
     Outcome.new(false, f.errors, f.type)
   end
@@ -63,26 +35,15 @@ module Tzu
     raise
   end
 
-  def fail!(type, data={})
-    raise Failure.new(type, data)
+  def command_name
+    self.class.command_name
   end
 
   private
 
-  def request_object(params)
-    klass = request_class
-    return klass.new(params) if klass && !params.is_a?(klass)
+  def init_request_object(params)
+    request_klass = self.class.request_klass
+    return request_klass.new(params) if request_klass
     params
   end
-
-  # Get the name of a request class related to calling class
-  # ie.   Tzus::MyNameSpace::MyTzu
-  # has   Tzus::MyNameSpace::Requests::MyTzu
-  def request_class
-    namespace =  self.class.name.deconstantize.constantize
-    request_object_name = "Requests::#{ self.class.name.demodulize}"
-    namespace.qualified_const_get(request_object_name)
-  rescue NameError
-    false
-  end
 end