whenner 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a4aa8af9fb47aa98f75a11bb2433eacf417ae87
+  data.tar.gz: 69d6cbba0ed8f7549028e185618321b31be8a1a0
+SHA512:
+  metadata.gz: 33fe745591cd305f62158756d6de021c3bdb82b1501c73826a9e6a06010db311c4bfbf1f4234ea09680af99d3cea32391a0cfabf0e8b4f33f229ac65601f40b9
+  data.tar.gz: 97794e75339f30bf8de24b1325d51674fe96ee6a55a0e421ff17a54fdcc1e0b02fd97a21c0e1fa2ac28a0cb0b72dc17712fe55c45a424159043ba35f51708117

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+.bundle
+.yardoc
+doc

data/.rspec

@@ -0,0 +1,6 @@
+--format progress
+--color
+--order rand
+-Ilib
+-Ispec
+-r whenner

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0

data/.yardopts

@@ -0,0 +1,8 @@
+--no-private
+--title "Whenner"
+--readme README.md
+--markup markdown
+--markup-provider kramdown
+-
+HISTORY.md
+LICENSE

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    whenner (0.1.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    kramdown (1.3.0)
+    rake (10.1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    yard (0.8.7.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  kramdown
+  rake
+  rspec
+  whenner!
+  yard

data/HISTORY.md

@@ -0,0 +1,6 @@
+# HISTORY
+
+## 0.1.0
+
+* Initial release
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (C) 2013 Arjan van der Gaag
+
+
+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,119 @@
+# Whenner [![Build Status](https://secure.travis-ci.org/avdgaag/whenner.png?branch=master)](http://travis-ci.org/avdgaag/whenner)
+
+## Introduction
+
+A promise represents the eventual result of an asynchronous operation. The
+primary way of interacting with a promise is through its `done` and `fail`
+methods, which registers callbacks to receive either a promise’s eventual value
+or the reason why the promise cannot be fulfilled.
+
+## Installation
+
+Whenner is distributed as a Ruby gem, which should be installed on most Macs and
+Linux systems. Once you have ensured you have a working installation of Ruby
+and Ruby gems, install the gem as follows from the command line:
+
+    $ gem install whenner
+
+## Usage
+
+Whenner provides two basic methods to use deferreds:
+
+* `Whenner.defer` to create a new deferred object and return its promise. In the
+  block to the method you can fulfill or reject the deferred.
+* `Whenner.when` to convert one or more arguments into promises, combining them
+  into a single new promise that you can attach callbacks to.
+
+Deferred objects can give you a promise that, at some point in the future, will
+resolve to either a fulfilled or rejected state. When that happens, appropriate
+callbacks are called. You can attach such callbacks on a deferred or promise
+using three methods:
+
+* `done` to register blocks to be called when the promise is fulfilled;
+* `fail` to register blocks to be called when the promise is rejected;
+* `always` to register blocks to be called when the promise is resolved (either
+  fulfilled or rejected);
+
+Here's an example of making three asynchronous HTTP requests, waiting for them
+all to finish and acting on their results:
+
+```ruby
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'whenner'
+require 'uri'
+require 'net/http'
+
+include Whenner
+
+def async_get(uri)
+  defer do |f|
+    thread = Thread.new do
+      response = Net::HTTP.get_response(URI(uri))
+      if response.code =~ /^2/
+        f.fulfill response.body
+      else
+        f.reject response.message
+      end
+    end
+    at_exit { thread.join }
+  end
+end
+
+cnn     = async_get('http://edition.cnn.com')
+nytimes = async_get('http://www.nytimes.com')
+google  = async_get('http://www.google.nl')
+
+Whenner.when(cnn, google, nytimes).done do |results|
+  results.map { |str| str[/<title>(.+)<\/title>/, 1] }
+end.done do |titles|
+  puts "Success: #{titles.inspect}"
+end
+```
+
+As methods in Ruby can only take a single block, Whenner does not support a
+`then` method yet, that would combine the `done` and `fail` methods. This might
+be implementing in the future using something like this:
+
+```ruby
+defer { async_get('http://google.com') }.then do |on|
+  on.done { puts 'Success!' }
+  on.fail { puts 'Success!' }
+end
+```
+
+### Documentation
+
+See the inline [API
+docs](http://rubydoc.info/github/avdgaag/whenner/master/frames) for more
+information.
+
+## Other
+
+### Note on Patches/Pull Requests
+
+1. Fork the project.
+2. Make your feature addition or bug fix.
+3. Add tests for it. This is important so I don't break it in a future version
+   unintentionally.
+4. Commit, do not mess with rakefile, version, or history. (if you want to have
+   your own version, that is fine but bump version in a commit by itself I can
+   ignore when I pull)
+5. Send me a pull request. Bonus points for topic branches.
+
+### Issues
+
+Please report any issues, defects or suggestions in the [Github issue
+tracker](https://github.com/avdgaag/whenner/issues).
+
+### What has changed?
+
+See the [HISTORY](https://github.com/avdgaag/whenner/blob/master/HISTORY.md) file
+for a detailed changelog.
+
+### Credits
+
+Created by: Arjan van der Gaag  
+URL: [http://arjanvandergaag.nl](http://arjanvandergaag.nl)  
+Project homepage: [http://avdgaag.github.com/whenner](http://avdgaag.github.com/whenner)  
+Date: april 2012  
+License: [MIT-license](https://github.com/avdgaag/whenner/blob/master/LICENSE) (same as Ruby)

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require 'bundler'
+Bundler::GemHelper.install_tasks
+Bundler.setup
+
+desc 'Default: run specs.'
+task :default => :spec
+
+require 'rspec/core/rake_task'
+desc 'Run specs'
+RSpec::Core::RakeTask.new
+
+require 'yard'
+desc 'Generate API docs'
+YARD::Rake::YardocTask.new

data/lib/whenner/callback.rb

@@ -0,0 +1,55 @@
+module Whenner
+  # A Callback is used internally by {Deferred} to store its callbacks.
+  # It provides the same `call` interface as regular blocks, but this
+  # will always return a promise for the block's return value.
+  #
+  # When the block in question returns a regular object, a new deferred for
+  # that object is created and immediately fulfilled. When the block raises an
+  # exception, the returned promise is rejected with that exception. When the
+  # block returns a promise itself, the returned deferred will mimic that
+  # promise -- as if that promise is what actually was returned.
+  class Callback
+    # A callable object, usually a Ruby block.
+    #
+    # @return [#call]
+    attr_reader :block
+
+    # @return [Deferred] the deferred object representing the block's return
+    #   value.
+    attr_reader :deferred
+
+    def initialize(block)
+      @block    = block
+      @deferred = Deferred.new
+    end
+
+    # Run the block, passing it any given arguments, and return a promise
+    # for its return value.
+    #
+    # @return [Promise]
+    def call(*args)
+      update_deferred(*args)
+      deferred.promise
+    end
+
+    # @return [Promise] for this callback's {#deferred}.
+    # @see #deferred
+    def promise
+      deferred.promise
+    end
+
+    private
+
+    def update_deferred(*args)
+      retval = block.call(*args)
+      if retval.kind_of?(Promise)
+        retval.done { |arg| deferred.fulfill(arg) }
+        retval.fail { |arg| deferred.reject(arg) }
+      else
+        deferred.fulfill(retval)
+      end
+    rescue => e
+      deferred.reject(e)
+    end
+  end
+end

data/lib/whenner/conversions.rb

@@ -0,0 +1,17 @@
+module Whenner
+  module Conversions
+    module_function
+
+    # Convert any object to a promise. When the object in question responds to
+    # `to_promise`, the result of that method will be returned. If not, a new
+    # deferred object is created and immediately fulfilled with the given
+    # object.
+    #
+    # @param [Object] obj
+    # @return [Promise]
+    def Promise(obj)
+      return obj.to_promise if obj.respond_to?(:to_promise)
+      Deferred.new.fulfill(obj)
+    end
+  end
+end

data/lib/whenner/deferred.rb

@@ -0,0 +1,173 @@
+module Whenner
+  # A deferred object is an operation that will eventually resolve to a result
+  # value. A deferred can be in three possible states:
+  #
+  # * Pending: it has been created but not yet resolved.
+  # * Fulfilled: it has been successfully resolved.
+  # * Rejected: it has been unsuccessfully resolved.
+  #
+  # A deferred might transition from pending to fulfilled or rejected, but it
+  # will not transition again once resolved (resolved can be either fulfilled
+  # or rejected).
+  #
+  # When a deferred does resolve, it will trigger any applicable callbacks. You
+  # can stack on callbacks on a deferred object before it has been resolved and
+  # they will be called later. When you register callbacks on an already
+  # resolved deferred, the callback will be called immediately. Note that a
+  # callback will only be run once.
+  #
+  # When a callback is in the fulfilled state, it has a value that represents
+  # its eventual outcome. When it is rejected, it has a reason.
+  class Deferred
+    # @return [Promise] a promise for this deferred
+    attr_reader :promise
+
+    def initialize
+      @promise             = Promise.new(self)
+      @state               = :pending
+      @fulfilled_callbacks = []
+      @rejected_callbacks  = []
+      @always_callbacks    = []
+    end
+
+    # The value the deferred was resolved with.
+    #
+    # @raise [UnresolvedError] when the deferred is still pending
+    def value
+      raise UnresolvedError unless resolved?
+      @value
+    end
+
+    # The reason the deferred was rejected.
+    #
+    # @raise [UnresolvedError] when the deferred is still pending
+    def reason
+      raise UnresolvedError unless resolved?
+      @reason
+    end
+
+    # @return [Boolean] whether the deferred has not been resolved yet.
+    def pending?
+      state == :pending
+    end
+
+    # @return [Boolean] whether the deferred was successfully resolved.
+    def fulfilled?
+      state == :fulfilled
+    end
+
+    # @return [Boolean] whether the deferred was rejected.
+    def rejected?
+      state == :rejected
+    end
+
+    # @return [Boolean] whether the deferred was either fulfilled or rejected.
+    def resolved?
+      fulfilled? || rejected?
+    end
+
+    # Fulfill this promise with an optional value. The value will be stored in
+    # the deferred and passed along to any registered `done` callbacks.
+    #
+    # When fulfilling a deferred twice, nothing happens.
+    #
+    # @raise [CannotTransitionError] when it was already fulfilled.
+    # @return [Deferred] self
+    def fulfill(value = nil)
+      raise CannotTransitionError if rejected?
+      return if fulfilled?
+      unless resolved?
+        self.value = value
+        resolve_to(:fulfilled)
+      end
+      self
+    end
+
+    # Reject this promise with an optional reason. The reason will be stored in
+    # the deferred and passed along to any registered `fail` callbacks.
+    #
+    # When rejecting a deferred twice, nothing happens.
+    #
+    # @raise [CannotTransitionError] when it was already fulfilled.
+    # @return [Deferred] self
+    def reject(reason = nil)
+      raise CannotTransitionError if fulfilled?
+      return if rejected?
+      unless resolved?
+        self.reason = reason
+        resolve_to(:rejected)
+      end
+      self
+    end
+
+    # @return [Promise]
+    def to_promise
+      promise
+    end
+
+    # Register a callback to be run when the deferred is fulfilled.
+    #
+    # @yieldparam [Object] value
+    # @return [Promise] a new promise representing the return value
+    #   of the callback, or -- when that return value is a promise itself
+    #   -- a promise mimicking that promise.
+    def done(&block)
+      cb = Callback.new(block)
+      fulfilled_callbacks << cb
+      cb.call(*callback_response) if fulfilled?
+      cb.promise
+    end
+
+    # Register a callback to be run when the deferred is rejected.
+    #
+    # @yieldparam [Object] reason
+    # @return [Promise] a new promise representing the return value
+    #   of the callback, or -- when that return value is a promise itself
+    #   -- a promise mimicking that promise.
+    def fail(&block)
+      cb = Callback.new(block)
+      rejected_callbacks << cb
+      cb.call(*callback_response) if rejected?
+      cb.promise
+    end
+
+    # Register a callback to be run when the deferred is resolved.
+    #
+    # @yieldparam [Object] value
+    # @yieldparam [Object] reason
+    # @return [Promise] a new promise representing the return value
+    #   of the callback, or -- when that return value is a promise itself
+    #   -- a promise mimicking that promise.
+    def always(&block)
+      cb = Callback.new(block)
+      always_callbacks << cb
+      cb.call(*callback_response) if resolved?
+      cb.promise
+    end
+
+    private
+
+    attr_accessor :state
+    attr_writer :value, :reason
+    attr_reader :fulfilled_callbacks, :rejected_callbacks, :always_callbacks
+
+    def resolve_to(state)
+      self.state = state
+      flush
+    end
+
+    def result_callbacks
+      fulfilled? ? fulfilled_callbacks : rejected_callbacks
+    end
+
+    def callback_response
+      fulfilled? ? value : reason
+    end
+
+    def flush
+      (result_callbacks + always_callbacks).each do |cb|
+        cb.call(callback_response)
+      end
+    end
+  end
+end

data/lib/whenner/promise.rb

@@ -0,0 +1,44 @@
+module Whenner
+  # A promise represents the public face of a {Deferred} object. You can use it
+  # to add more callbacks to the deferred or inspect its state -- but you
+  # cannot resolve it.
+  #
+  # The methods and attributes of the promise are basically forwarded to the
+  # deferred.
+  class Promise
+    extend Forwardable
+
+    # @!attribute [r] fulfilled?
+    #   @return [Boolean] whether the deferred was successfully resolved.
+    # @!attribute [r] resolved?
+    #   @return [Boolean] whether the deferred was either fulfilled or rejected.
+    # @!attribute [r] rejected?
+    #   @return [Boolean] whether the deferred was rejected.
+    # @!attribute [r] pending?
+    #   @return [Boolean] whether the deferred has not been resolved yet.
+    # @!attribute [r] reason
+    #   @return [Object] the reason for the deferred to be rejected.
+    # @!attribute [r] value
+    #   @return [Object] the value that the deferred was fulfilled with.
+    # @!method fail(&block)
+    #   Register a callback to fire when the deferred is rejected.
+    #   @return [Promise] a new promise for the return value of the block.
+    # @!method done(&block)
+    #   Register a callback to fire when the deferred is fulfilled.
+    #   @return [Promise] a new promise for the return value of the block.
+    # @!method always(&block)
+    #   Register a callback to fire when the deferred is resolved.
+    #   @return [Promise] a new promise for the return value of the block.
+    def_delegators :@deferred, *%i[
+      reason value pending? fulfilled? resolved? rejected? fail done always
+    ]
+
+    def initialize(deferred)
+      @deferred = deferred
+    end
+
+    def to_promise
+      self
+    end
+  end
+end

data/lib/whenner/version.rb

@@ -0,0 +1,3 @@
+module Whenner
+  VERSION = '0.1.1'
+end

data/lib/whenner.rb

@@ -0,0 +1,63 @@
+require 'whenner/version'
+require 'forwardable'
+
+require 'whenner/conversions'
+require 'whenner/callback'
+require 'whenner/deferred'
+require 'whenner/promise'
+
+module Whenner
+  # Generic root exception for the Whenner library. Any other custom
+  # exceptions inherit from WhennerError.
+  class WhennerError < StandardError; end
+
+  # Custom exception raised when trying to access a deferred's value or
+  # reason before it is resolved.
+  #
+  # @see WhennerError
+  class UnresolvedError < WhennerError; end
+
+  # Custom exception raised when trying to transition an already resolved
+  # deferred.
+  #
+  # @see WhennerError
+  class CannotTransitionError < WhennerError; end
+
+  module_function
+
+  # Create a new deferred, resolve it in the block and get its promise back.
+  #
+  # @yieldparam [Deferred] deferred
+  # @return [Promise]
+  def defer
+    deferred = Deferred.new
+    yield deferred
+    deferred.promise
+  end
+
+  # Create a new deferred based that will resolve if/when the given promises
+  # are resolved. Use to combine multiple promises into a single deferred
+  # object.
+  #
+  # When all the given promises are fulfilled, the resulting promise from
+  # `when` if fulfilled with an array of all the values. When one of the given
+  # promises is rejected, the resulting promise is rejected with that reason.
+  #
+  # @param [Object] promises
+  # @return [Promise]
+  def when(*promises)
+    defer do |d|
+      promises.each_with_object([]) do |promise, values|
+        Conversions.Promise(promise).tap do |p|
+          p.done  do |value|
+            values << value
+            d.fulfill(values) if values.size == promises.size
+          end
+          p.fail do |reason|
+            d.reject(reason)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/whenner/conversions_spec.rb

@@ -0,0 +1,19 @@
+module Whenner
+  describe '#Promise' do
+    it 'returns a promise itself' do
+      promise = Whenner::Deferred.new.promise
+      expect(Whenner::Conversions.Promise(promise)).to be(promise)
+    end
+
+    it 'returns a promise for a deferred' do
+      deferred = Whenner::Deferred.new
+      expect(Whenner::Conversions.Promise(deferred)).to be(deferred.promise)
+    end
+
+    it 'returns a resolved promise for an object' do
+      promise = Whenner::Conversions.Promise('foo')
+      expect(promise.value).to eql('foo')
+      expect(promise).to be_fulfilled
+    end
+  end
+end

data/spec/whenner/deferred_spec.rb

@@ -0,0 +1,141 @@
+module Whenner
+  describe Deferred do
+    it 'is pending by default' do
+      expect(subject).to be_pending
+    end
+
+    context 'when pending' do
+      it 'can be fulfilled' do
+        subject.fulfill
+        expect(subject).to be_fulfilled
+      end
+
+      it 'can be rejected' do
+        subject.reject
+        expect(subject).to be_rejected
+      end
+
+      it 'has no value' do
+        expect { subject.value }.to raise_error
+      end
+    end
+
+    context 'when fulfilled' do
+      subject do
+        described_class.new.tap { |d| d.fulfill }
+      end
+
+      it 'cannot transition to other states' do
+        expect { subject.reject }.to raise_error
+      end
+
+      it 'has a value' do
+        expect(subject.value).to be_nil
+      end
+    end
+
+    context 'when rejected' do
+      subject do
+        described_class.new.tap { |d| d.reject(:foo) }
+      end
+
+      it 'cannot transition to other states' do
+        expect { subject.fulfill }.to raise_error
+      end
+
+      it 'has a reason' do
+        expect(subject.reason).to eql(:foo)
+      end
+    end
+
+    it 'creates a promise' do
+      expect(subject.promise).to be_kind_of(Promise)
+    end
+
+    context 'callbacks' do
+      it 'calls fulfillment callbacks when fulfilled' do
+        resolved = false
+        subject.done { resolved = true }
+        expect { subject.fulfill(:a) }.to change { resolved }.to(true)
+      end
+
+      it 'calls rejection callbacks when rejected' do
+        resolved = false
+        subject.fail { resolved = true }
+        expect { subject.reject(:a) }.to change { resolved }.to(true)
+      end
+
+      it 'calls always callbacks when resolved' do
+        resolved = false
+        subject.always { resolved = true }
+        expect { subject.fulfill(:a) }.to change { resolved }.to(true)
+      end
+
+      it 'passes fulfillment callbacks the value' do
+        resolved = nil
+        subject.done { |arg| resolved = arg }
+        expect { subject.fulfill(:a) }.to change { resolved }.to(:a)
+      end
+
+      it 'passes rejection callbacks the reason' do
+        resolved = nil
+        subject.done { |arg| resolved = arg }
+        expect { subject.fulfill(:a) }.to change { resolved }.to(:a)
+      end
+
+      it 'passes the value and reason to always callbacks' do
+        subject.always do |value, reason|
+          expect(value).to eql(:a)
+          expect(reason).to be_nil
+        end
+        subject.fulfill(:a)
+      end
+
+      it 'calls callbacks only once' do
+        called = 0
+        subject.done { called += 1 }
+        subject.fulfill(:a)
+        subject.fulfill(:b)
+        expect(called).to eql(1)
+      end
+
+      it 'runs callbacks in order' do
+        output = ''
+        subject.done { output << 'a' }
+        subject.done { output << 'b' }
+        subject.fulfill
+        expect(output).to eql('ab')
+      end
+
+      it 'returns a new promise that fulfills to the value' do
+        new_promise = subject.done { 'foo' }
+        subject.fulfill
+        expect(new_promise.value).to eql('foo')
+        expect(new_promise).to be_fulfilled
+      end
+
+      it 'returns a new promise that rejects to the reason' do
+        new_promise = subject.fail { 'foo' }
+        subject.reject
+        expect(new_promise.value).to eql('foo')
+        expect(new_promise).to be_fulfilled
+      end
+
+      it 'returns a new promise that mimics a promise value' do
+        d = Deferred.new
+        new_promise = subject.done { d.promise }
+        subject.fulfill(:b)
+        d.fulfill(:a)
+        expect(new_promise.value).to eql(:a)
+      end
+
+      it 'is rejected on exception' do
+        called = false
+        promise = subject.done { raise 'arg' }
+        promise.fail { |e| called = e }
+        subject.fulfill
+        expect(called).to be_a(RuntimeError)
+      end
+    end
+  end
+end

data/spec/whenner/promise_spec.rb

@@ -0,0 +1,51 @@
+module Whenner
+  describe Promise do
+    let(:deferred)    { Deferred.new }
+    subject(:promise) { deferred.promise }
+
+    it 'converts into a promise as itself' do
+      expect(promise.to_promise).to be(promise)
+    end
+
+    describe 'callbacks' do
+      it 'can add done callbacks to the deferred' do
+        expect { promise.done { :a } }.to change { deferred.send(:fulfilled_callbacks).size }.by(1)
+      end
+
+      it 'can add fail callbacks to the deferred' do
+        expect { promise.fail { :a } }.to change { deferred.send(:rejected_callbacks).size }.by(1)
+      end
+
+      it 'can add always callbacks to the deferred' do
+        expect { promise.always { :a } }.to change { deferred.send(:always_callbacks).size }.by(1)
+      end
+    end
+
+    context 'when the deferred is fulfilled' do
+      let(:deferred) { Deferred.new.fulfill(:a) }
+
+      it 'has a value' do
+        expect(promise.value).to eql(:a)
+      end
+
+      it 'knows its state' do
+        expect(promise).to be_resolved
+        expect(promise).to be_fulfilled
+      end
+    end
+
+
+    context 'when the deferred is rejected' do
+      let(:deferred) { Deferred.new.reject(:a) }
+
+      it 'has a reason' do
+        expect(promise.reason).to eql(:a)
+      end
+
+      it 'knows its state' do
+        expect(promise).to be_resolved
+        expect(promise).to be_rejected
+      end
+    end
+  end
+end

data/spec/whenner_spec.rb

@@ -0,0 +1,39 @@
+describe Whenner do
+  describe '#defer' do
+    it 'returns a new promise' do
+      promise = Whenner.defer { 'bla' }
+      expect(promise).to be_kind_of(Whenner::Promise)
+    end
+
+    it 'yields a deferred' do
+      expect { |b| Whenner.defer(&b) }.to yield_with_args(Whenner::Deferred)
+    end
+  end
+
+  describe '#when' do
+    let(:deferred1) { Whenner::Deferred.new }
+    let(:deferred2) { Whenner::Deferred.new }
+    let!(:promise)  { Whenner.when(deferred1.promise, deferred2.promise) }
+
+    it 'returns a promise' do
+      expect(Whenner.when).to be_kind_of(Whenner::Promise)
+      end
+
+    it 'resolves when all given promises are resolved' do
+      expect { deferred1.fulfill }.not_to change { promise.resolved? }.from(false)
+      expect { deferred2.fulfill }.to change { promise.resolved? }.to(true)
+    end
+
+    it 'fulfills with all values' do
+      deferred1.fulfill :a
+      deferred2.fulfill :b
+      expect(promise.value).to eql([:a, :b])
+    end
+
+    it 'rejects with the first reason' do
+      deferred1.reject :a
+      deferred2.reject :b
+      expect(promise.reason).to eql(:a)
+    end
+    end
+end

data/whenner.gemspec

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/whenner/version', __FILE__)
+
+Gem::Specification.new do |s|
+  # Metadata
+  s.name        = 'whenner'
+  s.version     = Whenner::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Arjan van der Gaag']
+  s.email       = %q{arjan@arjanvandergaag.nl}
+  s.description = %q{A simple promises implementation in Ruby.}
+  s.homepage    = %q{http://avdgaag.github.com/whenner}
+  s.summary     = <<-EOS
+A promise represents the eventual result of an asynchronous operation. The
+primary way of interacting with a promise is through its `done` and `fail`
+methods, which registers callbacks to receive either a promise’s eventual value
+or the reason why the promise cannot be fulfilled.
+EOS
+
+  # Files
+  s.files         = `git ls-files`.split("
+")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("
+")
+  s.executables   = `git ls-files -- bin/*`.split("
+").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # Rdoc
+  s.rdoc_options = ['--charset=UTF-8']
+  s.extra_rdoc_files = [
+     'LICENSE',
+     'README.md',
+     'HISTORY.md'
+  ]
+
+  # Dependencies
+  s.add_development_dependency 'kramdown'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rake'
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: whenner
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Arjan van der Gaag
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  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: yard
+  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: '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'
+description: A simple promises implementation in Ruby.
+email: arjan@arjanvandergaag.nl
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+- HISTORY.md
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- HISTORY.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/whenner.rb
+- lib/whenner/callback.rb
+- lib/whenner/conversions.rb
+- lib/whenner/deferred.rb
+- lib/whenner/promise.rb
+- lib/whenner/version.rb
+- spec/whenner/conversions_spec.rb
+- spec/whenner/deferred_spec.rb
+- spec/whenner/promise_spec.rb
+- spec/whenner_spec.rb
+- whenner.gemspec
+homepage: http://avdgaag.github.com/whenner
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+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.1.11
+signing_key: 
+specification_version: 4
+summary: A promise represents the eventual result of an asynchronous operation. The
+  primary way of interacting with a promise is through its `done` and `fail` methods,
+  which registers callbacks to receive either a promise’s eventual value or the reason
+  why the promise cannot be fulfilled.
+test_files:
+- spec/whenner/conversions_spec.rb
+- spec/whenner/deferred_spec.rb
+- spec/whenner/promise_spec.rb
+- spec/whenner_spec.rb
+has_rdoc: