when 0.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    when (0.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    minitest (2.12.1)
+    rake (0.9.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest (~> 2.0)
+  rake (~> 0.9)
+  when!

data/Rakefile

@@ -0,0 +1,10 @@
+require "rake/testtask"
+require "bundler/gem_tasks"
+
+Rake::TestTask.new("test") do |test|
+  test.libs << "test"
+  test.pattern = "test/**/*_test.rb"
+  test.verbose = true
+end
+
+task :default => :test

data/Readme.md

@@ -0,0 +1,119 @@
+# When.rb
+
+This library is a Ruby port of the wonderful JavaScript promise library
+[when.js](https://github.com/cujojs/when). The API is kept as close to the
+original as possible. In cases where there's a trade-off between 1:1 API
+compatibility and "being Ruby-like", the latter is preferred. An example is
+`When.defer`, which yields the newly created deferred to a block in Ruby.
+
+This is currently a minimal implementation and the port is being built on a
+what-I-need basis.
+
+## API
+
+### `When(value_or_promise)`
+
+Returns a promise. If the value is already a promise, it is returned. Otherwise,
+a new promise is created and immediately resolved with the provided value.
+
+### `When.defer`
+
+Create a deferred, equivalent to `When::Deferred.new`. The deferred can be
+"split" in its resolver and promise parts for better encapsulation:
+
+```ruby
+require "when"
+require "eventmachine"
+
+def async
+  deferred = When.defer
+  EventMachine.defer { deferred.resolver.resolve(42) }
+  deferred.promise
+end
+
+EventMachine.run do
+  async.then do |num
+    puts "Got number #{num}"
+    EventMachine.stop
+  end
+end
+```
+
+In this example, the returned promise can only register success and failure
+callbacks, it can not be used to resolve the deferred.
+
+### `When.resolve(value)`
+
+Creates a deferred and immediately resolves it with `value`, then returns the
+promise.
+
+### `When.reject(value)`
+
+Creates a deferred and immediately rejects it with `value`, then returns the
+promise.
+
+### `When.all(promises)`
+
+Takes an array of promises/deferreds and returns a promise that will either
+reject when the first promise rejects, or resolve when all promises have
+resolved.
+
+## Why?
+
+Working with EventMachine, I found that I didn't care to much for its deferrable
+implementation. My main objections was:
+
+1. The way it encourages you to extend deferrable types with custom logic to
+   create deferrable business objects.
+2. (More importantly) How it allows deferrables to be resolved multiple times.
+
+
+## Installing
+
+`when` ships as a gem:
+
+    $ gem install when
+
+Or in your Gemfile:
+
+    gem "when", "~> 0"
+
+## Contributing
+
+Contributions are welcome. To get started:
+
+    $ git clone git://gitorious.org/gitorious/when.git
+    $ cd when
+    $ bundle install
+    $ rake
+
+When you have fixed a bug/added a feature/done your thing, create a
+[clone on Gitorious](http://gitorious.org/gitorious/when-rb) or a
+[fork on GitHub](http://github.com/cjohansen/when-rb) and send a
+merge request/pull request, whichever you prefer.
+
+Please add tests when adding/altering code, and always make sure all the tests
+pass before submitting your contribution.
+
+## License
+
+### The MIT License (MIT)
+
+**Copyright (C) 2012 Gitorious AS**
+
+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/lib/when.rb

@@ -0,0 +1,135 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2012 Gitorious AS
+#
+# 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.
+#++
+
+module When
+  class Promise
+    def initialize(deferred); @deferred = deferred; end
+    def then(&block); @deferred.then(&block); end
+    def callback(&block); @deferred.callback(&block); end
+    def errback(&block); @deferred.errback(&block); end
+  end
+
+  class Resolver
+    def initialize(deferred); @deferred = deferred; end
+    def resolve(*args); @deferred.resolve(*args); end
+    def reject(*args); @deferred.reject(*args); end
+    def resolved?; @deferred.resolved; end
+  end
+
+  class Deferred
+    attr_reader :resolver, :promise
+
+    def initialize
+      @resolution = nil
+      @callbacks = { :resolved => [], :rejected => [] }
+      @resolver = Resolver.new(self)
+      @promise = Promise.new(self)
+    end
+
+    def resolve(*args); mark_resolved(:resolved, args); end
+    def reject(*args); mark_resolved(:rejected, args); end
+    def callback(&block); add_callback(:resolved, block); end
+    def then(&block); add_callback(:resolved, block); end
+    def errback(&block); add_callback(:rejected, block); end
+    def resolved?; !@resolution.nil?; end
+
+    private
+    def add_callback(type, block)
+      return notify_callbacks({ type => [block] }) if resolved?
+      @callbacks[type] << block
+    end
+
+    def mark_resolved(state, args)
+      raise AlreadyResolvedError.new("Already resolved") if resolved?
+      @resolution = [state, args]
+      notify_callbacks(@callbacks)
+    end
+
+    def notify_callbacks(callbacks)
+      blocks = callbacks[@resolution.first] || []
+      blocks.each { |cb| cb.call(*@resolution.last) }
+    end
+  end
+
+  def self.defer
+    deferred = Deferred.new
+    yield deferred if block_given?
+    deferred
+  end
+
+  def self.resolve(val)
+    deferred = Deferred.new
+    deferred.resolve(val)
+    deferred.promise
+  end
+
+  def self.reject(val)
+    deferred = Deferred.new
+    deferred.reject(val)
+    deferred.promise
+  end
+
+  def self.all(promises)
+    raise(ArgumentError, "expected enumerable promises") if !promises.is_a?(Enumerable)
+    resolved = 0
+    results = []
+    d = Deferred.new
+
+    attempt_resolution = lambda do |err, res|
+      break if d.resolved?
+      if err.nil?
+        d.resolve(res) if promises.length == resolved
+      else
+        d.reject(err)
+      end
+    end
+
+    wait_for_all(promises) do |err, result, index|
+      resolved += 1
+      results[index] = result
+      attempt_resolution.call(err, results)
+    end
+
+    attempt_resolution.call(nil, results) if promises.length == 0
+    d.promise
+  end
+
+  private
+  def self.wait_for_all(promises, &block)
+    promises.each_with_index do |p, i|
+      p.callback do |result|
+        block.call(nil, result, i)
+      end
+      p.errback { |e| block.call(e, nil, i) }
+    end
+  end
+
+  class AlreadyResolvedError < Exception; end
+end
+
+def When(val)
+  return val if val.respond_to?(:callback) && val.respond_to?(:errback)
+  When.resolve(val)
+end

data/lib/when/version.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2012 Gitorious AS
+#
+# 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.
+#++
+
+module When
+  VERSION = "0.1.0"
+end

data/test/test_helper.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2012 Gitorious AS
+#
+# 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.
+#++
+require "bundler/setup"
+require "minitest/autorun"
+
+Bundler.require(:default, :test)

data/test/when_test.rb

@@ -0,0 +1,249 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2012 Gitorious AS
+#
+# 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.
+#++
+require "test_helper"
+require "when"
+
+describe When do
+  describe "When" do
+    it "returns promise" do
+      promise = When(42)
+      assert promise.respond_to?(:callback)
+      assert promise.respond_to?(:errback)
+    end
+
+    it "resolves promise with value" do
+      promise = When(42)
+      called_back = false
+      promise.callback do |value|
+        assert_equal 42, value
+        called_back = true
+      end
+
+      assert called_back
+    end
+  end
+
+  describe "resolve" do
+    it "returns resolved promise" do
+      called_back = false
+      When.resolve(42).callback do |num|
+        assert_equal 42, num
+        called_back = true
+      end
+
+      assert called_back
+    end
+  end
+
+  describe "reject" do
+    it "returns rejected promise" do
+      called_back = false
+      When.reject(42).errback do |num|
+        assert_equal 42, num
+        called_back = true
+      end
+
+      assert called_back
+    end
+  end
+
+  describe "defer" do
+    it "creates deferred" do
+      deferred = When.defer
+      assert deferred.respond_to?(:callback)
+      assert deferred.respond_to?(:errback)
+      assert deferred.respond_to?(:resolve)
+      assert deferred.respond_to?(:reject)
+    end
+
+    it "resolves promise through resolver" do
+      deferred = When.defer
+      called_back = false
+      deferred.promise.callback { called_back = true }
+      assert !called_back
+      deferred.resolver.resolve
+      assert called_back
+    end
+
+    it "aliases then to callback" do
+      deferred = When.defer
+      called_back = false
+      deferred.promise.then { called_back = true }
+      deferred.resolver.resolve
+      assert called_back
+    end
+
+    it "resolves promise through deferred" do
+      deferred = When.defer
+      called_back = false
+      deferred.promise.callback { called_back = true }
+      assert !called_back
+      deferred.resolve
+      assert called_back
+    end
+
+    it "resolves deferred through deferred" do
+      deferred = When.defer
+      called_back = false
+      deferred.callback { called_back = true }
+      assert !called_back
+      deferred.resolve
+      assert called_back
+    end
+
+    it "raises if already resolved" do
+      deferred = When.defer
+      deferred.resolve
+      assert_raises(When::AlreadyResolvedError) do
+        deferred.resolve
+      end
+    end
+
+    it "rejects promise through reject" do
+      deferred = When.defer
+      called_back = false
+      deferred.promise.errback { called_back = true }
+      assert !called_back
+      deferred.resolver.reject
+      assert called_back
+    end
+
+    it "rejects promise through deferred" do
+      deferred = When.defer
+      called_back = false
+      deferred.promise.errback { called_back = true }
+      assert !called_back
+      deferred.reject
+      assert called_back
+    end
+
+    it "rejects deferred through deferred" do
+      deferred = When.defer
+      called_back = false
+      deferred.errback { called_back = true }
+      assert !called_back
+      deferred.reject
+      assert called_back
+    end
+
+    it "raises if already rejectd" do
+      deferred = When.defer
+      deferred.reject
+      assert_raises(When::AlreadyResolvedError) do
+        deferred.reject
+      end
+    end
+  end
+
+  describe ".all" do
+    it "returns deferrable" do
+      d = When.all([When(42)])
+      assert d.respond_to?(:callback)
+      assert d.respond_to?(:errback)
+    end
+
+    it "resolves immediately if no promises" do
+      d = When.all([])
+      called_back = false
+      d.callback do |results|
+        assert_equal [], results
+        called_back = true
+      end
+      assert called_back
+    end
+
+    it "resolves when single deferrable resolves" do
+      deferred = When::Deferred.new
+      d = When.all([deferred.promise])
+      resolved = false
+      d.callback { |results| resolved = true }
+
+      assert !resolved
+      deferred.resolve(42)
+      assert resolved
+    end
+
+    it "resolves when all deferrables are resolved" do
+      deferreds = [When::Deferred.new, When::Deferred.new, When::Deferred.new]
+      d = When.all(deferreds.map(&:promise))
+      resolved = false
+      d.callback { |results| resolved = true }
+
+      assert !resolved
+      deferreds[0].resolve(42)
+      assert !resolved
+      deferreds[1].resolve(13)
+      assert !resolved
+      deferreds[2].resolve(3)
+      assert resolved
+    end
+
+    it "rejects when single deferrable rejects" do
+      deferred = When::Deferred.new
+      d = When.all([deferred.promise])
+      rejected = false
+      d.errback { |results| rejected = true }
+
+      assert !rejected
+      deferred.reject(StandardError.new)
+      assert rejected
+    end
+
+    it "rejects on first rejection" do
+      deferreds = [When::Deferred.new, When::Deferred.new, When::Deferred.new]
+      d = When.all(deferreds.map(&:promise))
+      rejected = false
+      d.errback { |results| rejected = true }
+
+      deferreds[0].resolve(42)
+      deferreds[2].reject(StandardError.new)
+      deferreds[1].resolve(13)
+
+      assert rejected
+    end
+
+    it "proxies resolution vaule in array" do
+      deferred = When::Deferred.new
+      d = When.all([deferred.promise])
+      results = nil
+      d.callback { |res| results = res }
+
+      deferred.resolve(42)
+      assert_equal [42], results
+    end
+
+    it "orders results like input" do
+      deferred1 = When::Deferred.new
+      deferred2 = When::Deferred.new
+      d = When.all([deferred1.promise, deferred2.promise])
+      results = nil
+      d.callback { |res| results = res }
+
+      deferred2.resolve(42)
+      deferred1.resolve(13)
+      assert_equal [13, 42], results
+    end
+  end
+end

data/when.gemspec

@@ -0,0 +1,46 @@
+# encoding: utf-8
+# --
+# The MIT License (MIT)
+#
+# Copyright (C) 2012 Gitorious AS
+#
+# 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.
+#++
+dir = File.expand_path(File.dirname(__FILE__))
+require File.join(dir, "lib/when/version")
+
+Gem::Specification.new do |s|
+  s.name        = "when"
+  s.version     = When::VERSION
+  s.authors     = ["Christian Johansen"]
+  s.email       = ["christian@gitorious.org"]
+  s.homepage    = "http://gitorious.org/gitorious/seuss"
+  s.summary     = %q{A Ruby implementation of the wonderful when.js promise library}
+  s.description = %q{Currently very incomplete}
+
+  s.rubyforge_project = "when"
+
+  s.add_development_dependency "minitest", "~> 2.0"
+  s.add_development_dependency "rake", "~> 0.9"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: when
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Christian Johansen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-10-08 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 0
+        - 9
+        version: "0.9"
+  type: :development
+  version_requirements: *id002
+description: Currently very incomplete
+email: 
+- christian@gitorious.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- Readme.md
+- lib/when.rb
+- lib/when/version.rb
+- test/test_helper.rb
+- test/when_test.rb
+- when.gemspec
+has_rdoc: true
+homepage: http://gitorious.org/gitorious/seuss
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: when
+rubygems_version: 1.4.2
+signing_key: 
+specification_version: 3
+summary: A Ruby implementation of the wonderful when.js promise library
+test_files: []
+