pure_promise 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3a89eec90f03fb3f8769db7778d3996f489e2390
+  data.tar.gz: 992aad1bb58162a030f5e0a11b2e5f378e5d4065
+SHA512:
+  metadata.gz: 20942612cb7d93992b621d962b01c8380d7805657e8d6004cb3f00965342e26b1f36e6f6c37558abd945a6b32c713d13ab9bb74df5f551b14b8e3e10943fb437
+  data.tar.gz: c5b903a596095ce5524f04f313fa5c6f6fe033776c528e7f99c169211880b2a51f60887d211873723d62e382e3772ef9776794d93bcc750907f04fd6b1cd7c97

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+rvm:
+  - 1.9
+  - 2.0
+  - 2.1
+  - jruby
+  - rbx-2.1
+  - rbx-2.2
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+  fast_finish: true
+before_install:
+  - gem install bundler
+install: bundle install --jobs=1 --retry=3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pure_promise.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Cameron Martin
+
+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,172 @@
+[![Build Status](https://travis-ci.org/cameron-martin/pure_promise.svg?branch=master)](https://travis-ci.org/cameron-martin/pure_promise)
+
+# PurePromise
+
+My promises library. It tries to be as close to the Promises/A+ spec as possible, with one exception:
+
+__A promise callback _must_ return a promise__
+
+This makes it slightly more verbose, but it has some nice properties. I'll explain them here later.
+
+Influenced by [promise.rb][2], the [Promises/A+ spec][3], and browsers' implementations of promises (for the stuff that's not `#then`).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pure_promise'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pure_promise
+
+## Usage
+
+### Making them asynchronous
+
+Note: The defer method does not have to yield in the order in which defer was called,
+it just has to yield some time in the future.
+
+```ruby
+class EMPromise < PurePromise
+  def defer
+    EM.next_tick { yield }
+  end
+end
+```
+
+### Creating promises
+
+```ruby
+# Create a fulfilled promise
+PurePromise.fulfill(:value)
+PurePromise.fulfill
+
+# Create a rejected promise
+PurePromise.reject(:value)
+PurePromise.reject
+
+# Create a pending promise
+PurePromise.new
+
+# Create a promise which fulfills or rejects when fulfill or reject are called.
+PurePromise.new do |fulfill, reject|
+  if something?
+    fulfill.call(:value)
+  else
+    reject.call(:error)
+  end
+end
+
+# Create a promise with fulfills/rejects when thenable fulfills/rejects
+PurePromise.resolve(thenable)
+
+# Create a promise which is rejected to an exception object, with backtrace properly set.
+PurePromise.error # #<RuntimeError: RuntimeError>
+PurePromise.error('message') # #<RuntimeError: message>
+PurePromise.error(TypeError, 'message') # #<TypeError: message>
+PurePromise.error(TypeError.new('message')) # #<TypeError: message>
+```
+
+### Mutating promises
+
+A promise can only be mutated once. Once it has transitioned from pending, the value cannot be changed.
+
+```ruby
+promise = Promise.new
+
+# It is recommended to pass a block to new for fulfilling and rejecting promises,
+# as this normally makes your code more clear
+promise.fulfill(:value)
+promise.reject(:value)
+
+# Make promise take on the form of thenable
+# This can be any object that implements a semi-compliant then method,
+# as described in the Promises/A+ spec
+promise.resolve(thenable)
+
+```
+
+### Accessing promises
+
+The only way to access a promise's value is through the then/catch methods.
+
+Each callback __must__ evaluate to a promise. If the action in the callback succeeds, return `PurePromise.fulfill`,
+otherwise return `PurePromise.reject`.
+
+`then` and `catch` always return a promise, which fulfills or rejects to the value of the promise returned from the callback when it is executed.
+
+If a callback raises an error, the promise returned by `then` or `catch` will be rejected with the error as the value.
+
+```ruby
+
+# Attach a fulfillment callback
+PurePromise.fulfill(:some_value).then do |value|
+  puts value.inspect
+  PurePromise.fulfill
+end
+# :some_value
+
+# Attach a rejection callback
+PurePromise.error.catch do |error|
+  puts error.inspect
+  PurePromise.fulfill
+end
+# #<RuntimeError: RuntimeError>
+
+# Attach both
+PurePromise.fulfill(:some_value).then(proc { |value|
+  puts value.inspect
+  PurePromise.fulfill
+}, proc { |error|
+  puts error.inspect
+  PurePromise.fulfill
+})
+
+```
+
+## Shortcomings addressed
+
+This isn't having a dig at anyone else's work, these are just the reasons why I wanted to create my own promises library.
+I could have got a lot of things wrong too, and I'd love to hear about them in the issues section.
+
+### In Promises/A+ Spec
+
+* You cannot wrap anything that implements a `then` method in a promise.
+  This bit me when wanting to pass around a [faye client][1] in a promise system - and it took me forever to debug.
+  PurePromise addresses this by forcing you to return a promise from your callbacks.
+
+### In Promise.rb
+
+* IMO, being able to retrieve the value of the promise through an accessor is wrong.
+  What do you return when the promise is pending and _has no value_? Nil? But nil is a valid value for a promise,
+  creating ambiguity.
+
+## Design goals
+* Address the above shortcomings.
+* Limit the public api to as small as possible (then, fulfill, reject, resolve).
+  Everything else should just be convenience methods on top of these.
+
+## TODO
+
+* DRY up specs; they are pretty verbose atm.
+* Get 100% mutation coverage
+* Release gem
+
+## Contributing
+
+1. Fork it ( https://github.com/cameron-martin/pure_promise/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+[1]: http://faye.jcoglan.com/browser.html
+[2]: https://github.com/lgierth/promise.rb
+[3]: http://promisesaplus.com/

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/pure_promise.rb

@@ -0,0 +1,135 @@
+require 'pure_promise/callback'
+require 'pure_promise/coercer'
+
+class PurePromise
+
+  MutationError = Class.new(RuntimeError)
+
+  class << self
+    extend Forwardable
+
+    def_delegators :new, :fulfill, :reject, :resolve
+
+    # TODO: Clean this up, it's pretty messy.
+    def error(message_or_exception=nil, message=nil, backtrace=nil)
+      backtrace ||= caller(2) # Fix for jRuby - See https://github.com/jruby/jruby/issues/1908
+      if message_or_exception.respond_to?(:exception)
+        exception = message_or_exception.exception(message || message_or_exception)
+      else
+        exception = RuntimeError.new(message_or_exception)
+      end
+      exception.set_backtrace(backtrace)
+      reject(exception)
+    end
+  end
+
+  def initialize
+    @state = :pending # Pending/fulfilled/rejected
+    @callbacks = []
+
+    yield method(:fulfill), method(:reject) if block_given?
+  end
+
+  # REVIEW: Consider having two callback chains, to avoid having potentially expensive null_callbacks littering @callbacks
+  def then(fulfill_callback=null_callback, reject_callback=null_callback, &block)
+    fulfill_callback = block if block
+    self.class.new.tap do |return_promise|
+      register_callbacks(
+          Callback.new(fulfill_callback, return_promise),
+          Callback.new(reject_callback, return_promise)
+      )
+    end
+  end
+
+  def catch(&block)
+    self.then(null_callback, block || null_callback)
+  end
+
+  def fulfill(value=nil)
+    mutate_state(:fulfilled, value, @callbacks.map(&:first))
+  end
+
+  def reject(value=nil)
+    mutate_state(:rejected, value, @callbacks.map(&:last))
+  end
+
+  # TODO: Rename method to:
+  # receive?
+  # acquire?
+  # take?
+  def resolve(promise)
+    if equal?(promise)
+      raise TypeError, 'Promise cannot be resolved to itself'
+    elsif Coercer.is_thenable?(promise)
+      Coercer.coerce(promise, self.class).resolve_into(self)
+      self
+    else
+      raise TypeError, 'Argument is not a promise'
+    end
+  end
+
+  def resolve_into(pure_promise)
+    raise TypeError, 'Argument must be of same type as self' unless pure_promise.instance_of?(self.class)
+
+    if fulfilled?
+      pure_promise.fulfill(@value)
+    elsif rejected?
+      pure_promise.reject(@value)
+    else
+      self.then(pure_promise.method(:fulfill), pure_promise.method(:reject))
+    end
+    self
+  end
+
+private
+
+  def defer
+    yield
+  end
+
+  def mutate_state(state, value, callbacks)
+    raise MutationError, 'You can only mutate pending promises' unless pending?
+
+    @state = state
+    @value = value
+
+    run_callbacks(callbacks)
+    # TODO: Find a way of testing this - It makes no visible changes, apart from clearing some memory.
+    @callbacks.clear
+
+    self
+  end
+
+  def register_callbacks(fulfill_callback, reject_callback)
+    if fulfilled?
+      defer { fulfill_callback.call(@value) }
+    elsif rejected?
+      defer { reject_callback.call(@value) }
+    else
+      @callbacks << [fulfill_callback, reject_callback]
+    end
+  end
+
+  # This ensures that all callbacks run in order, by setting up an execution chain like
+  # proc { defer { a.call; proc { defer { b.call; ... } }.call  } }.call
+  # You might think this is really slow by only running one callback per tick,
+  # but here are some benchmarks with eventmachine: https://gist.github.com/cameron-martin/08abeaeae1bf746ef718
+  #
+  # We do this because we do not want to require implementations of defer to execute blocks in the order they were registered.
+  def run_callbacks(callbacks)
+    callbacks.reverse.inject(proc{}) do |memo, callback|
+      proc { defer { callback.call(@value); memo.call } }
+    end.call
+  end
+
+  def null_callback
+    @null_callback ||= proc { self }
+  end
+
+  [:pending, :fulfilled, :rejected].each do |state|
+    define_method("#{state}?") do
+      @state.equal?(state)
+    end
+  end
+
+end

data/lib/pure_promise/callback.rb

@@ -0,0 +1,19 @@
+class PurePromise
+  class Callback
+
+    def initialize(callback, return_promise)
+      @callback = callback
+      @return_promise = return_promise
+    end
+
+    # TODO: Return a consistent value here. Nil? self?
+    def call(value)
+      return_value = @callback.call(value)
+    rescue Exception => error
+      @return_promise.reject(error)
+    else
+      @return_promise.resolve(return_value)
+    end
+
+  end
+end

data/lib/pure_promise/coercer.rb

@@ -0,0 +1,59 @@
+# This coerces a thenable into a PurePromise
+# I wanted to keep this separate because there are a lot of edge cases that need handling
+# if the thenable doesn't conform to the spec properly.
+
+class PurePromise
+  class Coercer
+
+    def self.is_thenable?(thenable)
+      thenable.respond_to?(:then)
+    end
+
+    def self.coerce(*args, &block)
+      new(*args, &block).coerce
+    end
+
+    def initialize(thenable, promise_class)
+      raise TypeError, 'Can only coerce a thenable' unless self.class.is_thenable?(thenable)
+      @thenable = thenable
+      @promise_class = promise_class
+    end
+
+    def coerce
+      return @thenable if @thenable.instance_of?(@promise_class)
+
+      @mutated = false
+      coerce_thenable
+    end
+
+  private
+
+    def coerce_thenable
+      @promise_class.new.tap do |promise|
+        begin
+          @thenable.then(
+              build_callback(promise, :fulfill),
+              build_callback(promise, :reject)
+          )
+        rescue Exception => error
+          mutate_promise { promise.reject(error) }
+        end
+      end
+    end
+
+    def build_callback(promise, method)
+      proc do |value|
+        mutate_promise { promise.public_send(method, value) }
+        promise
+      end
+    end
+
+    def mutate_promise
+      unless @mutated
+        yield
+        @mutated = true
+      end
+    end
+
+  end
+end