conversion callback api - deferring

[jbenet]

Callbacks should always be deferred. See:

• http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony
• http://blog.ometer.com/2011/07/24/callbacks-synchronous-and-asynchronous/

https://github.com/jbenet/transformer/commit/8b2349a makes this happen, by deferring in the conversion callback wrapper. So now, whether a user defers or not, the callback is deferred. Remaining question is whether to make users defer anyway.

module.exports = Conversion(Ascii, Base32, convert);
function convert(ascii, callback) {
  callback(base32.encode(ascii));
};

is nicer than

var defer = // defer implementation
module.exports = Conversion(Ascii, Base32, convert);
function convert(ascii, callback) {
  defer(callback, base32.encode(ascii));
};

As mentioned above, they both do the same now. One is "more right" because deferring is what should happen, so it's easier to know it's happening when you do it up-front. The other is more concise.

IMO it's kind of annoying to force users to do the latter, if we can handle it correctly in either case.

[jbenet]

former. conversion wrappers automatically defers just in case.

• https://github.com/jbenet/transformer/blob/e71011a/js/conversion.js#L222-224
• https://github.com/jbenet/transformer/blob/e71011a/js/apiAsync.js#L75-77

[jbenet]

11