What is the difference in jQuery between returning deferred and deferred.promise()?

Question

I'm working in an ES5 environment using jQuery. I have some code as follows:

var saveGame = function (gameState, saveStars) {
  var deferred = $.Deferred();
  var starsSaved = saveStars ? false : true;

  model.game().saved(starsSaved);
  model.driveAccessInProgress(true);

  GW.manifest.saveGame(gameState).then(function () {
    model.driveAccessInProgress(false);
    deferred.resolve();
  });
  return deferred; // or deferred.promise()?
};

saveGame().then(/* more stuff */);

In this instance, whether I return deferred.promise() or just deferred the .then works as expected. Given this, I guess I'm a little unclear on what a promise is, and was wondering what the difference is between these two returns and when might it matter?

Answer 1

You want to return deferred.promise() so that the calling code can't call resolve or reject or other Deferred-specific methods. That's not something the caller should have access to. It should only be able to consume the promise, not affect its state. You can read the documentation as well .

Answer 2

You would return deferred.promise().

But it looks like saveGame(gameState) already returns a Promise so you shouldn't use $.Deferred here at all.

var saveGame = function (gameState, saveStars) {
  var starsSaved = saveStars ? false : true;

  model.game().saved(starsSaved);
  model.driveAccessInProgress(true);

  return GW.manifest.saveGame(gameState).then(function () {
    model.driveAccessInProgress(false);
  });
};

saveGame().then(/* more stuff */);

Having already a Promise and creating a new one using $.Deferred is an anti-pattern. the reason for this is that you might easily forget certain cases and your code might get stuck on such a point.

What if e.g. GW.manifest.saveGame(gameState) fails? You don't consider that case so you would need to add a .catch:

  GW.manifest.saveGame(gameState).then(function () {
    model.driveAccessInProgress(false);
    deferred.resolve();
  })
  .catch(function(err) {
    deferred.resolve(err);
  })

And there might be other cases as well.