promise.rb 0.4.0 → 0.5.0

data/.travis.yml

@@ -2,7 +2,7 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
-  - jruby-19mode
+  - jruby
   - rbx
   - ruby-head
   - jruby-head
@@ -10,4 +10,5 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
+  fast_finish: true
 script: bundle exec rake -t metrics:coverage ci

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # promise.rb changelog
 
+## 0.5.0 (December 16, 2013)
+
+* Fulfillment value and rejection reason are no longer being frozen
+* Rejection reason always gets a sensible backtrace now
+* Have pending specs for deviations from the A+ spec
+
 ## 0.4.0 (December 13, 2013)
 
 * Disclaiming my copyright, promise.rb is now in the Public Domain

data/README.md

@@ -6,15 +6,14 @@ Ruby implementation of the [Promises/A+ spec](http://promisesaplus.com/).
 Similar projects:
 
 - [concurrent-ruby](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md), Promises/A(+) implementation, thread based
+- [ruby-thread](https://github.com/meh/ruby-thread), thread/mutex/condition variable based, thread safe
 - [promise](https://github.com/bhuga/promising-future), a.k.a. promising-future, classic promises and futures, thread based
 - [celluloid-promise](https://github.com/cotag/celluloid-promise), inspired by Q, backed by a Celluloid actor
 - [em-promise](https://github.com/cotag/em-promise), inspired by Q, backed by an EventMachine reactor
 - [futuristic](https://github.com/seanlilmateus/futuristic), MacRuby bindings for Grand Central Dispatch
 - [methodmissing/promise](https://github.com/methodmissing/promise), thread based, abandoned
 
-## Todo
-
-- test with https://gist.github.com/joeljackson/5722487
+*Note that promise.rb is probably not thread safe.*
 
 ## Installation
 
@@ -81,6 +80,8 @@ end
 failing_stuff.then(proc { |value| }, proc { |reason| p reason })
 ```
 
+### Waiting for fulfillment/rejection
+
 promise.rb also comes with the utility method `Promise#sync`, which waits for
 the promise to be fulfilled and returns the value, or for it to be rejected and
 re-raises the reason. Using `#sync` requires you to implement `#wait`. You could
@@ -127,6 +128,28 @@ end.resume
 promise.reject(MyError.new)
 ```
 
+### Chaining promises
+
+As per the A+ spec, every call to `#then` returns a new promise, which assumes
+the first promise's state. That means it passes its `#fulfill` and `#reject`
+methods to first promise's `#then`, shortcircuiting the two promises. In case
+a callback returns a promise, it'll instead assume that promise's state.
+
+Imagine the `#fulfill` and `#reject` calls in the following example happening
+somewhere in a background Fiber or so.
+
+```ruby
+require 'promise'
+
+Promise.new
+  .tap(&:fulfill)
+  .then { Promise.new.tap(&:fulfill) }
+  .then { Promise.new.tap(&:reject) }
+  .then(nil, proc { |reason| p reason })
+```
+
+### Progress callbacks
+
 Very simple progress callbacks, as per Promises/A, are supported as well. They have been dropped in A+, but I found them to be a useful mechanism - if kept simple. Callback dispatch happens immediately in the call to `#progress`, in the order of definition via `#on_progress`. Also note that `#on_progress` does not return a new promise for chaining - the progress mechanism is meant to be very lightweight, and ignores many of the constraints and guarantees of `then`.
 
 ```ruby

data/Rakefile

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require "bundler/gem_tasks"
+task :default => 'ci:metrics'
 
 # Added by devtools
 require 'devtools'

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
 threshold: 10
-total_score: 49
+total_score: 50

data/config/reek.yml

@@ -57,7 +57,7 @@ TooManyInstanceVariables:
 TooManyMethods:
   enabled: true
   exclude: []
-  max_methods: 13
+  max_methods: 14
 TooManyStatements:
   enabled: true
   exclude:

data/lib/promise.rb

@@ -49,7 +49,8 @@ class Promise
     end
   end
 
-  def reject(reason = RuntimeError)
+  def reject(reason = nil)
+    reason = build_reason(reason || RuntimeError, caller)
     dispatch(@on_reject, reason) do
       @state = :rejected
       @reason = reason
@@ -68,7 +69,6 @@ class Promise
   def dispatch(callbacks, arg)
     if pending?
       yield
-      arg.freeze
       callbacks.each { |callback| dispatch!(callback, arg) }
     end
 
@@ -97,4 +97,10 @@ class Promise
   def defer
     yield
   end
+
+  def build_reason(reason, backtrace)
+    reason = reason.new if reason.respond_to?(:new)
+    reason.set_backtrace(backtrace) unless reason.backtrace
+    reason
+  end
 end

data/lib/promise/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 class Promise
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/spec/promise_spec.rb

@@ -7,11 +7,13 @@ describe Promise do
 
   let(:value) { double('value') }
   let(:other_value) { double('other_value') }
+
+  let(:backtrace) { caller }
   let(:reason) do
-    StandardError.new('reason').tap { |ex| ex.set_backtrace(caller) }
+    StandardError.new('reason').tap { |ex| ex.set_backtrace(backtrace) }
   end
   let(:other_reason) do
-    StandardError.new('other_reason').tap { |ex| ex.set_backtrace(caller) }
+    StandardError.new('other_reason').tap { |ex| ex.set_backtrace(backtrace) }
   end
 
   describe '3.1.1 pending' do
@@ -33,14 +35,16 @@ describe Promise do
       expect(subject).to be_fulfilled
     end
 
-    it 'has an immutable value' do
+    it 'has a value' do
       subject.fulfill(value)
       expect(subject.value).to eq(value)
 
       subject.fulfill(other_value)
       expect(subject.value).to eq(value)
+    end
 
-      expect(subject.value).to be_frozen
+    it 'freezes the value' do
+      pending 'Dropped in 74da6e9'
     end
   end
 
@@ -51,14 +55,16 @@ describe Promise do
       expect(subject).to be_rejected
     end
 
-    it 'has an immutable reason' do
+    it 'has a reason' do
       subject.reject(reason)
       expect(subject.reason).to eq(reason)
 
       subject.reject(other_reason)
       expect(subject.reason).to eq(reason)
+    end
 
-      expect(subject.reason).to be_frozen
+    it 'freezes the reason' do
+      pending 'Dropped in 74da6e9'
     end
   end
 
@@ -164,7 +170,7 @@ describe Promise do
 
   describe '3.2.4' do
     it 'returns before on_fulfill or on_reject is called' do
-      pending
+      pending 'To be implemented by application code'
     end
   end
 
@@ -358,7 +364,29 @@ describe Promise do
 
     it 'does not require a reason' do
       subject.reject
-      expect(subject.reason).to be(RuntimeError)
+      expect(subject.reason).to be_a(RuntimeError)
+    end
+
+    it 'allows nil reason' do
+      subject.reject(nil)
+      expect(subject.reason).to be_a(RuntimeError)
+    end
+
+    it 'sets the backtrace' do
+      subject.reject
+      expect(subject.reason.backtrace[0])
+        .to include(__FILE__ + ':' + (__LINE__ - 2).to_s)
+    end
+
+    it 'does not override backtrace' do
+      subject.reject(reason)
+      expect(subject.reason.backtrace).to be(backtrace)
+    end
+
+    it 'builds exception object for custom error class' do
+      cls = Class.new(StandardError)
+      subject.reject(cls)
+      expect(subject.reason).to be_a(cls)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: promise.rb
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-12 00:00:00.000000000 Z
+date: 2013-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec