I'm not smart enough to understand documentation

[Anton Kudris]

Hello!

I know it should be easy, but I can't get it how to do stuff with deferreds. I understand and use only the simplest form like 

var someAsyncFunc = function( params ) {
  var def = deferred();

  any_async_stuff_here( params, function( err, data ) {
    if ( err ) { 
      def.resolve( err );
    }

    def.resolve( data );
  })

  return def.promise();
}

someAsyncFunc( params ).then( function( data ){ 
   //.. process data here
}

But I don't understand how to make a little bit more complex stuff.
For example, I'd like to run callback when 2 different async functions resolves; Like I would do it with some other promise libs:

when( asyncFunc1( ),  asyncFunc2( )).then( function( data1, data2 ) {
 // run callback here or process data
}); 

how would I do this with deferred? Am I supposed to use .aside ?
Please provide more examples for dumb users like me :)

[Mariusz Nowak]

Anton, yes deferred unfortunately lack step by step documentation/tutorial. I have in mind one and plan to write it, but some other commitments on the way take my time for now.

Anway it's totally understood and ok to ask even dumbest questions on this mailing list :)

On Sunday, January 20, 2013 1:44:16 PM UTC+1, Anton Kudris wrote:

For example, I'd like to run callback when 2 different async functions resolves; Like I would do it with some other promise libs:

when( asyncFunc1( ),  asyncFunc2( )).then( function( data1, data2 ) {
 // run callback here or process data
}); 

how would I do this with deferred? Am I supposed to use .aside ?
Please provide more examples for dumb users like me :)

Main deferred function does that, it returns promise that resolves when all passed arguments are resolved, so:

deferred(promise1, promise2).then(function (result) {

  var resultOfPromise1 = result[0];

  var resultOfPromise2 = result[1];

}).end();

It's kind of documented: https://github.com/medikoo/deferred#grouping-promises ;-)

If you prefer, you may also spread result across arguments of callback with help of match extension:

deferred(promise1, promise2).match(function (resultOfPromise1, resultOfPromise2) {

}).end();

If it's final operation and you don't wish to extend promise chain, you should (highly advised) to use 'end' instead of then.

Then you also don't need to end chain with empty end() call:

deferred(promise1, promise2).end(function (result) {

  var resultOfPromise1 = result[0];

  var resultOfPromise2 = result[1];

});

Just side note: with deferred v0.7 'end' might be renamed to 'done', as it's how some other libraries picked that up.

[Anton Kudris]

Thanks for a quick reply! 

It appears that current documentation is OK if ones to read it carefully. I must have missed somehow #grouping-promises section. Thanks for pointing on it, that was exactly what I needed.

If I don't really chain promises do I still better use "end" instead of "then" ? 

--
 
 

--
Anton Kudris

[Mariusz Nowak]

Yes, you should only use `then` if you *need* promise that is a result of `then`, otherwise use `end` or `aside`.

It's important cause of error handling, `then` while extending chain intercepts any errors that may occur in callback, If you don't handle them, then they're silent which is dangerours, e.g.:

promise.then(function (result) {

  throw new Error('Error');
});

Error is silenced and becomes a value of promise returned by `then`, if you leave it like then, you'll never know about it. To expose it you should run `end` on returned promise:

promise.then(function (result) {

  throw new Error('Error');
}).end();

Ok, error thrown, but, still it's much better to use `end` right away, instead of `then` and `end`:

promise.end(function (result) {

  throw new Error('Error');
});

Error thrown. Going that way you don't create promises you don't need and you're assured that all unhandled errors are exposed, which is very important.

[Rishav Sharan]

I'd say, more important than documentation are some examples. maybe someone can add a folder of examples to the git?

[Mariusz Nowak]

I thought about collecting example solutions to some most common problems on Wiki (it might be also in repo), I'll try to fix that soon. First good example already starts the documentation.

Anyway also this mail list was opened to serve such purpose. If someone struggles with some flow, *please post it on this mail list*, I'll be more than happy to guide and explain in detail how it can be solved with deferred, this way it may grow as rich list of (not just theoretical, but real world) examples and great complement to the documentation.