async conversions

[jbenet]

Some conversions will be async, for example us-street-address-to-us-city will use node-geocoder. The Api needs to move from

var conversion = transformer('typeA', 'typeB');
var dataB = conversion(dataA);

to

var conversion = transformer('typeA', 'typeB');
conversion(dataA, function(dataB) {
  // ...
});

(Unless fibers are used).

[jbenet]

Done, now all async.

[jbenet]

Damn. switching to conversions broke the nice api. can no longer do:

var transformer = require('dat-transformer');
var iso2js = transformer('iso-date', 'js-date');
console.log(iso2js('2014-04-26T12:02:23.000Z'));

Now have to do

var transformer = require('dat-transformer');
var iso2js = transformer('iso-date', 'js-date');
return iso2js('2014-04-26T12:02:23.000Z', function(err, out) {
  console.log(out);
});

Which really sucks for simple things. I may not be the best thing to force all conversions to be async. The problem is some have to, and detecting + composing sync + async correctly will get complicated.

Maybe promises is the right thing to do here (ew).

[jbenet]

Or having an optimistic sync call that only resolves sync conversions.

[jbenet]

Basically, make both of these possible:

var transformer = require('dat-transformer');
var iso2js = transformer.sync('iso-date', 'js-date');
console.log(iso2js('2014-04-26T12:02:23.000Z'));

var transformer = require('dat-transformer');
var iso2js = transformer.async('iso-date', 'js-date');
iso2js('2014-04-26T12:02:23.000Z', function(err, out) {
  console.log(out);
});

[jbenet]

Ok, so this interface now works. Supports:

• both sync and async conversions work!
• no forcing async for simple sync things.
• differentiate the context directly in api: transformer.sync and transformer.async (transformer defaults to sync.)
• loading any async conversion in sync context will immediately throw error (programmer error)
• using sync in async context works nicely (async wrapper)
• in async context, auto-defers (process.nextTick) callbacks since users won't.
• in async context, all callbacks have callback(err, output) signature
• conversions compose with transformer.{sync,async}.compose (tricky in async context, as conversion and callback signatures differ: conversion(input, callback) and callback(err, output)).
• nice error output immediately upon loading an async conversion that doesn't conform:

Error: async conversion foo-to-bar should take 2 args (input, callback):
function convert(foo) {
  return 'bar';
}

• similarly for sync:

Error: sync conversion foo-to-bar should take 1 arg (input):
function convert(foo, callback) {
  return 'bar';
}

(thanks for the help @mafintosh @maxogden @groundwater!)

[groundwater]

:+1: glad to have helped