seam 0.0.9 → 0.0.10

data/README.md

@@ -1,6 +1,136 @@
 # Seam
 
-TODO: Write a gem description
+Simple workflows in Ruby. 
+
+## Usage
+
+Seam is meant for situations where you want to take some entity (user, order, ec.) through a long-running process that is comprised of multiple steps.
+
+For example, if you want every new user a "hello" email after signup, then wait a few days, and then send a "gone so soon?" email if they haven't signed in again.
+
+This gem provides some simple tools for building and executing this process.
+It provides a way to define the process, break it up into separate components, and then send entities through the process.
+
+####Define a workflow####
+
+To start, define a workflow.
+
+````
+flow = Seam::Flow.new
+flow.send_order_to_warehouse
+flow.wait_for_order_to_be_shipped wait_up_to: 7.days
+flow.send_shipping_email email_template: 'shipping_7'
+flow.mark_order_as_fulfilled
+````
+
+A flow will convert any method call you make into a step that has to be completed. 
+
+You can also pass a hash to the method, which will be saved for later.
+
+````
+flow.wait_for_order_to_be_shipped wait_up_to: 7.days
+````
+
+####Starting an instance of the flow####
+
+Starting an instance of the flow is done with "start":
+
+````
+flow.start order_id: '1234'
+````
+
+An instance of this effort was created and saved in whatever persistence is being used (in-memory by default). 
+
+This effort will start at the first step (send_order_to_warehouse) and then progress through the steps as they are completed.
+
+"start" also returns the effort that was created, and it will look like this:
+
+````
+<Seam::Effort 
+  @completed_steps=[], 
+  @history=[], 
+  @complete=false, 
+  @id="1ecc4cbe-16af-45f6-8532-7f37493ec11c", 
+  @created_at=2013-08-20 22:58:07 -0500, 
+  @next_execute_at=2013-08-20 22:58:07 -0500, 
+  @next_step="send_order_to_warehouse", 
+  @flow={"steps"=>[{"name"=>"send_order_to_warehouse", "type"=>"do", "arguments"=>{}}, {"name"=>"wait_for_order_to_be_shipped", "type"=>"do", "arguments"=>{}}, {"name"=>"send_shipping_email", "type"=>"do", "arguments"=>{}}, {"name"=>"mark_order_as_fulfilled", "type"=>"do", "arguments"=>{}}]}, 
+  @data={"order_id"=>"1234"}>
+````
+
+So we have a unique instance of this flow and the instance has been saved in the database.  The first step to be executed for this instance is "send_order_to_warehouse", so let's create a worker for this step.
+
+####Defining workers for each step####
+
+A workflow is comprised of steps, and each step needs a worker.  Each worker will execute whatever it was meant to do, and then either:
+
+1. Pass the workflow instance to the next step on the process, or
+2. Delay the step execution for a later date, or
+3. End the entire workflow process for the instance.
+
+Since send_order_to_warehouse is the first step in this workflow, let's build the worker for it first:
+
+````
+class SendOrderToWarehouseWorker < Seam::Worker
+  def process
+    # the current workflow instance is available as "effort"
+    order = Order.find effort.data['order_id']
+    warehouse_service.send order
+
+    # by default, if this worker completes with no error the workflow instance will be sent to the next step
+  end
+end
+````
+
+If you name your class as a camel-case version of the step, Seam will automatically bind up the worker to the step.  
+
+To execute the worker, use:
+
+````
+SendOrderToWarehouse.execute_all
+````
+
+This method will look for all workflow instances that are currently ready for the step in question.
+
+####Progressing through the workflow####
+
+By default, steps are considered as being completed when the worker completes successfully.  There might be times where you don't want to go quickly, like the next step in this example:
+
+````
+class WaitForOrderToBeShippedWorker < Seam::Worker
+  def process
+    effort.data["shipping_status"] = # some method that returns the shipping status
+    unless effort.data["shipping_status"] == "shipped"
+      try_again_in 4.hours
+    end
+  end
+end
+````
+
+"try_again_in" can be used to signal that the step has not been completed and should be retried later.
+
+"eject" can also be used to signify that the entire workflow should be stopped, like so:
+
+````
+class WaitForOrderToBeShippedWorker < Seam::Worker
+  def process
+    effort.data["shipping_status"] = # some method that returns the shipping status
+    if effort.data["shipping_status"] == "cancelled"
+      eject # no need to continue!
+    end
+  end
+end
+````
+
+####History####
+
+As workflow instances progress through each step, the history of every operation will be stored.  A history of the "data" block before and after each step run is also stored.
+
+The history is available through:
+
+````
+effort.history
+````
 
 ## Installation
 
@@ -16,10 +146,6 @@ Or install it yourself as:
 
     $ gem install seam
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it

data/lib/seam/flow.rb

@@ -2,13 +2,12 @@ module Seam
   class Flow
 
     def initialize
-      @steps = {}
+      @steps = []
     end
 
     def method_missing(meth, *args, &blk)
       meth = meth.to_s
-      return false if @steps[meth]
-      @steps[meth] = args
+      @steps << { name: meth, arguments: args }
       true
     end
 
@@ -28,10 +27,10 @@ module Seam
     end
 
     def steps
-      @steps.each.map do |name, arguments|
-        Seam::Step.new( { name:       name,
+      @steps.each.map do |step|
+        Seam::Step.new( { name:      step[:name],
                           type:      'do',
-                          arguments: arguments } )
+                          arguments: step[:arguments] } )
 
       end
     end

data/lib/seam/version.rb

@@ -1,3 +1,3 @@
 module Seam
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
 end

data/spec/seam/flow_spec.rb

@@ -109,8 +109,23 @@ describe "flow" do
         flow = Seam::Flow.new
         flow.do_something.must_equal true
         flow.steps.count.must_equal 1
-        flow.do_something.must_equal false
-        flow.steps.count.must_equal 1
+        flow.do_something.must_equal true
+        flow.steps.count.must_equal 2
+      end
+    end
+
+    describe "repeating steps with different data" do
+      it "should only add the step once" do
+        flow = Seam::Flow.new
+        flow.do_something(special_id: 'one').must_equal true
+        flow.do_something( { special_id: 'two' }, 4).must_equal true
+        flow.steps.count.must_equal 2
+
+        flow.steps[0].arguments.count.must_equal 1
+        flow.steps[0].arguments[0].contrast_with!( { special_id: 'one' } )
+        flow.steps[1].arguments.count.must_equal 2
+        flow.steps[1].arguments[0].contrast_with!( { special_id: 'two' } )
+        flow.steps[1].arguments[1].must_equal 4
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seam
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-20 00:00:00.000000000 Z
+date: 2013-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -227,7 +227,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1805101925636728224
+      hash: -3288944774515324226
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -236,7 +236,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1805101925636728224
+      hash: -3288944774515324226
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25