1 /**

     2  * Backbone-relational.js 0.6.0

     3  * (c) 2011 Paul Uithol

     4  * 

     5  * Backbone-relational may be freely distributed under the MIT license; see the accompanying LICENSE.txt.

     6  * For details and documentation: https://github.com/PaulUithol/Backbone-relational.

     7  * Depends on Backbone (and thus on Underscore as well): https://github.com/documentcloud/backbone.

     8  */

     9 ( function( undefined ) {

    10 	"use strict";

    11 	

    12 	/**

    13 	 * CommonJS shim

    14 	 **/

    15 	var _, Backbone, exports;

    16 	if ( typeof window === 'undefined' ) {

    17 		_ = require( 'underscore' );

    18 		Backbone = require( 'backbone' );

    19 		exports = module.exports = Backbone;

    20 	}

    21 	else {

    22 		_ = window._;

    23 		Backbone = window.Backbone;

    24 		exports = window;

    25 	}

    26 

    27 	Backbone.Relational = {

    28 		showWarnings: true

    29 	};

    30 

    31 	/**

    32 	 * Semaphore mixin; can be used as both binary and counting.

    33 	 **/

    34 	Backbone.Semaphore = {

    35 		_permitsAvailable: null,

    36 		_permitsUsed: 0,

    37 		

    38 		acquire: function() {

    39 			if ( this._permitsAvailable && this._permitsUsed >= this._permitsAvailable ) {

    40 				throw new Error( 'Max permits acquired' );

    41 			}

    42 			else {

    43 				this._permitsUsed++;

    44 			}

    45 		},

    46 		

    47 		release: function() {

    48 			if ( this._permitsUsed === 0 ) {

    49 				throw new Error( 'All permits released' );

    50 			}

    51 			else {

    52 				this._permitsUsed--;

    53 			}

    54 		},

    55 		

    56 		isLocked: function() {

    57 			return this._permitsUsed > 0;

    58 		},

    59 		

    60 		setAvailablePermits: function( amount ) {

    61 			if ( this._permitsUsed > amount ) {

    62 				throw new Error( 'Available permits cannot be less than used permits' );

    63 			}

    64 			this._permitsAvailable = amount;

    65 		}

    66 	};

    67 	

    68 	/**

    69 	 * A BlockingQueue that accumulates items while blocked (via 'block'),

    70 	 * and processes them when unblocked (via 'unblock').

    71 	 * Process can also be called manually (via 'process').

    72 	 */

    73 	Backbone.BlockingQueue = function() {

    74 		this._queue = [];

    75 	};

    76 	_.extend( Backbone.BlockingQueue.prototype, Backbone.Semaphore, {

    77 		_queue: null,

    78 		

    79 		add: function( func ) {

    80 			if ( this.isBlocked() ) {

    81 				this._queue.push( func );

    82 			}

    83 			else {

    84 				func();

    85 			}

    86 		},

    87 		

    88 		process: function() {

    89 			while ( this._queue && this._queue.length ) {

    90 				this._queue.shift()();

    91 			}

    92 		},

    93 		

    94 		block: function() {

    95 			this.acquire();

    96 		},

    97 		

    98 		unblock: function() {

    99 			this.release();

   100 			if ( !this.isBlocked() ) {

   101 				this.process();

   102 			}

   103 		},

   104 		

   105 		isBlocked: function() {

   106 			return this.isLocked();

   107 		}

   108 	});

   109 	/**

   110 	 * Global event queue. Accumulates external events ('add:<key>', 'remove:<key>' and 'update:<key>')

   111 	 * until the top-level object is fully initialized (see 'Backbone.RelationalModel').

   112 	 */

   113 	Backbone.Relational.eventQueue = new Backbone.BlockingQueue();

   114 	

   115 	/**

   116 	 * Backbone.Store keeps track of all created (and destruction of) Backbone.RelationalModel.

   117 	 * Handles lookup for relations.

   118 	 */

   119 	Backbone.Store = function() {

   120 		this._collections = [];

   121 		this._reverseRelations = [];

   122 		this._subModels = [];

   123 		this._modelScopes = [ exports ];

   124 	};

   125 	_.extend( Backbone.Store.prototype, Backbone.Events, {

   126 		addModelScope: function( scope ) {

   127 			this._modelScopes.push( scope );

   128 		},

   129 

   130 		/**

   131 		 * Add a set of subModelTypes to the store, that can be used to resolve the '_superModel'

   132 		 * for a model later in 'setupSuperModel'.

   133 		 *

   134 		 * @param {Backbone.RelationalModel} subModelTypes

   135 		 * @param {Backbone.RelationalModel} superModelType

   136 		 */

   137 		addSubModels: function( subModelTypes, superModelType ) {

   138 			this._subModels.push({

   139 				'superModelType': superModelType,

   140 				'subModels': subModelTypes

   141 			});

   142 		},

   143 

   144 		/**

   145 		 * Check if the given modelType is registered as another model's subModel. If so, add it to the super model's

   146 		 * '_subModels', and set the modelType's '_superModel', '_subModelTypeName', and '_subModelTypeAttribute'.

   147 		 *

   148 		 * @param {Backbone.RelationalModel} modelType

   149 		 */

   150 		setupSuperModel: function( modelType ) {

   151 			_.find( this._subModels, function( subModelDef ) {

   152 				return _.find( subModelDef.subModels, function( subModelTypeName, typeValue ) {

   153 					var subModelType = this.getObjectByName( subModelTypeName );

   154 

   155 					if ( modelType === subModelType ) {

   156 						// Set 'modelType' as a child of the found superModel

   157 						subModelDef.superModelType._subModels[ typeValue ] = modelType;

   158 

   159 						// Set '_superModel', '_subModelTypeValue', and '_subModelTypeAttribute' on 'modelType'.

   160 						modelType._superModel = subModelDef.superModelType;

   161 						modelType._subModelTypeValue = typeValue;

   162 						modelType._subModelTypeAttribute = subModelDef.superModelType.prototype.subModelTypeAttribute;

   163 						return true;

   164 					}

   165 				}, this );

   166 			}, this );

   167 		},

   168 		

   169 		/**

   170 		 * Add a reverse relation. Is added to the 'relations' property on model's prototype, and to

   171 		 * existing instances of 'model' in the store as well.

   172 		 * @param {Object} relation

   173 		 * @param {Backbone.RelationalModel} relation.model

   174 		 * @param {String} relation.type

   175 		 * @param {String} relation.key

   176 		 * @param {String|Object} relation.relatedModel

   177 		 */

   178 		addReverseRelation: function( relation ) {

   179 			var exists = _.any( this._reverseRelations, function( rel ) {

   180 					return _.all( relation, function( val, key ) {

   181 							return val === rel[ key ];

   182 						});

   183 				});

   184 			

   185 			if ( !exists && relation.model && relation.type ) {

   186 				this._reverseRelations.push( relation );

   187 				

   188 				var addRelation = function( model, relation ) {

   189 					if ( !model.prototype.relations ) {

   190 						model.prototype.relations = [];

   191 					}

   192 					model.prototype.relations.push( relation );

   193 					

   194 					_.each( model._subModels, function( subModel ) {

   195 							addRelation( subModel, relation );

   196 						}, this );

   197 				};

   198 				

   199 				addRelation( relation.model, relation );

   200 				

   201 				this.retroFitRelation( relation );

   202 			}

   203 		},

   204 		

   205 		/**

   206 		 * Add a 'relation' to all existing instances of 'relation.model' in the store

   207 		 * @param {Object} relation

   208 		 */

   209 		retroFitRelation: function( relation ) {

   210 			var coll = this.getCollection( relation.model );

   211 			coll.each( function( model ) {

   212 				if ( !( model instanceof relation.model ) ) {

   213 					return;

   214 				}

   215 

   216 				new relation.type( model, relation );

   217 			}, this);

   218 		},

   219 		

   220 		/**

   221 		 * Find the Store's collection for a certain type of model.

   222 		 * @param {Backbone.RelationalModel} model

   223 		 * @return {Backbone.Collection} A collection if found (or applicable for 'model'), or null

   224 		 */

   225 		getCollection: function( model ) {

   226 			if ( model instanceof Backbone.RelationalModel ) {

   227 				model = model.constructor;

   228 			}

   229 			

   230 			var rootModel = model;

   231 			while ( rootModel._superModel ) {

   232 				rootModel = rootModel._superModel;

   233 			}

   234 			

   235 			var coll = _.detect( this._collections, function( c ) {

   236 					return c.model === rootModel;

   237 				});

   238 			

   239 			if ( !coll ) {

   240 				coll = this._createCollection( rootModel );

   241 			}

   242 			

   243 			return coll;

   244 		},

   245 		

   246 		/**

   247 		 * Find a type on the global object by name. Splits name on dots.

   248 		 * @param {String} name

   249 		 * @return {Object}

   250 		 */

   251 		getObjectByName: function( name ) {

   252 			var parts = name.split( '.' ),

   253 				type = null;

   254 

   255 			_.find( this._modelScopes, function( scope ) {

   256 				type = _.reduce( parts, function( memo, val ) {

   257 					return memo[ val ];

   258 				}, scope );

   259 

   260 				if ( type && type !== scope ) {

   261 					return true;

   262 				}

   263 			}, this );

   264 

   265 			return type;

   266 		},

   267 		

   268 		_createCollection: function( type ) {

   269 			var coll;

   270 			

   271 			// If 'type' is an instance, take its constructor

   272 			if ( type instanceof Backbone.RelationalModel ) {

   273 				type = type.constructor;

   274 			}

   275 			

   276 			// Type should inherit from Backbone.RelationalModel.

   277 			if ( type.prototype instanceof Backbone.RelationalModel ) {

   278 				coll = new Backbone.Collection();

   279 				coll.model = type;

   280 				

   281 				this._collections.push( coll );

   282 			}

   283 			

   284 			return coll;

   285 		},

   286 

   287 		/**

   288 		 * Find the attribute that is to be used as the `id` on a given object

   289 		 * @param type

   290 		 * @param {String|Number|Object|Backbone.RelationalModel} item

   291 		 * @return {String|Number}

   292 		 */

   293 		resolveIdForItem: function( type, item ) {

   294 			var id = _.isString( item ) || _.isNumber( item ) ? item : null;

   295 

   296 			if ( id === null ) {

   297 				if ( item instanceof Backbone.RelationalModel ) {

   298 					id = item.id;

   299 				}

   300 				else if ( _.isObject( item ) ) {

   301 					id = item[ type.prototype.idAttribute ];

   302 				}

   303 			}

   304 

   305 			// Make all falsy values `null` (except for 0, which could be an id.. see '/issues/179')

   306 			if ( !id && id !== 0 ) {

   307 				id = null;

   308 			}

   309 

   310 			return id;

   311 		},

   312 

   313 		/**

   314 		 *

   315 		 * @param type

   316 		 * @param {String|Number|Object|Backbone.RelationalModel} item

   317 		 */

   318 		find: function( type, item ) {

   319 			var id = this.resolveIdForItem( type, item );

   320 			var coll = this.getCollection( type );

   321 			

   322 			// Because the found object could be of any of the type's superModel

   323 			// types, only return it if it's actually of the type asked for.

   324 			if ( coll ) {

   325 				var obj = coll.get( id );

   326 

   327 				if ( obj instanceof type ) {

   328 					return obj;

   329 				}

   330 			}

   331 

   332 			return null;

   333 		},

   334 		

   335 		/**

   336 		 * Add a 'model' to it's appropriate collection. Retain the original contents of 'model.collection'.

   337 		 * @param {Backbone.RelationalModel} model

   338 		 */

   339 		register: function( model ) {

   340 			var coll = this.getCollection( model );

   341 

   342 			if ( coll ) {

   343 				if ( coll.get( model ) ) {

   344 					throw new Error( "Cannot instantiate more than one Backbone.RelationalModel with the same id per type!" );

   345 				}

   346 

   347 				var modelColl = model.collection;

   348 				coll.add( model );

   349 				model.bind( 'destroy', this.unregister, this );

   350 				model.collection = modelColl;

   351 			}

   352 		},

   353 		

   354 		/**

   355 		 * Explicitly update a model's id in it's store collection

   356 		 * @param {Backbone.RelationalModel} model

   357 		 */

   358 		update: function( model ) {

   359 			var coll = this.getCollection( model );

   360 			coll._onModelEvent( 'change:' + model.idAttribute, model, coll );

   361 		},

   362 		

   363 		/**

   364 		 * Remove a 'model' from the store.

   365 		 * @param {Backbone.RelationalModel} model

   366 		 */

   367 		unregister: function( model ) {

   368 			model.unbind( 'destroy', this.unregister );

   369 			var coll = this.getCollection( model );

   370 			coll && coll.remove( model );

   371 		}

   372 	});

   373 	Backbone.Relational.store = new Backbone.Store();

   374 	

   375 	/**

   376 	 * The main Relation class, from which 'HasOne' and 'HasMany' inherit. Internally, 'relational:<key>' events

   377 	 * are used to regulate addition and removal of models from relations.

   378 	 *

   379 	 * @param {Backbone.RelationalModel} instance

   380 	 * @param {Object} options

   381 	 * @param {string} options.key

   382 	 * @param {Backbone.RelationalModel.constructor} options.relatedModel

   383 	 * @param {Boolean|String} [options.includeInJSON=true] Serialize the given attribute for related model(s)' in toJSON, or just their ids.

   384 	 * @param {Boolean} [options.createModels=true] Create objects from the contents of keys if the object is not found in Backbone.store.

   385 	 * @param {Object} [options.reverseRelation] Specify a bi-directional relation. If provided, Relation will reciprocate

   386 	 *    the relation to the 'relatedModel'. Required and optional properties match 'options', except that it also needs

   387 	 *    {Backbone.Relation|String} type ('HasOne' or 'HasMany').

   388 	 */

   389 	Backbone.Relation = function( instance, options ) {

   390 		this.instance = instance;

   391 		// Make sure 'options' is sane, and fill with defaults from subclasses and this object's prototype

   392 		options = _.isObject( options ) ? options : {};

   393 		this.reverseRelation = _.defaults( options.reverseRelation || {}, this.options.reverseRelation );

   394 		this.reverseRelation.type = !_.isString( this.reverseRelation.type ) ? this.reverseRelation.type :

   395 			Backbone[ this.reverseRelation.type ] || Backbone.Relational.store.getObjectByName( this.reverseRelation.type );

   396 		this.model = options.model || this.instance.constructor;

   397 		this.options = _.defaults( options, this.options, Backbone.Relation.prototype.options );

   398 		

   399 		this.key = this.options.key;

   400 		this.keySource = this.options.keySource || this.key;

   401 		this.keyDestination = this.options.keyDestination || this.keySource || this.key;

   402 

   403 		// 'exports' should be the global object where 'relatedModel' can be found on if given as a string.

   404 		this.relatedModel = this.options.relatedModel;

   405 		if ( _.isString( this.relatedModel ) ) {

   406 			this.relatedModel = Backbone.Relational.store.getObjectByName( this.relatedModel );

   407 		}

   408 

   409 		if ( !this.checkPreconditions() ) {

   410 			return false;

   411 		}

   412 

   413 		if ( instance ) {

   414 			this.keyContents = this.instance.get( this.keySource );

   415 

   416 			// Explicitly clear 'keySource', to prevent a leaky abstraction if 'keySource' differs from 'key'.

   417 			if ( this.key !== this.keySource ) {

   418 				this.instance.unset( this.keySource, { silent: true } );

   419 			}

   420 

   421 			// Add this Relation to instance._relations

   422 			this.instance._relations.push( this );

   423 		}

   424 

   425 		// Add the reverse relation on 'relatedModel' to the store's reverseRelations

   426 		if ( !this.options.isAutoRelation && this.reverseRelation.type && this.reverseRelation.key ) {

   427 			Backbone.Relational.store.addReverseRelation( _.defaults( {

   428 					isAutoRelation: true,

   429 					model: this.relatedModel,

   430 					relatedModel: this.model,

   431 					reverseRelation: this.options // current relation is the 'reverseRelation' for it's own reverseRelation

   432 				},

   433 				this.reverseRelation // Take further properties from this.reverseRelation (type, key, etc.)

   434 			) );

   435 		}

   436 

   437 		_.bindAll( this, '_modelRemovedFromCollection', '_relatedModelAdded', '_relatedModelRemoved' );

   438 

   439 		if ( instance ) {

   440 			this.initialize();

   441 

   442 			// When a model in the store is destroyed, check if it is 'this.instance'.

   443 			Backbone.Relational.store.getCollection( this.instance )

   444 				.bind( 'relational:remove', this._modelRemovedFromCollection );

   445 

   446 			// When 'relatedModel' are created or destroyed, check if it affects this relation.

   447 			Backbone.Relational.store.getCollection( this.relatedModel )

   448 				.bind( 'relational:add', this._relatedModelAdded )

   449 				.bind( 'relational:remove', this._relatedModelRemoved );

   450 		}

   451 	};

   452 	// Fix inheritance :\

   453 	Backbone.Relation.extend = Backbone.Model.extend;

   454 	// Set up all inheritable **Backbone.Relation** properties and methods.

   455 	_.extend( Backbone.Relation.prototype, Backbone.Events, Backbone.Semaphore, {

   456 		options: {

   457 			createModels: true,

   458 			includeInJSON: true,

   459 			isAutoRelation: false

   460 		},

   461 		

   462 		instance: null,

   463 		key: null,

   464 		keyContents: null,

   465 		relatedModel: null,

   466 		reverseRelation: null,

   467 		related: null,

   468 		

   469 		_relatedModelAdded: function( model, coll, options ) {

   470 			// Allow 'model' to set up it's relations, before calling 'tryAddRelated'

   471 			// (which can result in a call to 'addRelated' on a relation of 'model')

   472 			var dit = this;

   473 			model.queue( function() {

   474 				dit.tryAddRelated( model, options );

   475 			});

   476 		},

   477 		

   478 		_relatedModelRemoved: function( model, coll, options ) {

   479 			this.removeRelated( model, options );

   480 		},

   481 		

   482 		_modelRemovedFromCollection: function( model ) {

   483 			if ( model === this.instance ) {

   484 				this.destroy();

   485 			}

   486 		},

   487 		

   488 		/**

   489 		 * Check several pre-conditions.

   490 		 * @return {Boolean} True if pre-conditions are satisfied, false if they're not.

   491 		 */

   492 		checkPreconditions: function() {

   493 			var i = this.instance,

   494 				k = this.key,

   495 				m = this.model,

   496 				rm = this.relatedModel,

   497 				warn = Backbone.Relational.showWarnings && typeof console !== 'undefined';

   498 

   499 			if ( !m || !k || !rm ) {

   500 				warn && console.warn( 'Relation=%o; no model, key or relatedModel (%o, %o, %o)', this, m, k, rm );

   501 				return false;

   502 			}

   503 			// Check if the type in 'model' inherits from Backbone.RelationalModel

   504 			if ( !( m.prototype instanceof Backbone.RelationalModel ) ) {

   505 				warn && console.warn( 'Relation=%o; model does not inherit from Backbone.RelationalModel (%o)', this, i );

   506 				return false;

   507 			}

   508 			// Check if the type in 'relatedModel' inherits from Backbone.RelationalModel

   509 			if ( !( rm.prototype instanceof Backbone.RelationalModel ) ) {

   510 				warn && console.warn( 'Relation=%o; relatedModel does not inherit from Backbone.RelationalModel (%o)', this, rm );

   511 				return false;

   512 			}

   513 			// Check if this is not a HasMany, and the reverse relation is HasMany as well

   514 			if ( this instanceof Backbone.HasMany && this.reverseRelation.type === Backbone.HasMany ) {

   515 				warn && console.warn( 'Relation=%o; relation is a HasMany, and the reverseRelation is HasMany as well.', this );

   516 				return false;

   517 			}

   518 

   519 			// Check if we're not attempting to create a duplicate relationship

   520 			if ( i && i._relations.length ) {

   521 				var exists = _.any( i._relations, function( rel ) {

   522 						var hasReverseRelation = this.reverseRelation.key && rel.reverseRelation.key;

   523 						return rel.relatedModel === rm && rel.key === k &&

   524 							( !hasReverseRelation || this.reverseRelation.key === rel.reverseRelation.key );

   525 					}, this );

   526 

   527 				if ( exists ) {

   528 					warn && console.warn( 'Relation=%o between instance=%o.%s and relatedModel=%o.%s already exists',

   529 						this, i, k, rm, this.reverseRelation.key );

   530 					return false;

   531 				}

   532 			}

   533 

   534 			return true;

   535 		},

   536 

   537 		/**

   538 		 * Set the related model(s) for this relation

   539 		 * @param {Backbone.Mode|Backbone.Collection} related

   540 		 * @param {Object} [options]

   541 		 */

   542 		setRelated: function( related, options ) {

   543 			this.related = related;

   544 

   545 			this.instance.acquire();

   546 			this.instance.set( this.key, related, _.defaults( options || {}, { silent: true } ) );

   547 			this.instance.release();

   548 		},

   549 		

   550 		/**

   551 		 * Determine if a relation (on a different RelationalModel) is the reverse

   552 		 * relation of the current one.

   553 		 * @param {Backbone.Relation} relation

   554 		 * @return {Boolean}

   555 		 */

   556 		_isReverseRelation: function( relation ) {

   557 			if ( relation.instance instanceof this.relatedModel && this.reverseRelation.key === relation.key &&

   558 					this.key === relation.reverseRelation.key ) {

   559 				return true;

   560 			}

   561 			return false;

   562 		},

   563 		

   564 		/**

   565 		 * Get the reverse relations (pointing back to 'this.key' on 'this.instance') for the currently related model(s).

   566 		 * @param {Backbone.RelationalModel} [model] Get the reverse relations for a specific model.

   567 		 *    If not specified, 'this.related' is used.

   568 		 * @return {Backbone.Relation[]}

   569 		 */

   570 		getReverseRelations: function( model ) {

   571 			var reverseRelations = [];

   572 			// Iterate over 'model', 'this.related.models' (if this.related is a Backbone.Collection), or wrap 'this.related' in an array.

   573 			var models = !_.isUndefined( model ) ? [ model ] : this.related && ( this.related.models || [ this.related ] );

   574 			_.each( models , function( related ) {

   575 					_.each( related.getRelations(), function( relation ) {

   576 							if ( this._isReverseRelation( relation ) ) {

   577 								reverseRelations.push( relation );

   578 							}

   579 						}, this );

   580 				}, this );

   581 			

   582 			return reverseRelations;

   583 		},

   584 		

   585 		/**

   586 		 * Rename options.silent to options.silentChange, so events propagate properly.

   587 		 * (for example in HasMany, from 'addRelated'->'handleAddition')

   588 		 * @param {Object} [options]

   589 		 * @return {Object}

   590 		 */

   591 		sanitizeOptions: function( options ) {

   592 			options = options ? _.clone( options ) : {};

   593 			if ( options.silent ) {

   594 				options.silentChange = true;

   595 				delete options.silent;

   596 			}

   597 			return options;

   598 		},

   599 

   600 		/**

   601 		 * Rename options.silentChange to options.silent, so events are silenced as intended in Backbone's

   602 		 * original functions.

   603 		 * @param {Object} [options]

   604 		 * @return {Object}

   605 		 */

   606 		unsanitizeOptions: function( options ) {

   607 			options = options ? _.clone( options ) : {};

   608 			if ( options.silentChange ) {

   609 				options.silent = true;

   610 				delete options.silentChange;

   611 			}

   612 			return options;

   613 		},

   614 		

   615 		// Cleanup. Get reverse relation, call removeRelated on each.

   616 		destroy: function() {

   617 			Backbone.Relational.store.getCollection( this.instance )

   618 				.unbind( 'relational:remove', this._modelRemovedFromCollection );

   619 			

   620 			Backbone.Relational.store.getCollection( this.relatedModel )

   621 				.unbind( 'relational:add', this._relatedModelAdded )

   622 				.unbind( 'relational:remove', this._relatedModelRemoved );

   623 			

   624 			_.each( this.getReverseRelations(), function( relation ) {

   625 					relation.removeRelated( this.instance );

   626 				}, this );

   627 		}

   628 	});

   629 	

   630 	Backbone.HasOne = Backbone.Relation.extend({

   631 		options: {

   632 			reverseRelation: { type: 'HasMany' }

   633 		},

   634 		

   635 		initialize: function() {

   636 			_.bindAll( this, 'onChange' );

   637 

   638 			this.instance.bind( 'relational:change:' + this.key, this.onChange );

   639 

   640 			var model = this.findRelated( { silent: true } );

   641 			this.setRelated( model );

   642 

   643 			// Notify new 'related' object of the new relation.

   644 			_.each( this.getReverseRelations(), function( relation ) {

   645 					relation.addRelated( this.instance );

   646 				}, this );

   647 		},

   648 		

   649 		findRelated: function( options ) {

   650 			var item = this.keyContents;

   651 			var model = null;

   652 			

   653 			if ( item instanceof this.relatedModel ) {

   654 				model = item;

   655 			}

   656 			else if ( item || item === 0 ) { // since 0 can be a valid `id` as well

   657 				model = this.relatedModel.findOrCreate( item, { create: this.options.createModels } );

   658 			}

   659 			

   660 			return model;

   661 		},

   662 		

   663 		/**

   664 		 * If the key is changed, notify old & new reverse relations and initialize the new relation

   665 		 */

   666 		onChange: function( model, attr, options ) {

   667 			// Don't accept recursive calls to onChange (like onChange->findRelated->findOrCreate->initializeRelations->addRelated->onChange)

   668 			if ( this.isLocked() ) {

   669 				return;

   670 			}

   671 			this.acquire();

   672 			options = this.sanitizeOptions( options );

   673 			

   674 			// 'options._related' is set by 'addRelated'/'removeRelated'. If it is set, the change

   675 			// is the result of a call from a relation. If it's not, the change is the result of 

   676 			// a 'set' call on this.instance.

   677 			var changed = _.isUndefined( options._related );

   678 			var oldRelated = changed ? this.related : options._related;

   679 			

   680 			if ( changed ) {	

   681 				this.keyContents = attr;

   682 				

   683 				// Set new 'related'

   684 				if ( attr instanceof this.relatedModel ) {

   685 					this.related = attr;

   686 				}

   687 				else if ( attr ) {

   688 					var related = this.findRelated( options );

   689 					this.setRelated( related );

   690 				}

   691 				else {

   692 					this.setRelated( null );

   693 				}

   694 			}

   695 			

   696 			// Notify old 'related' object of the terminated relation

   697 			if ( oldRelated && this.related !== oldRelated ) {

   698 				_.each( this.getReverseRelations( oldRelated ), function( relation ) {

   699 						relation.removeRelated( this.instance, options );

   700 					}, this );

   701 			}

   702 			

   703 			// Notify new 'related' object of the new relation. Note we do re-apply even if this.related is oldRelated;

   704 			// that can be necessary for bi-directional relations if 'this.instance' was created after 'this.related'.

   705 			// In that case, 'this.instance' will already know 'this.related', but the reverse might not exist yet.

   706 			_.each( this.getReverseRelations(), function( relation ) {

   707 					relation.addRelated( this.instance, options );

   708 				}, this);

   709 			

   710 			// Fire the 'update:<key>' event if 'related' was updated

   711 			if ( !options.silentChange && this.related !== oldRelated ) {

   712 				var dit = this;

   713 				Backbone.Relational.eventQueue.add( function() {

   714 					dit.instance.trigger( 'update:' + dit.key, dit.instance, dit.related, options );

   715 				});

   716 			}

   717 			this.release();

   718 		},

   719 		

   720 		/**

   721 		 * If a new 'this.relatedModel' appears in the 'store', try to match it to the last set 'keyContents'

   722 		 */

   723 		tryAddRelated: function( model, options ) {

   724 			if ( this.related ) {

   725 				return;

   726 			}

   727 			options = this.sanitizeOptions( options );

   728 			

   729 			var item = this.keyContents;

   730 			if ( item || item === 0 ) { // since 0 can be a valid `id` as well

   731 				var id = Backbone.Relational.store.resolveIdForItem( this.relatedModel, item );

   732 				if ( !_.isNull( id ) && model.id === id ) {

   733 					this.addRelated( model, options );

   734 				}

   735 			}

   736 		},

   737 		

   738 		addRelated: function( model, options ) {

   739 			if ( model !== this.related ) {

   740 				var oldRelated = this.related || null;

   741 				this.setRelated( model );

   742 				this.onChange( this.instance, model, { _related: oldRelated } );

   743 			}

   744 		},

   745 		

   746 		removeRelated: function( model, options ) {

   747 			if ( !this.related ) {

   748 				return;

   749 			}

   750 			

   751 			if ( model === this.related ) {

   752 				var oldRelated = this.related || null;

   753 				this.setRelated( null );

   754 				this.onChange( this.instance, model, { _related: oldRelated } );

   755 			}

   756 		}

   757 	});

   758 	

   759 	Backbone.HasMany = Backbone.Relation.extend({

   760 		collectionType: null,

   761 		

   762 		options: {

   763 			reverseRelation: { type: 'HasOne' },

   764 			collectionType: Backbone.Collection,

   765 			collectionKey: true,

   766 			collectionOptions: {}

   767 		},

   768 		

   769 		initialize: function() {

   770 			_.bindAll( this, 'onChange', 'handleAddition', 'handleRemoval', 'handleReset' );

   771 			this.instance.bind( 'relational:change:' + this.key, this.onChange );

   772 			

   773 			// Handle a custom 'collectionType'

   774 			this.collectionType = this.options.collectionType;

   775 			if ( _.isString( this.collectionType ) ) {

   776 				this.collectionType = Backbone.Relational.store.getObjectByName( this.collectionType );

   777 			}

   778 			if ( !this.collectionType.prototype instanceof Backbone.Collection ){

   779 				throw new Error( 'collectionType must inherit from Backbone.Collection' );

   780 			}

   781 

   782 			// Handle cases where a model/relation is created with a collection passed straight into 'attributes'

   783 			if ( this.keyContents instanceof Backbone.Collection ) {

   784 				this.setRelated( this._prepareCollection( this.keyContents ) );

   785 			}

   786 			else {

   787 				this.setRelated( this._prepareCollection() );

   788 			}

   789 

   790 			this.findRelated( { silent: true } );

   791 		},

   792 		

   793 		_getCollectionOptions: function() {

   794 			return _.isFunction( this.options.collectionOptions ) ?

   795 				this.options.collectionOptions( this.instance ) :

   796 				this.options.collectionOptions;

   797 		},

   798 

   799 		/**

   800 		 * Bind events and setup collectionKeys for a collection that is to be used as the backing store for a HasMany.

   801 		 * If no 'collection' is supplied, a new collection will be created of the specified 'collectionType' option.

   802 		 * @param {Backbone.Collection} [collection]

   803 		 */

   804 		_prepareCollection: function( collection ) {

   805 			if ( this.related ) {

   806 				this.related

   807 					.unbind( 'relational:add', this.handleAddition )

   808 					.unbind( 'relational:remove', this.handleRemoval )

   809 					.unbind( 'relational:reset', this.handleReset )

   810 			}

   811 

   812 			if ( !collection || !( collection instanceof Backbone.Collection ) ) {

   813 				collection = new this.collectionType( [], this._getCollectionOptions() );

   814 			}

   815 

   816 			collection.model = this.relatedModel;

   817 			

   818 			if ( this.options.collectionKey ) {

   819 				var key = this.options.collectionKey === true ? this.options.reverseRelation.key : this.options.collectionKey;

   820 				

   821 				if ( collection[ key ] && collection[ key ] !== this.instance ) {

   822 					if ( Backbone.Relational.showWarnings && typeof console !== 'undefined' ) {

   823 						console.warn( 'Relation=%o; collectionKey=%s already exists on collection=%o', this, key, this.options.collectionKey );

   824 					}

   825 				}

   826 				else if ( key ) {

   827 					collection[ key ] = this.instance;

   828 				}

   829 			}

   830 			

   831 			collection

   832 				.bind( 'relational:add', this.handleAddition )

   833 				.bind( 'relational:remove', this.handleRemoval )

   834 				.bind( 'relational:reset', this.handleReset );

   835 			

   836 			return collection;

   837 		},

   838 		

   839 		findRelated: function( options ) {

   840 			if ( this.keyContents ) {

   841 				var models = [];

   842 

   843 				if ( this.keyContents instanceof Backbone.Collection ) {

   844 					models = this.keyContents.models;

   845 				}

   846 				else {

   847 					// Handle cases the an API/user supplies just an Object/id instead of an Array

   848 					this.keyContents = _.isArray( this.keyContents ) ? this.keyContents : [ this.keyContents ];

   849 

   850 					// Try to find instances of the appropriate 'relatedModel' in the store

   851 					_.each( this.keyContents, function( item ) {

   852 							var model = null;

   853 							if ( item instanceof this.relatedModel ) {

   854 								model = item;

   855 							}

   856 							else if ( item || item === 0 ) { // since 0 can be a valid `id` as well

   857 								model = this.relatedModel.findOrCreate( item, { create: this.options.createModels } );

   858 							}

   859 

   860 							if ( model && !this.related.getByCid( model ) && !this.related.get( model ) ) {

   861 								models.push( model );

   862 							}

   863 						}, this );

   864 				}

   865 

   866 				// Add all found 'models' in on go, so 'add' will only be called once (and thus 'sort', etc.)

   867 				if ( models.length ) {

   868 					options = this.unsanitizeOptions( options );

   869 					this.related.add( models, options );

   870 				}

   871 			}

   872 		},

   873 		

   874 		/**

   875 		 * If the key is changed, notify old & new reverse relations and initialize the new relation

   876 		 */

   877 		onChange: function( model, attr, options ) {

   878 			options = this.sanitizeOptions( options );

   879 			this.keyContents = attr;

   880 			

   881 			// Notify old 'related' object of the terminated relation

   882 			_.each( this.getReverseRelations(), function( relation ) {

   883 					relation.removeRelated( this.instance, options );

   884 				}, this );

   885 			

   886 			// Replace 'this.related' by 'attr' if it is a Backbone.Collection

   887 			if ( attr instanceof Backbone.Collection ) {

   888 				this._prepareCollection( attr );

   889 				this.related = attr;

   890 			}

   891 			// Otherwise, 'attr' should be an array of related object ids.

   892 			// Re-use the current 'this.related' if it is a Backbone.Collection, and remove any current entries.

   893 			// Otherwise, create a new collection.

   894 			else {

   895 				var coll;

   896 

   897 				if ( this.related instanceof Backbone.Collection ) {

   898 					coll = this.related;

   899 					coll.remove( coll.models );

   900 				}

   901 				else {

   902 					coll = this._prepareCollection();

   903 				}

   904 

   905 				this.setRelated( coll );

   906 				this.findRelated( options );

   907 			}

   908 			

   909 			// Notify new 'related' object of the new relation

   910 			_.each( this.getReverseRelations(), function( relation ) {

   911 					relation.addRelated( this.instance, options );

   912 				}, this );

   913 			

   914 			var dit = this;

   915 			Backbone.Relational.eventQueue.add( function() {

   916 				!options.silentChange && dit.instance.trigger( 'update:' + dit.key, dit.instance, dit.related, options );

   917 			});

   918 		},

   919 		

   920 		tryAddRelated: function( model, options ) {

   921 			options = this.sanitizeOptions( options );

   922 			if ( !this.related.getByCid( model ) && !this.related.get( model ) ) {

   923 				// Check if this new model was specified in 'this.keyContents'

   924 				var item = _.any( this.keyContents, function( item ) {

   925 						var id = Backbone.Relational.store.resolveIdForItem( this.relatedModel, item );

   926 						return !_.isNull( id ) && id === model.id;

   927 					}, this );

   928 				

   929 				if ( item ) {

   930 					this.related.add( model, options );

   931 				}

   932 			}

   933 		},

   934 		

   935 		/**

   936 		 * When a model is added to a 'HasMany', trigger 'add' on 'this.instance' and notify reverse relations.

   937 		 * (should be 'HasOne', must set 'this.instance' as their related).

   938 		 */

   939 		handleAddition: function( model, coll, options ) {

   940 			//console.debug('handleAddition called; args=%o', arguments);

   941 			// Make sure the model is in fact a valid model before continuing.

   942 			// (it can be invalid as a result of failing validation in Backbone.Collection._prepareModel)

   943 			if ( !( model instanceof Backbone.Model ) ) {

   944 				return;

   945 			}

   946 			

   947 			options = this.sanitizeOptions( options );

   948 			

   949 			_.each( this.getReverseRelations( model ), function( relation ) {

   950 					relation.addRelated( this.instance, options );

   951 				}, this );

   952 

   953 			// Only trigger 'add' once the newly added model is initialized (so, has it's relations set up)

   954 			var dit = this;

   955 			Backbone.Relational.eventQueue.add( function() {

   956 				!options.silentChange && dit.instance.trigger( 'add:' + dit.key, model, dit.related, options );

   957 			});

   958 		},

   959 		

   960 		/**

   961 		 * When a model is removed from a 'HasMany', trigger 'remove' on 'this.instance' and notify reverse relations.

   962 		 * (should be 'HasOne', which should be nullified)

   963 		 */

   964 		handleRemoval: function( model, coll, options ) {

   965 			//console.debug('handleRemoval called; args=%o', arguments);

   966 			if ( !( model instanceof Backbone.Model ) ) {

   967 				return;

   968 			}

   969 

   970 			options = this.sanitizeOptions( options );

   971 			

   972 			_.each( this.getReverseRelations( model ), function( relation ) {

   973 					relation.removeRelated( this.instance, options );

   974 				}, this );

   975 			

   976 			var dit = this;

   977 			Backbone.Relational.eventQueue.add( function() {

   978 				!options.silentChange && dit.instance.trigger( 'remove:' + dit.key, model, dit.related, options );

   979 			});

   980 		},

   981 

   982 		handleReset: function( coll, options ) {

   983 			options = this.sanitizeOptions( options );

   984 

   985 			var dit = this;

   986 			Backbone.Relational.eventQueue.add( function() {

   987 				!options.silentChange && dit.instance.trigger( 'reset:' + dit.key, dit.related, options );

   988 			});

   989 		},

   990 		

   991 		addRelated: function( model, options ) {

   992 			var dit = this;

   993 			options = this.unsanitizeOptions( options );

   994 			model.queue( function() { // Queued to avoid errors for adding 'model' to the 'this.related' set twice

   995 				if ( dit.related && !dit.related.getByCid( model ) && !dit.related.get( model ) ) {

   996 					dit.related.add( model, options );

   997 				}

   998 			});

   999 		},

  1000 		

  1001 		removeRelated: function( model, options ) {

  1002 			options = this.unsanitizeOptions( options );

  1003 			if ( this.related.getByCid( model ) || this.related.get( model ) ) {

  1004 				this.related.remove( model, options );

  1005 			}

  1006 		}

  1007 	});

  1008 	

  1009 	/**

  1010 	 * A type of Backbone.Model that also maintains relations to other models and collections.

  1011 	 * New events when compared to the original:

  1012 	 *  - 'add:<key>' (model, related collection, options)

  1013 	 *  - 'remove:<key>' (model, related collection, options)

  1014 	 *  - 'update:<key>' (model, related model or collection, options)

  1015 	 */

  1016 	Backbone.RelationalModel = Backbone.Model.extend({

  1017 		relations: null, // Relation descriptions on the prototype

  1018 		_relations: null, // Relation instances

  1019 		_isInitialized: false,

  1020 		_deferProcessing: false,

  1021 		_queue: null,

  1022 		

  1023 		subModelTypeAttribute: 'type',

  1024 		subModelTypes: null,

  1025 		

  1026 		constructor: function( attributes, options ) {

  1027 			// Nasty hack, for cases like 'model.get( <HasMany key> ).add( item )'.

  1028 			// Defer 'processQueue', so that when 'Relation.createModels' is used we:

  1029 			// a) Survive 'Backbone.Collection.add'; this takes care we won't error on "can't add model to a set twice"

  1030 			//    (by creating a model from properties, having the model add itself to the collection via one of

  1031 			//    it's relations, then trying to add it to the collection).

  1032 			// b) Trigger 'HasMany' collection events only after the model is really fully set up.

  1033 			// Example that triggers both a and b: "p.get('jobs').add( { company: c, person: p } )".

  1034 			var dit = this;

  1035 			if ( options && options.collection ) {

  1036 				this._deferProcessing = true;

  1037 				

  1038 				var processQueue = function( model ) {

  1039 					if ( model === dit ) {

  1040 						dit._deferProcessing = false;

  1041 						dit.processQueue();

  1042 						options.collection.unbind( 'relational:add', processQueue );

  1043 					}

  1044 				};

  1045 				options.collection.bind( 'relational:add', processQueue );

  1046 				

  1047 				// So we do process the queue eventually, regardless of whether this model really gets added to 'options.collection'.

  1048 				_.defer( function() {

  1049 					processQueue( dit );

  1050 				});

  1051 			}

  1052 			

  1053 			this._queue = new Backbone.BlockingQueue();

  1054 			this._queue.block();

  1055 			Backbone.Relational.eventQueue.block();

  1056 			

  1057 			Backbone.Model.apply( this, arguments );

  1058 			

  1059 			// Try to run the global queue holding external events

  1060 			Backbone.Relational.eventQueue.unblock();

  1061 		},

  1062 		

  1063 		/**

  1064 		 * Override 'trigger' to queue 'change' and 'change:*' events

  1065 		 */

  1066 		trigger: function( eventName ) {

  1067 			if ( eventName.length > 5 && 'change' === eventName.substr( 0, 6 ) ) {

  1068 				var dit = this, args = arguments;

  1069 				Backbone.Relational.eventQueue.add( function() {

  1070 						Backbone.Model.prototype.trigger.apply( dit, args );

  1071 					});

  1072 			}

  1073 			else {

  1074 				Backbone.Model.prototype.trigger.apply( this, arguments );

  1075 			}

  1076 			

  1077 			return this;

  1078 		},

  1079 		

  1080 		/**

  1081 		 * Initialize Relations present in this.relations; determine the type (HasOne/HasMany), then creates a new instance.

  1082 		 * Invoked in the first call so 'set' (which is made from the Backbone.Model constructor).

  1083 		 */

  1084 		initializeRelations: function() {

  1085 			this.acquire(); // Setting up relations often also involve calls to 'set', and we only want to enter this function once

  1086 			this._relations = [];

  1087 			

  1088 			_.each( this.relations, function( rel ) {

  1089 					var type = !_.isString( rel.type ) ? rel.type :	Backbone[ rel.type ] || Backbone.Relational.store.getObjectByName( rel.type );

  1090 					if ( type && type.prototype instanceof Backbone.Relation ) {

  1091 						new type( this, rel ); // Also pushes the new Relation into _relations

  1092 					}

  1093 					else {

  1094 						Backbone.Relational.showWarnings && typeof console !== 'undefined' && console.warn( 'Relation=%o; missing or invalid type!', rel );

  1095 					}

  1096 				}, this );

  1097 			

  1098 			this._isInitialized = true;

  1099 			this.release();

  1100 			this.processQueue();

  1101 		},

  1102 

  1103 		/**

  1104 		 * When new values are set, notify this model's relations (also if options.silent is set).

  1105 		 * (Relation.setRelated locks this model before calling 'set' on it to prevent loops)

  1106 		 */

  1107 		updateRelations: function( options ) {

  1108 			if ( this._isInitialized && !this.isLocked() ) {

  1109 				_.each( this._relations, function( rel ) {

  1110 					// Update from data in `rel.keySource` if set, or `rel.key` otherwise

  1111 					var val = this.attributes[ rel.keySource ] || this.attributes[ rel.key ];

  1112 					if ( rel.related !== val ) {

  1113 						this.trigger( 'relational:change:' + rel.key, this, val, options || {} );

  1114 					}

  1115 				}, this );

  1116 			}

  1117 		},

  1118 		

  1119 		/**

  1120 		 * Either add to the queue (if we're not initialized yet), or execute right away.

  1121 		 */

  1122 		queue: function( func ) {

  1123 			this._queue.add( func );

  1124 		},

  1125 		

  1126 		/**

  1127 		 * Process _queue

  1128 		 */

  1129 		processQueue: function() {

  1130 			if ( this._isInitialized && !this._deferProcessing && this._queue.isBlocked() ) {

  1131 				this._queue.unblock();

  1132 			}

  1133 		},

  1134 		

  1135 		/**