Merge pull request #39 from pschlette/save-resolves-when-all-dependents-resolve

JJModels now return a Deferred object that resolves when every dependent...

Author: sarink

README.md

@@ -38,10 +38,11 @@ Backbone JJRelational has been tested with Backbone 1.0.0 and Underscore 1.5.0
 <a name="installation" /> 
 ## Installation
 
-Backbone JJRelational depends - who would have thought - on [Backbone.JS](https://github.com/documentcloud/backbone) and [Underscore.JS](https://github.com/documentcloud/underscore).  
-Simply include backbone.JJRelational.js right after Underscore and Backbone.
+Backbone JJRelational depends - who would have thought - on [Backbone.JS](https://github.com/documentcloud/backbone), [Underscore.JS](https://github.com/documentcloud/underscore) and [jQuery](https://github.com/jquery/jquery).  
+Simply include backbone.JJRelational.js right after jQuery, Underscore and Backbone.
 
 ```html
+<script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="underscore.js"></script>
 <script type="text/javascript" src="backbone.js"></script>
 <script type="text/javascript" src="backbone.JJRelational.js"></script>
@@ -313,6 +314,8 @@ When you call `save` on a `Backbone.JJRelationalModel`, it will walk through tha
 
 Assume that a Store `has_many` Products, and Product `has_one` Store. You call `store.save()` ... So the Store will save itself first. After this completes, the Product's `save` will be called.
 
+The Deferred object returned by `save` won't be resolved until all of the model's dependent models have finished saving too.
+
 It should be noted that these related models will only be saved before/after if the model `isNew()`. If these are existing models, then you should save them each yourself individually.
 
 You should also be aware that `save` will inevitably call `set()` on the response returned from the server, and so the usual backbone set options apply. Please read the backbone docs on how to use the `add`, `remove`, and `merge` options. In some cases, you'll probably want to pass these to `save`, which will in turn pass them through to `set`.

backbone.JJRelational.coffee

@@ -347,16 +347,26 @@ do () ->
 
         if options.parse is undefined then options.parse = true
 
+        # Set up chain of deferreds to save each 'after' model.
+        # If we encounter a model that's not new, we'll simply return a Deferred that's already resolved as a sort of no-op.
+        # afterSuccess is resolved in the success handler of the model to kick off this process.
+        afterSuccess = new Backbone.$.Deferred();
+
+        latestSuccess = afterSuccess;
+        generateSuccessHandler = (model) =>
+          () =>
+            if model.isNew()
+              return model.save({}, _.extend({}, origOptions))
+            else
+              d = new Backbone.$.Deferred()
+              d.resolve()
+              return d
+          
+        for relModel in relModelsToSaveAfter
+          latestSuccess = latestSuccess.then generateSuccessHandler(relModel)
+
         options.success = (resp, status, xhr) =>
-          # we're in the actualSave success function, so now let's invoke a save on our "after" models
-          # the success callback we're going to pass is this function, so the next model in the relModelsToSaveAfter list
-          # won't be saved until the previous model has finished saving itself and all of its before/after dependencies
-          # we could probably analyze this dependency graph more to be more performant...maybe someday.
-          saveRelModelsAfterSuccess = =>
-            if relModelsToSaveAfter.length > 0
-              relModel = relModelsToSaveAfter.shift()
-              if relModel.isNew() then relModel.save({}, _.extend({}, origOptions, {success: saveRelModelsAfterSuccess}))
-          saveRelModelsAfterSuccess()
+          afterSuccess.resolve()
 
           # Ensure attribtues are restored during synchronous saves
           @attributes = attributes
@@ -379,7 +389,8 @@ do () ->
         # Restore attributes
         if attrs and options.wait then @.attributes = attributes
 
-        xhr
+        # Yield a Deferred that will be resolved when every model has been updated
+        latestSuccess
 
       # Okay, so here's actually happening it. When we're saving - and a model in a relation is not yet saved
       # we have to save the related model first. Only then can we save our actual model.