JSON-LD API w/DOM Futures implemented

Hi all,

I've updated jsonld.js ( https://github.com/digitalbazaar/jsonld.js) and 
the playground on json-ld.org (json-ld.org/playground) to use the new 
JSON-LD API that utilizes DOM Futures. The DOM Futures implementation 
was provided by Alex Russell here ( 
https://github.com/slightlyoff/DOMFuture).

The WebIDL test (http://json-ld.org/test-suite/idltest/) fails 3 
additional tests now (more than it failed before). The reason for these 
failures is that it's unclear how exceptions should be raised by a 
WebIDL function that returns a Future. It could be that there is a bug 
in the test harness code -- and it should be trying to resolve the 
returned Future and look for an error there, instead of trying to catch 
one. Hopefully, this is the case.

If the function is actually meant to throw an exception, then this may 
be a little bit of a mess for implementations that wrap APIs that use 
continuation-passing style callbacks. The reason for this is that 
callback-based APIs will raise the error as the first parameter of the 
callback, they will not throw them. In other words, they will happen 
asynchronously -- and not be caught by the test harness' try/catch. This 
would be a general problem for developers that attempt to reuse existing 
libraries that are callback-based by wrapping them to use Futures. Maybe 
the problem would be limited in scope, I'm not sure.

Whilst making changes to support Futures, I ran into a few other 
problems that make wrapping callback-based APIs a little more difficult 
than I had hoped. The most annoying was that Futures can only "resolve" 
to a single value, meaning that their "success" callbacks can only 
receive a single value. A number of popular node.js libraries pass 
multiple values to their callbacks; in order to deal with this, you must 
either treat each call on a case-by-case basis (wrapping them 
differently) or you must always box node.js callback arguments into an 
array using one wrapper and then unbox them using another wrapper before 
you're able to get back to writing useful code. In other words, the 
boilerplate for getting things into a form you may be used to working 
with is more verbose than I had hoped. I brought this up on 
www-dom@w3.org ( 
http://lists.w3.org/Archives/Public/www-dom/2013AprJun/0057.html), but 
so far, at least, it seems that Futures/Promises proponents would not 
support a change to allow multiple values to be passed to the success 
callback ... because it represents a departure from a more perfect 
analogy to synchronous programming. A desire to be able to use a new ES6 
'yield' feature in a consistent way was also cited.

In any case, the first implementation of the JSON-LD API using Futures 
is now live on the playground.

-Dave

-- 
Dave Longley
CTO
Digital Bazaar, Inc.