waterfall 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 129bb57a29df2394c12511053c406490b8a99674
+  data.tar.gz: e7260b30ce91910cdb8d1466a39898000bde0fa5
+SHA512:
+  metadata.gz: 80c9da8ab97a26854f8fa5700e1a8669409f2212fe16660805dff074894df2ba89aea2bec52efd232b874646de286cc992f9ad8d3be679fd63beefffdaa132fd
+  data.tar.gz: c9253aa6ce5ce77577398006957eab695b8489db2b914adfb68e44b0319820d6e8fa92159ed6a77aed93726f803e476194e7227bb8a844f82adf7283de6ddd9a

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.0
+script: bundle exec rspec spec
+addons:
+  code_climate:
+    repo_token: 06ba7b4d95c2d056ef2b66c86e9d69f24dceee54354c1ab2ce1397f8f309b0a4

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in waterfall.gemspec
+gemspec
+
+gem "codeclimate-test-reporter", group: :test, require: nil

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    waterfall (1.0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    codeclimate-test-reporter (0.4.7)
+      simplecov (>= 0.7.1, < 1.0.0)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    json (1.8.2)
+    method_source (0.8.2)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-nav (0.2.4)
+      pry (>= 0.9.10, < 0.11.0)
+    rake (10.3.2)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  codeclimate-test-reporter
+  pry (> 0.10)
+  pry-nav
+  rake
+  rspec (= 3.2)
+  waterfall!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Benjamin Roth
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,345 @@
+![Waterfall Logo](http://apneadiving.github.io/images/waterfall_logo.png)
+[![Code Climate](https://codeclimate.com/github/apneadiving/waterfall/badges/gpa.svg)](https://codeclimate.com/github/apneadiving/waterfall)
+[![Test Coverage](https://codeclimate.com/github/apneadiving/waterfall/badges/coverage.svg)](https://codeclimate.com/github/apneadiving/waterfall/coverage)
+[![Build Status](https://travis-ci.org/apneadiving/waterfall.svg?branch=master)](https://travis-ci.org/apneadiving/waterfall)
+#### Goal
+
+Be able to chain ruby commands, and treat them like a flow.
+
+General presentation slides can [be found here](https://slides.com/apneadiving/code-ruby-like-you-build-legos).
+
+Check [the slides here](https://slides.com/apneadiving/handling-error-in-ruby-rails) for a refactoring example.
+
+
+#### Basic example
+
+```ruby
+Wf.new
+  .when_falsy { @user.update(user_params) }
+    .dam { @user.errors }
+  .chain { render json: @user }
+  .on_dam { |errors| render json: { errors: errors.full_messages }, status: 422 }
+```
+
+When logic is complicated, waterfalls show their true power and let you write intention revealing code. Above all they excel at chaining services.
+
+#### Rationale
+Coding is all about writing a flow of commands.
+
+Generally you basically go on, unless something wrong happens. Whenever this happens you have to halt the flow and send feedback to the user.
+
+When conditions stack up, readability decreases.
+
+One way to solve it is to create abstractions to wrap your business logic (service objects or the like). There some questions arise:
+* what should a good service return?
+* how to handle errors?
+* how to call a service within a service?
+* how to chain services / commands
+
+Those topics are discussed in [the slides here](https://slides.com/apneadiving/service-objects-waterfall-rails).
+
+
+## Wf object
+
+The `Wf` class just includes the `Waterfall` module. It makes it easy to create standalone waterfalls mostly to chain actions or to chain services including `Waterfall` or returning a `Wf` object.
+
+Basically `chain` statements are executed in the order they appear. But if ever the waterfall is dammed, they are skipped.
+
+If a main waterfall chains another waterfall and the child waterfall is dammed, the main waterfall would be dammed.
+
+The point is to be able to be able to chain an expected set of actions whenever everything works fine. And to be able to quickly stop and get the errors back whenever something wrong happens.
+
+## Installation
+
+There exists a gem on rubygem with the same name but its not mine :)
+
+For installation:
+
+    gem 'waterfall', git: 'git://github.com/apneadiving/waterfall.git'
+
+
+## Waterfall mixin
+
+### Overview
+
+The following are equivalent:
+```ruby
+# 1
+Wf.new.chain{ 1 + 1 }
+
+# 2
+class MyService
+  include Waterfall
+
+  def call
+    self.chain{ 1 + 1 }
+  end
+end
+
+MyService.new.call
+```
+
+This illustrates one convention classes including the mixin should obey: respond to `call`
+
+### Outputs
+
+Each waterfall has its own `outflow` and `error_pool`.
+
+`outflow` is an Openstruct so you can get/set its property like a hash or like a standard object.
+
+For the `error_pool`, its up to you. But using Rails, I usually `include ActiveModel::Validations` in my services.
+
+Thus you:
+
+* have a standard way to deal with errors
+* can deal with multiple errors
+* support I18n out of the box
+* can use your model errors out of the box
+
+## Illustration of chaining
+Doing
+```ruby
+ Wf.new
+   .chain(foo: :bar) { Wf.new.chain(:bar){ 1 } }
+```
+
+is the same as doing:
+
+```ruby
+ Wf.new
+   .chain do |outflow, parent_waterfall|
+     unless parent_waterfall.dammed?
+       child = Wf.new.chain(:bar){ 1 }
+       if child.dammed?
+         parent_waterfall.dam(child.error_pool)
+       else
+         parent_waterfall.ouflow.foo = child.outflow.bar
+       end
+     end
+   end
+```
+
+Hopefully you better get the chaining power this way.
+
+## Predicates
+
+### chain(name_or_mapping = nil, &block) | block signature: (outflow, waterfall)
+
+Chain is the main predicate, what it does depends on what the block returns
+```ruby
+ # main waterfall
+ Wf.new
+   .chain(foo: :bar) do
+     # child waterfall
+     Wf.new.chain(:bar){ 1 }.chain(:baz){ 2 }.chain{ 3 }
+   end
+```
+##### when block doesn't return a waterfall
+
+The child waterfall would have the following outflow: `{ bar: 1, baz: 2 }`
+
+This illustrates that when the block returns a value which is not a waterfall, it stores the returned value of the block inside the `name_or_mapping` key of the `outflow` or doesn't store it if `name_or_mapping` is `nil`.
+
+Be aware those are equivalent:
+
+```ruby
+Wf.new.chain(:foo) { 1 }
+Wf.new.chain{|outflow| outflow[:foo] = 1 }
+Wf.new.chain{|outflow| outflow.foo = 1 }
+Wf.new.chain{|outflow, waterfall| waterfall.update_outflow(:foo, 1) }
+Wf.new.chain{|outflow, waterfall| waterfall.outflow.foo = 1 }
+```
+##### when block returns a waterfall
+
+The main waterfall would have the following outflow: `{ foo: 1 }`
+
+The main waterfall above receives the child waterfall as a return value of its `chain` block.
+All waterfalls have independent outflows.
+
+If `name_or_mapping` is `nil`, the main waterfall's `outflow` wouldnt be affected by its child (but if the child is dammed, the parent will be dammed).
+
+If `name_or_mapping` is a `hash`, the format must be read as `{ name_in_parent_waterfall: :name_from_child_waterfall}`. In the above example, the child returned an `outflow` with a `bar` key which has be renamed as `foo` in the main one.
+
+It may look useless, because most of the time you may not rename, but... It makes things clear. You know exactly what you expect and you know exactly that you dont expect the rest the child may provide.
+
+### when_falsy(&block) | block signature: (error_pool, waterfall)
+
+This predicate must ***always*** be used followed with `dam` like:
+
+```ruby
+Wf.new
+  .chain(:foo) { 1 }
+  .when_falsy { true }
+   .dam { "this wouldnt be executed"  }
+  .when_falsy { false }
+   .dam { "errrrr"  }
+  .chain(:bar) { 2 }
+  .on_dam {|error_pool| puts error_pool  }
+```
+
+If the block returns a falsy value, it executes the `dam` block, which will store the returned value in the `error_pool`.
+
+Once the waterfall is dammed, all following `chain` blocks are skipped (wont be executed). And all the following `on_dam` block would be executed.
+
+As a result the example above would return a waterfall object having its `outflow` equal to `{ foo: 1 }`. Remember: it has been dammed before `bar` would have been set.
+
+Its `error_pool` would be `"errrrr"` and it would be `puts` as a result of the `on_dam`
+
+Be aware those are equivalent:
+
+```ruby
+Wf.new.when_falsy{ false }.dam{ 'errrr' }
+Wf.new.chain{ |outflow, waterfall| waterfall.dam('errrr') unless false }
+```
+
+### when_truthy(&block) | block signature: (error_pool, waterfall)
+
+Behaves the same as `when_falsy` except it dams when its return value is truthy
+
+## Syntactic sugar
+Given:
+```ruby
+class MyWaterfall
+  include Waterfall
+  def call
+    self.chain { 1 }
+  end
+end
+```
+You may have noticed that I usually write:
+
+```ruby
+Wf.new
+  .chain { MyWaterfall.new }
+```
+instead of
+```ruby
+Wf.new
+  .chain { MyWaterfall.new.call }
+```
+Both are the same: if a block returns a waterfall which was not executed, it will execute it (hence the `call` convention)
+
+### on_dam(&block) | block signature: (error_pool, outflow, waterfall)
+
+Its block is executed whenever the waterfall is dammed, skipped otherwise.
+
+```ruby
+Wf.new
+  .when_falsy { false }
+  .on_dam {|error_pool, outflow, waterfall| puts error_pool  }
+```
+
+## Error propagation
+
+Whenever a a waterfall is dammed, all the following chains are skipped.
+
+* all the following chains are skipped
+* all `on_dam` blocks are executed
+
+## Testing a Waterfall service
+
+Say I have this service:
+```ruby
+class AuthenticateUser
+  include Waterfall
+  include ActiveModel::Validations
+
+  validates :user, presence: true
+  attr_reader :user
+
+  def initialize(email, password)
+    @email, @password = email, @password
+  end
+
+  def call
+    self
+      .chain { @user = User.authenticate(@email, @password) }
+      .when_falsy { valid? }
+         .dam { errors }
+      .chain(:user) { user }
+  end
+end
+```
+I could spec it this way:
+```ruby
+describe AuthenticateUser do
+  let(:email)    { 'email@email.com' }
+  let(:password) { 'password' }
+  subject(:service) { AuthenticateUser.new(email, password).call }
+
+  context "when given valid credentials" do
+    let(:user) { double(:user) }
+
+    before do
+      allow(User).to receive(:authenticate).with(email, password).and_return(user)
+    end
+
+    it "succeeds" do
+      expect(service.dammed?).to be false
+    end
+
+    it "provides the user" do
+      expect(service.outflow.user).to eq(user)
+    end
+  end
+
+  context "when given invalid credentials" do
+    before do
+      allow(User).to receive(:authenticate).with(email, password).and_return(nil)
+    end
+
+    it "fails" do
+      expect(service.dammed?).to be true
+    end
+
+    it "provides a failure message" do
+      expect(service.error_pool).to be_present
+    end
+  end
+end
+```
+Syntax advice
+=========
+```ruby
+# this is valid
+self
+  .chain { Service1.new }
+  .chain { Service2.new }
+
+# this is equivalent
+self.chain { Service1.new }
+self.chain { Service2.new }
+
+# this is equivalent too
+chain { Service1.new }
+chain { Service2.new }
+
+# this is invalid Ruby due to the extra line
+self
+  .chain { Service1.new }
+
+  .chain { Service2.new }
+```
+
+Tips
+=========
+### Conditional Flow
+In a service, there is one and single flow, so if you need conditionals to branch off, you can do:
+```ruby
+self.chain { Service1.new }
+
+if foo?
+  self.chain { Service2.new }
+else
+  self.chain { Service3.new }
+end
+```
+
+
+Examples
+=========
+Check the [wiki for other examples](https://github.com/apneadiving/waterfall/wiki).
+
+Thanks
+=========
+Huge thanks to [laxrph10](https://github.com/laxrph10) for the help during infinite naming brainstorming.

data/lib/waterfall.rb

@@ -0,0 +1,85 @@
+require 'ostruct'
+require 'waterfall/version'
+require 'waterfall/predicates/base'
+require 'waterfall/predicates/on_dam'
+require 'waterfall/predicates/when_falsy'
+require 'waterfall/predicates/when_truthy'
+require 'waterfall/predicates/chain'
+
+module Waterfall
+
+  attr_reader :error_pool, :outflow, :flowing, :_wf_rolled_back
+
+  def when_falsy(&block)
+    handler = ::Waterfall::WhenFalsy.new(self)
+    _wf_run { handler.call(&block) }
+    handler
+  end
+
+  def when_truthy(&block)
+    handler = ::Waterfall::WhenTruthy.new(self)
+    _wf_run { handler.call(&block) }
+    handler
+  end
+
+  def chain(mapping_or_var_name = nil, &block)
+    _wf_run do
+      ::Waterfall::Chain
+        .new(self, mapping_or_var_name)
+        .call(&block)
+    end
+  end
+
+  def chain_wf(mapping_hash = nil, &block)
+    chain(mapping_hash, &block)
+  end
+
+  def on_dam(&block)
+    ::Waterfall::OnDam
+      .new(self)
+      .call(&block)
+    self
+  end
+
+  def dam(obj)
+    @error_pool = obj
+    self
+  end
+
+  def undam
+    dam nil
+    self
+  end
+
+  def dammed?
+    !error_pool.nil?
+  end
+
+  def is_waterfall?
+    true
+  end
+
+  def flowing?
+    !! @flowing
+  end
+
+  def update_outflow(key, value)
+    @outflow[key] = value
+    self
+  end
+
+  def _wf_run
+    @flowing = true
+    @outflow ||= OpenStruct.new({})
+    yield unless dammed?
+    self
+  end
+
+end
+
+class Wf
+  include Waterfall
+  def initialize
+    @outflow = OpenStruct.new({})
+  end
+end

data/lib/waterfall/predicates/base.rb

@@ -0,0 +1,23 @@
+module Waterfall
+  class Base
+
+    def waterfall?(obj)
+      obj.respond_to?(:is_waterfall?) && obj.is_waterfall?
+    end
+
+    def chained_waterfall(child_waterfall)
+      child_waterfall.call unless child_waterfall.flowing?
+
+      if child_waterfall.dammed?
+        @root.dam child_waterfall.error_pool
+      else
+        yield
+      end
+      self
+    end
+
+    def yield_args
+      [@root.outflow, @root]
+    end
+  end
+end

data/lib/waterfall/predicates/chain.rb

@@ -0,0 +1,26 @@
+module Waterfall
+  class Chain < Base
+
+    def initialize(root, mapping_or_var_name)
+      @root, @mapping_or_var_name = root, mapping_or_var_name
+    end
+
+    def call
+      output = yield(*yield_args)
+
+      if waterfall?(output)
+        map_waterfalls(output, @mapping_or_var_name || {})
+      else
+        @root.update_outflow(@mapping_or_var_name, output) if @mapping_or_var_name
+      end
+    end
+
+    def map_waterfalls(child_waterfall, mapping)
+      chained_waterfall(child_waterfall) do
+        mapping.each do |k, v|
+          @root.update_outflow(k, child_waterfall.outflow[v])
+        end
+      end
+    end
+  end
+end

data/lib/waterfall/predicates/on_dam.rb

@@ -0,0 +1,13 @@
+module Waterfall
+  class OnDam < Base
+
+    def initialize(root)
+      @root = root
+    end
+
+    def call
+      return unless @root.dammed?
+      yield @root.error_pool, @root.outflow, @root
+    end
+  end
+end

data/lib/waterfall/predicates/when_falsy.rb

@@ -0,0 +1,19 @@
+module Waterfall
+  class WhenFalsy < Base
+
+    def initialize(root)
+      @root = root
+    end
+
+    def call
+      @output = yield(*yield_args)
+    end
+
+    def dam
+      if !@root.dammed? && !@output
+        @root.dam yield(*yield_args)
+      end
+      @root
+    end
+  end
+end

data/lib/waterfall/predicates/when_truthy.rb

@@ -0,0 +1,19 @@
+module Waterfall
+  class WhenTruthy < Base
+
+    def initialize(root)
+      @root = root
+    end
+
+    def call
+      @output = yield(*yield_args)
+    end
+
+    def dam
+      if !@root.dammed? && @output
+        @root.dam yield(*yield_args)
+      end
+      @root
+    end
+  end
+end

data/lib/waterfall/version.rb

@@ -0,0 +1,3 @@
+module Waterfall
+  VERSION = "1.0.2"
+end

data/spec/integration_spec.rb

@@ -0,0 +1,197 @@
+require 'spec_helper'
+
+describe 'Wf' do
+  let(:wf) { Wf.new }
+
+  describe "chain" do
+
+    it "yields wf outflow" do
+      wf
+        .chain  {|outflow| outflow[:bar] = 'bar' }
+        .chain  {|outflow| @bar = outflow[:bar] }
+      expect(wf.outflow[:bar]).to eq 'bar'
+      expect(@bar).to eq 'bar'
+    end
+
+    it "assigns outflow's key the value of the block" do
+      wf
+        .chain(:bar) { 'bar' }
+      expect(wf.outflow[:bar]).to eq 'bar'
+    end
+
+    context "wf internals" do
+      it "dam from within" do
+        wf
+          .chain  {|outflow, waterfall| waterfall.dam('errrrr') }
+          .on_dam {|error_pool| @errors = error_pool }
+
+        expect(wf.dammed?).to be true
+        expect(@errors).to eq 'errrrr'
+      end
+
+      it "outflow from within" do
+        wf
+          .chain {|outflow, waterfall| waterfall.outflow[:foo] = 1 }
+
+        expect(wf.outflow[:foo]).to eq 1
+      end
+    end
+
+    describe "chaining waterfalls" do
+
+      shared_examples "a waterfall chain" do
+        describe 'chain_wf' do
+          it "takes expected vars only and rename them" do
+            wf
+              .chain_wf(baz: :foo) { waterfall }
+
+            expect(wf.outflow.foo).to be nil
+            expect(wf.outflow.bar).to be nil
+            expect(wf.outflow[:baz]).to eq waterfall.outflow[:foo]
+          end
+        end
+      end
+
+      context "from an instance of a custom waterfall class" do
+        class FakeService
+          include Waterfall
+
+          def call
+            self
+              .chain(:foo) { 1 }
+              .chain(:bar) { 2 }
+          end
+        end
+
+        let(:waterfall) { FakeService.new }
+
+        it_behaves_like "a waterfall chain"
+
+        context "only calls waterfall service if it was never called before" do
+          it "when passed as an instance responding to call" do
+            expect(waterfall).to receive(:call).once.and_call_original
+            wf
+              .chain { waterfall }
+          end
+
+          it "already called" do
+            expect(waterfall).to receive(:call).once.and_call_original
+            wf
+              .chain { waterfall.call }
+          end
+        end
+      end
+
+      context "from a mere wf" do
+        let(:waterfall) do
+          Wf.new
+            .chain(:foo) { 1 }
+            .chain(:bar) { 2 }
+        end
+
+        it_behaves_like "a waterfall chain"
+      end
+    end
+  end
+
+  describe "when falsy" do
+    let(:my_proc) { ->(val){ val } }
+
+    def action(bool)
+      wf
+        .chain { wf.dam('dammed') if dam? }
+        .when_falsy { my_proc.call(bool) }
+          .dam  { 'err' }
+        .chain  { @foo = 1 }
+        .on_dam { |error_pool| @error = error_pool }
+    end
+
+    context "main context not dammed" do
+      let(:dam?) { false }
+
+      it "when actually falsy" do
+        action false
+        expect(@error).to eq 'err'
+        expect(@foo).to_not eq 1
+      end
+
+      it "when actually truthy" do
+        action true
+        expect(@error).to_not eq 'err'
+        expect(@foo).to eq 1
+      end
+    end
+
+    context "main context dammed" do
+      let(:dam?) { true }
+
+      it "when actually falsy" do
+        expect(my_proc).to_not receive(:call)
+        action false
+      end
+    end
+  end
+
+  describe "when truthy" do
+    let(:my_proc) { ->(val){ val } }
+
+    def action(bool)
+      wf
+        .chain { wf.dam('dammed') if dam? }
+        .when_truthy { my_proc.call(bool) }
+          .dam  { 'err' }
+        .chain  { @foo = 1 }
+        .on_dam { |error_pool| @error = error_pool }
+    end
+
+    context "main context not dammed" do
+      let(:dam?) { false }
+
+      it "when actually falsy" do
+        action false
+        expect(@error).to_not eq 'err'
+        expect(@foo).to eq 1
+      end
+
+      it "when actually truthy" do
+        action true
+        expect(@error).to eq 'err'
+        expect(@foo).to_not eq 1
+      end
+    end
+
+    context "main context dammed" do
+      let(:dam?) { true }
+
+      it "when actually truthy" do
+        expect(my_proc).to_not receive(:call)
+        action true
+      end
+    end
+  end
+
+  describe "error propagation" do
+    class FailingChain
+      include Waterfall
+
+      def call
+        self
+          .chain {|error_pool, waterfall| waterfall.dam(self.class.error) }
+      end
+
+      def self.error
+        'err'
+      end
+    end
+
+    it "error propagates" do
+      wf
+        .chain { FailingChain.new }
+        .chain    { @foo = 1 }
+        .on_dam   { |error_pool| @error = error_pool }
+
+      expect(@foo).to_not eq 1
+      expect(@error).to eq FailingChain.error
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require "codeclimate-test-reporter"
+CodeClimate::TestReporter.start
+
+require File.expand_path('../../lib/waterfall', __FILE__)
+require 'pry'
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/waterfall.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'waterfall/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "waterfall"
+  spec.version       = Waterfall::VERSION
+  spec.authors       = ["Benjamin Roth"]
+  spec.email         = ["benjamin@rubyist.fr"]
+  spec.description   = %q{A slice of functional programming to chain ruby services and blocks. Make them flow!}
+  spec.summary       = %q{A slice of functional programming to chain ruby services and blocks. Make them flow!}
+  spec.homepage      = "https://github.com/apneadiving/waterfall"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "pry", '>0.10'
+  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "3.2"
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: waterfall
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Benjamin Roth
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>'
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>'
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: A slice of functional programming to chain ruby services and blocks.
+  Make them flow!
+email:
+- benjamin@rubyist.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- lib/waterfall.rb
+- lib/waterfall/predicates/base.rb
+- lib/waterfall/predicates/chain.rb
+- lib/waterfall/predicates/on_dam.rb
+- lib/waterfall/predicates/when_falsy.rb
+- lib/waterfall/predicates/when_truthy.rb
+- lib/waterfall/version.rb
+- spec/integration_spec.rb
+- spec/spec_helper.rb
+- waterfall.gemspec
+homepage: https://github.com/apneadiving/waterfall
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A slice of functional programming to chain ruby services and blocks. Make
+  them flow!
+test_files:
+- spec/integration_spec.rb
+- spec/spec_helper.rb