JJModels now return a Deferred object that resolves when every dependent model has finished saving (instead of when the first model finishes saving). Update README with information about dependency on jQuery and changes to save().

Author: Pete Schlette

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.