Add getIdsToFetch to RelationalModel. Ref #463

Author: PaulUithol

backbone-relational.js

@@ -1358,12 +1358,36 @@
 			return _.values( this._relations );
 		},
 
+
+		/**
+		 * Get a list of ids that will be fetched on a call to `fetchRelated`.
+		 * @param {string|Backbone.Relation} key The relation key to fetch models for.
+		 * @param [refresh=false] Add ids for models that are already in the relation, refreshing them?
+		 * @return {Array} An array of ids that need to be fetched.
+		 */
+		getIdsToFetch: function( key, refresh ) {
+			var rel = key instanceof Backbone.Relation ? key : this.getRelation( key ),
+				ids = rel ? ( rel.keyIds && rel.keyIds.slice( 0 ) ) || ( ( rel.keyId || rel.keyId === 0 ) ? [ rel.keyId ] : [] ) : [];
+
+			// On `refresh`, add the ids for current models in the relation to `idsToFetch`
+			if ( refresh ) {
+				var models = rel.related && ( rel.related.models || [ rel.related ] );
+				_.each( models, function( model ) {
+					if ( model.id || model.id === 0 ) {
+						ids.push( model.id );
+					}
+				});
+			}
+
+			return ids;
+		},
+
 		/**
 		 * Retrieve related objects.
 		 * @param {string} key The relation key to fetch models for.
 		 * @param {Object} [options] Options for 'Backbone.Model.fetch' and 'Backbone.sync'.
 		 * @param {Boolean} [refresh=false] Fetch existing models from the server as well (in order to update them).
-		 * @return {jQuery.when[]} An array of request objects
+		 * @return {jQuery.when[]} An array of request objects.
 		 */
 		fetchRelated: function( key, options, refresh ) {
 			// Set default `options` for fetch
@@ -1373,17 +1397,7 @@
 				setUrl,
 				requests = [],
 				rel = this.getRelation( key ),
-				idsToFetch = rel && ( ( rel.keyIds && rel.keyIds.slice( 0 ) ) || ( ( rel.keyId || rel.keyId === 0 ) ? [ rel.keyId ] : [] ) );
-
-			// On `refresh`, add the ids for current models in the relation to `idsToFetch`
-			if ( refresh ) {
-				models = rel.related instanceof Backbone.Collection ? rel.related.models : [ rel.related ];
-				_.each( models, function( model ) {
-					if ( model.id || model.id === 0 ) {
-						idsToFetch.push( model.id );
-					}
-				});
-			}
+				idsToFetch = rel && this.getIdsToFetch( rel, refresh );
 
 			if ( idsToFetch && idsToFetch.length ) {
 				// Find (or create) a model for each one that is to be fetched

index.html

@@ -72,6 +72,7 @@
 	<ul>
 		<li><a href="#RelationalModel-getRelation">getRelation</a></li>
 		<li><a href="#RelationalModel-getRelations">getRelations</a></li>
+		<li><a href="#RelationalModel-getIdsToFetch">getIdsToFetch</a></li>
 		<li><a href="#RelationalModel-fetchRelated">fetchRelated</a></li>
 		<li><a href="#RelationalModel-set">set</a></li>
 		<li><a href="#RelationalModel-toJSON">toJSON</a></li>
@@ -297,6 +298,7 @@ <h2>
 			<li><a href="#RelationalModel-build">build</a></li>
 			<li><a href="#RelationalModel-findOrCreate">findOrCreate</a></li>
 			<li><a href="#RelationalModel-find">find</a></li>
+			<li><a href="#RelationalModel-findModel">findModel</a></li>
 		</ul>
 
 		<h3 id="RelationalModel-properties">
@@ -777,12 +779,21 @@ <h4 class="code">
 			</p>
 		</section>
 
+		<section id="RelationalModel-getIdsToFetch">
+			<h4 class="code">
+				getRelations<code>relationModel.getIdsToFetch(key&lt;string|Backbone.Relation&gt;, )</code>
+			</h4>
+			<p>
+				Returns: <q>Array</q> A list of the ids that will be fetched when calling `fetchRelated`.
+			</p>
+		</section>
+
 		<section id="RelationalModel-fetchRelated">
 			<h4 class="code">
-				fetchRelated<code>relationalModel.fetchRelated(key&lt;string&gt;, [options&lt;object&gt;], [update&lt;boolean&gt;])</code>
+				fetchRelated<code>relationalModel.fetchRelated(key&lt;string&gt;, [options&lt;object&gt;], [refresh&lt;boolean&gt;])</code>
 			</h4>
 			<p>
-				Returns: <q>deferred[]</q> An array of request objects.
+				Returns: <q>deferred[]</q> An array of (zero or more) request objects.
 			</p>
 			<p>
 				Fetch models from the server that were referenced in the model's attributes, but have not been found/created yet.
@@ -939,7 +950,7 @@ <h4 class="code">
 		<section id="RelationalModel-find">
 			<h4 class="code">
 				find
-				<code>relationalModel.findOrCreate(attributes&lt;string|number|object&gt;, [options&lt;object&gt;])</code>
+				<code>relationalModel.find(attributes&lt;string|number|object&gt;, [options&lt;object&gt;])</code>
 			</h4>
 			<p>
 				Returns: <q>Backbone.RelationalModel</q> A model instance.
@@ -1238,6 +1249,11 @@ <h4>Master
 				<a href="https://raw.github.com/PaulUithol/Backbone-relational/master/backbone-relational.js">download</a>
 			</small>
 		</h4>
+		<ul>
+			<li>
+				Add `getIdsToFetch` to `Backbone.RelationalModel`.
+			</li>
+		</ul>
 
 		<h4>0.8.8
 			<small>

test/tests.js

@@ -955,6 +955,9 @@ $(document).ready(function() {
 				resource_uri: 'person-10',
 				user: 'user-10'
 			});
+
+			var idsToFetch = person.getIdsToFetch( 'user' );
+			deepEqual( idsToFetch, [ 'user-10' ] );
 
 			var requests = person.fetchRelated( 'user', { error: function() {
 					errorCount++;
@@ -987,6 +990,9 @@ $(document).ready(function() {
 			var zoo = new Zoo({
 				animals: [ { id: 'monkey-1' }, 'lion-1', 'zebra-1' ]
 			});
+
+			var idsToFetch = zoo.getIdsToFetch( 'animals' );
+			deepEqual( idsToFetch, [ 'lion-1', 'zebra-1' ] );
 
 			//
 			// Case 1: separate requests for each model
@@ -996,7 +1002,7 @@ $(document).ready(function() {
 			equal( requests.length, 2, "Two requests have been made (a separate one for each animal)" );
 			equal( zoo.get( 'animals' ).length, 3, "Three animals in the zoo" );
 
-			// Triggering the 'error' callback for a request should destroy the model
+			// Triggering the 'error' callback for one request should destroy the model
 			requests[ 0 ].error();
 			// Trigger the 'success' callback on the `destroy` call to fire the 'destroy' event
 			_.last( window.requests ).success();