RE: JSON-LD API w/DOM Futures implemented

On Thursday, April 25, 2013 12:11 AM, Dave Longley wrote:

> 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).

Great, I haven't been aware of that implementation.


> 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.

I've fixed all but one failing test (the stringification of
JsonLdProcessor.prototype still fails).

I think you refer to the three that check the parameters. I believe that's
an error in your implementation. If you have a function like

   Future expand (JsonLdInput input, optional JsonLdOptions options);

and you call it without any parameters (expand()) it should throw an
TypeError instead of returning a Future. You have to keep in mind that these
things will most of the time be implemented in C++. You can't just omit a
parameter in that case.

I've updated the playground and also filed a PR for jsonld.js
(https://github.com/digitalbazaar/jsonld.js/pull/26)


> 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.

It's a different situation if you wrap an existing implementation by just
passing it to the Future's constructor or whether you define a method that
returns a Future. If you define a method that returns a Future it should
throw an exception if the method signature is not respected. It's a special
case for JavaScript because it doesn't check the parameters but almost all
other languages will do and you don't even enter the method in that case.


> 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.

Yeah.. a Future represents the return value of a function which has not yet
been completed. If you need more values you need to wrap them in an array or
dictionary.


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

Awesome.. and it now passes 15 of the 16 tests. Do you think it would make
sense to extend the this test suite to include all other JSON-LD tests and
to automatically generate the implementation report? This could then be used
to verify JSON-LD API Implementations.

I think it would be quite simple to port the tests you already have to
testharness.js. The doc is here:
http://darobin.github.io/test-harness-tutorial/docs/using-testharness.html



--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 25 April 2013 09:09:14 UTC