1 /* vim: set tabstop=4 softtabstop=4 shiftwidth=4 noexpandtab: */

     2 /**

     3  * Backbone-relational.js 0.8.5

     4  * (c) 2011-2013 Paul Uithol and contributors (https://github.com/PaulUithol/Backbone-relational/graphs/contributors)

     5  * 

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

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

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

     9  */

    10 ( function( undefined ) {

    11 	"use strict";

    12 

    13 	/**

    14 	 * CommonJS shim

    15 	 **/

    16 	var _, Backbone, exports;

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

    18 		_ = require( 'underscore' );

    19 		Backbone = require( 'backbone' );

    20 		exports = module.exports = Backbone;

    21 	}

    22 	else {

    23 		_ = window._;

    24 		Backbone = window.Backbone;

    25 		exports = window;

    26 	}

    27 

    28 	Backbone.Relational = {

    29 		showWarnings: true

    30 	};

    31 

    32 	/**

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

    34 	 **/

    35 	Backbone.Semaphore = {

    36 		_permitsAvailable: null,

    37 		_permitsUsed: 0,

    38 

    39 		acquire: function() {

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

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

    42 			}

    43 			else {

    44 				this._permitsUsed++;

    45 			}

    46 		},

    47 

    48 		release: function() {

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

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

    51 			}

    52 			else {

    53 				this._permitsUsed--;

    54 			}

    55 		},

    56 

    57 		isLocked: function() {

    58 			return this._permitsUsed > 0;

    59 		},

    60 

    61 		setAvailablePermits: function( amount ) {

    62 			if ( this._permitsUsed > amount ) {

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

    64 			}

    65 			this._permitsAvailable = amount;

    66 		}

    67 	};

    68 

    69 	/**

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

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

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

    73 	 */

    74 	Backbone.BlockingQueue = function() {

    75 		this._queue = [];

    76 	};

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

    78 		_queue: null,

    79 

    80 		add: function( func ) {

    81 			if ( this.isBlocked() ) {

    82 				this._queue.push( func );

    83 			}

    84 			else {

    85 				func();

    86 			}

    87 		},

    88 

    89 		process: function() {

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

    91 				this._queue.shift()();

    92 			}

    93 		},

    94 

    95 		block: function() {

    96 			this.acquire();

    97 		},

    98 

    99 		unblock: function() {

   100 			this.release();

   101 			if ( !this.isBlocked() ) {

   102 				this.process();

   103 			}

   104 		},

   105 

   106 		isBlocked: function() {

   107 			return this.isLocked();

   108 		}

   109 	});

   110 	/**

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

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

   113 	 */

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

   115 

   116 	/**

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

   118 	 * Handles lookup for relations.

   119 	 */

   120 	Backbone.Store = function() {

   121 		this._collections = [];

   122 		this._reverseRelations = [];

   123 		this._orphanRelations = [];

   124 		this._subModels = [];

   125 		this._modelScopes = [ exports ];

   126 	};

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

   128 		/**

   129 		 * Create a new `Relation`.

   130 		 * @param {Backbone.RelationalModel} [model]

   131 		 * @param {Object} relation

   132 		 * @param {Object} [options]

   133 		 */

   134 		initializeRelation: function( model, relation, options ) {

   135 			var type = !_.isString( relation.type ) ? relation.type : Backbone[ relation.type ] || this.getObjectByName( relation.type );

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

   137 				new type( model, relation, options ); // Also pushes the new Relation into `model._relations`

   138 			}

   139 			else {

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

   141 			}

   142 		},

   143 

   144 		/**

   145 		 * Add a scope for `getObjectByName` to look for model types by name.

   146 		 * @param {Object} scope

   147 		 */

   148 		addModelScope: function( scope ) {

   149 			this._modelScopes.push( scope );

   150 		},

   151 

   152 		/**

   153 		 * Remove a scope.

   154 		 * @param {Object} scope

   155 		 */

   156 		removeModelScope: function( scope ) {

   157 			this._modelScopes = _.without( this._modelScopes, scope );

   158 		},

   159 

   160 		/**

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

   162 		 * for a model later in 'setupSuperModel'.

   163 		 *

   164 		 * @param {Backbone.RelationalModel} subModelTypes

   165 		 * @param {Backbone.RelationalModel} superModelType

   166 		 */

   167 		addSubModels: function( subModelTypes, superModelType ) {

   168 			this._subModels.push({

   169 				'superModelType': superModelType,

   170 				'subModels': subModelTypes

   171 			});

   172 		},

   173 

   174 		/**

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

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

   177 		 *

   178 		 * @param {Backbone.RelationalModel} modelType

   179 		 */

   180 		setupSuperModel: function( modelType ) {

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

   182 				return _.find( subModelDef.subModels || [], function( subModelTypeName, typeValue ) {

   183 					var subModelType = this.getObjectByName( subModelTypeName );

   184 

   185 					if ( modelType === subModelType ) {

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

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

   188 

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

   190 						modelType._superModel = subModelDef.superModelType;

   191 						modelType._subModelTypeValue = typeValue;

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

   193 						return true;

   194 					}

   195 				}, this );

   196 			}, this );

   197 		},

   198 

   199 		/**

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

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

   202 		 * @param {Object} relation

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

   204 		 * @param {String} relation.type

   205 		 * @param {String} relation.key

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

   207 		 */

   208 		addReverseRelation: function( relation ) {

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

   210 				return _.all( relation || [], function( val, key ) {

   211 					return val === rel[ key ];

   212 				});

   213 			});

   214 			

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

   216 				this._reverseRelations.push( relation );

   217 				this._addRelation( relation.model, relation );

   218 				this.retroFitRelation( relation );

   219 			}

   220 		},

   221 

   222 		/**

   223 		 * Deposit a `relation` for which the `relatedModel` can't be resolved at the moment.

   224 		 *

   225 		 * @param {Object} relation

   226 		 */

   227 		addOrphanRelation: function( relation ) {

   228 			var exists = _.any( this._orphanRelations, function( rel ) {

   229 				return _.all( relation || [], function( val, key ) {

   230 					return val === rel[ key ];

   231 				});

   232 			});

   233 

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

   235 				this._orphanRelations.push( relation );

   236 			}

   237 		},

   238 

   239 		/**

   240 		 * Try to initialize any `_orphanRelation`s

   241 		 */

   242 		processOrphanRelations: function() {

   243 			// Make sure to operate on a copy since we're removing while iterating

   244 			_.each( this._orphanRelations.slice( 0 ), function( rel ) {

   245 				var relatedModel = Backbone.Relational.store.getObjectByName( rel.relatedModel );

   246 				if ( relatedModel ) {

   247 					this.initializeRelation( null, rel );

   248 					this._orphanRelations = _.without( this._orphanRelations, rel );

   249 				}

   250 			}, this );

   251 		},

   252 

   253 		/**

   254 		 *

   255 		 * @param {Backbone.RelationalModel.constructor} type

   256 		 * @param {Object} relation

   257 		 * @private

   258 		 */

   259 		_addRelation: function( type, relation ) {

   260 			if ( !type.prototype.relations ) {

   261 				type.prototype.relations = [];

   262 			}

   263 			type.prototype.relations.push( relation );

   264 

   265 			_.each( type._subModels || [], function( subModel ) {

   266 				this._addRelation( subModel, relation );

   267 			}, this );

   268 		},

   269 

   270 		/**

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

   272 		 * @param {Object} relation

   273 		 */

   274 		retroFitRelation: function( relation ) {

   275 			var coll = this.getCollection( relation.model, false );

   276 			coll && coll.each( function( model ) {

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

   278 					return;

   279 				}

   280 

   281 				new relation.type( model, relation );

   282 			}, this );

   283 		},

   284 

   285 		/**

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

   287 		 * @param {Backbone.RelationalModel} type

   288 		 * @param {Boolean} [create=true] Should a collection be created if none is found?

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

   290 		 */

   291 		getCollection: function( type, create ) {

   292 			if ( type instanceof Backbone.RelationalModel ) {

   293 				type = type.constructor;

   294 			}

   295 			

   296 			var rootModel = type;

   297 			while ( rootModel._superModel ) {

   298 				rootModel = rootModel._superModel;

   299 			}

   300 			

   301 			var coll = _.findWhere( this._collections, { model: rootModel } );

   302 			

   303 			if ( !coll && create !== false ) {

   304 				coll = this._createCollection( rootModel );

   305 			}

   306 			

   307 			return coll;

   308 		},

   309 

   310 		/**

   311 		 * Find a model type on one of the modelScopes by name. Names are split on dots.

   312 		 * @param {String} name

   313 		 * @return {Object}

   314 		 */

   315 		getObjectByName: function( name ) {

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

   317 				type = null;

   318 

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

   320 				type = _.reduce( parts || [], function( memo, val ) {

   321 					return memo ? memo[ val ] : undefined;

   322 				}, scope );

   323 

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

   325 					return true;

   326 				}

   327 			}, this );

   328 

   329 			return type;

   330 		},

   331 

   332 		_createCollection: function( type ) {

   333 			var coll;

   334 			

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

   336 			if ( type instanceof Backbone.RelationalModel ) {

   337 				type = type.constructor;

   338 			}

   339 			

   340 			// Type should inherit from Backbone.RelationalModel.

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

   342 				coll = new Backbone.Collection();

   343 				coll.model = type;

   344 				

   345 				this._collections.push( coll );

   346 			}

   347 			

   348 			return coll;

   349 		},

   350 

   351 		/**

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

   353 		 * @param type

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

   355 		 * @return {String|Number}

   356 		 */

   357 		resolveIdForItem: function( type, item ) {

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

   359 

   360 			if ( id === null ) {

   361 				if ( item instanceof Backbone.RelationalModel ) {

   362 					id = item.id;

   363 				}

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

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

   366 				}

   367 			}

   368 

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

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

   371 				id = null;

   372 			}

   373 

   374 			return id;

   375 		},

   376 

   377 		/**

   378 		 * Find a specific model of a certain `type` in the store

   379 		 * @param type

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

   381 		 */

   382 		find: function( type, item ) {

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

   384 			var coll = this.getCollection( type );

   385 			

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

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

   388 			if ( coll ) {

   389 				var obj = coll.get( id );

   390 

   391 				if ( obj instanceof type ) {

   392 					return obj;

   393 				}

   394 			}

   395 

   396 			return null;

   397 		},

   398 

   399 		/**

   400 		 * Add a 'model' to its appropriate collection. Retain the original contents of 'model.collection'.

   401 		 * @param {Backbone.RelationalModel} model

   402 		 */

   403 		register: function( model ) {

   404 			var coll = this.getCollection( model );

   405 

   406 			if ( coll ) {

   407 				var modelColl = model.collection;

   408 				coll.add( model );

   409 				this.listenTo( model, 'destroy', this.unregister, this );

   410 				model.collection = modelColl;

   411 			}

   412 		},

   413 

   414 		/**

   415 		 * Check if the given model may use the given `id`

   416 		 * @param model

   417 		 * @param [id]

   418 		 */

   419 		checkId: function( model, id ) {

   420 			var coll = this.getCollection( model ),

   421 				duplicate = coll && coll.get( id );

   422 

   423 			if ( duplicate && model !== duplicate ) {

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

   425 					console.warn( 'Duplicate id! Old RelationalModel=%o, new RelationalModel=%o', duplicate, model );

   426 				}

   427 

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

   429 			}

   430 		},

   431 

   432 		/**

   433 		 * Explicitly update a model's id in its store collection

   434 		 * @param {Backbone.RelationalModel} model

   435 		 */

   436 		update: function( model ) {

   437 			var coll = this.getCollection( model );

   438 			// This triggers updating the lookup indices kept in a collection

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

   440 

   441 			// Trigger an event on model so related models (having the model's new id in their keyContents) can add it.

   442 			model.trigger( 'relational:change:id', model, coll );

   443 		},

   444 

   445 		/**

   446 		 * Remove a 'model' from the store.

   447 		 * @param {Backbone.RelationalModel} model

   448 		 */

   449 		unregister: function( model ) {

   450 			this.stopListening( model, 'destroy', this.unregister );

   451 			var coll = this.getCollection( model );

   452 			coll && coll.remove( model );

   453 		},

   454 

   455 		/**

   456 		 * Reset the `store` to it's original state. The `reverseRelations` are kept though, since attempting to

   457 		 * re-initialize these on models would lead to a large amount of warnings.

   458 		 */

   459 		reset: function() {

   460 			this.stopListening();

   461 			this._collections = [];

   462 			this._subModels = [];

   463 			this._modelScopes = [ exports ];

   464 		}

   465 	});

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

   467 

   468 	/**

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

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

   471 	 *

   472 	 * @param {Backbone.RelationalModel} [instance] Model that this relation is created for. If no model is supplied,

   473 	 *      Relation just tries to instantiate it's `reverseRelation` if specified, and bails out after that.

   474 	 * @param {Object} options

   475 	 * @param {string} options.key

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

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

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

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

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

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

   482 	 * @param {Object} opts

   483 	 */

   484 	Backbone.Relation = function( instance, options, opts ) {

   485 		this.instance = instance;

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

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

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

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

   490 

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

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

   493 

   494 		this.key = this.options.key;

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

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

   497 

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

   499 		this.relatedModel = this.options.relatedModel;

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

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

   502 		}

   503 

   504 		if ( !this.checkPreconditions() ) {

   505 			return;

   506 		}

   507 

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

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

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

   511 					isAutoRelation: true,

   512 					model: this.relatedModel,

   513 					relatedModel: this.model,

   514 					reverseRelation: this.options // current relation is the 'reverseRelation' for its own reverseRelation

   515 				},

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

   517 			) );

   518 		}

   519 

   520 		if ( instance ) {

   521 			var contentKey = this.keySource;

   522 			if ( contentKey !== this.key && typeof this.instance.get( this.key ) === 'object' ) {

   523 				contentKey = this.key;

   524 			}

   525 

   526 			this.setKeyContents( this.instance.get( contentKey ) );

   527 			this.relatedCollection = Backbone.Relational.store.getCollection( this.relatedModel );

   528 

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

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

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

   532 			}

   533 

   534 			// Add this Relation to instance._relations

   535 			this.instance._relations[ this.key ] = this;

   536 

   537 			this.initialize( opts );

   538 

   539 			if ( this.options.autoFetch ) {

   540 				this.instance.fetchRelated( this.key, _.isObject( this.options.autoFetch ) ? this.options.autoFetch : {} );

   541 			}

   542 

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

   544 			this.listenTo( this.instance, 'destroy', this.destroy )

   545 				.listenTo( this.relatedCollection, 'relational:add relational:change:id', this.tryAddRelated )

   546 				.listenTo( this.relatedCollection, 'relational:remove', this.removeRelated )

   547 		}

   548 	};

   549 	// Fix inheritance :\

   550 	Backbone.Relation.extend = Backbone.Model.extend;

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

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

   553 		options: {

   554 			createModels: true,

   555 			includeInJSON: true,

   556 			isAutoRelation: false,

   557 			autoFetch: false,

   558 			parse: false

   559 		},

   560 

   561 		instance: null,

   562 		key: null,

   563 		keyContents: null,

   564 		relatedModel: null,

   565 		relatedCollection: null,

   566 		reverseRelation: null,

   567 		related: null,

   568 

   569 		/**

   570 		 * Check several pre-conditions.

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

   572 		 */

   573 		checkPreconditions: function() {

   574 			var i = this.instance,

   575 				k = this.key,

   576 				m = this.model,

   577 				rm = this.relatedModel,

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

   579 

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

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

   582 				return false;

   583 			}

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

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

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

   587 				return false;

   588 			}

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

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

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

   592 				return false;

   593 			}

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

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

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

   597 				return false;

   598 			}

   599 			// Check if we're not attempting to create a relationship on a `key` that's already used.

   600 			if ( i && _.keys( i._relations ).length ) {

   601 				var existing = _.find( i._relations, function( rel ) {

   602 					return rel.key === k;

   603 				}, this );

   604 

   605 				if ( existing ) {

   606 					warn && console.warn( 'Cannot create relation=%o on %o for model=%o: already taken by relation=%o.',

   607 						this, k, i, existing );

   608 					return false;

   609 				}

   610 			}

   611 

   612 			return true;

   613 		},

   614 

   615 		/**

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

   617 		 * @param {Backbone.Model|Backbone.Collection} related

   618 		 */

   619 		setRelated: function( related ) {

   620 			this.related = related;

   621 

   622 			this.instance.acquire();

   623 			this.instance.attributes[ this.key ] = related;

   624 			this.instance.release();

   625 		},

   626 

   627 		/**

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

   629 		 * relation of the current one.

   630 		 * @param {Backbone.Relation} relation

   631 		 * @return {Boolean}

   632 		 */

   633 		_isReverseRelation: function( relation ) {

   634 			return relation.instance instanceof this.relatedModel && this.reverseRelation.key === relation.key &&

   635 				this.key === relation.reverseRelation.key;

   636 		},

   637 

   638 		/**

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

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

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

   642 		 * @return {Backbone.Relation[]}

   643 		 */

   644 		getReverseRelations: function( model ) {

   645 			var reverseRelations = [];

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

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

   648 			_.each( models || [], function( related ) {

   649 				_.each( related.getRelations() || [], function( relation ) {

   650 						if ( this._isReverseRelation( relation ) ) {

   651 							reverseRelations.push( relation );

   652 						}

   653 					}, this );

   654 			}, this );

   655 			

   656 			return reverseRelations;

   657 		},

   658 

   659 		/**

   660 		 * When `this.instance` is destroyed, cleanup our relations.

   661 		 * Get reverse relation, call removeRelated on each.

   662 		 */

   663 		destroy: function() {

   664 			this.stopListening();

   665 

   666 			if ( this instanceof Backbone.HasOne ) {

   667 				this.setRelated( null );

   668 			}

   669 			else if ( this instanceof Backbone.HasMany ) {

   670 				this.setRelated( this._prepareCollection() );

   671 			}

   672 			

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

   674 				relation.removeRelated( this.instance );

   675 			}, this );

   676 		}

   677 	});

   678 

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

   680 		options: {

   681 			reverseRelation: { type: 'HasMany' }

   682 		},

   683 

   684 		initialize: function( opts ) {

   685 			this.listenTo( this.instance, 'relational:change:' + this.key, this.onChange );

   686 

   687 			var related = this.findRelated( opts );

   688 			this.setRelated( related );

   689 

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

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

   692 				relation.addRelated( this.instance, opts );

   693 			}, this );

   694 		},

   695 

   696 		/**

   697 		 * Find related Models.

   698 		 * @param {Object} [options]

   699 		 * @return {Backbone.Model}

   700 		 */

   701 		findRelated: function( options ) {

   702 			var related = null;

   703 

   704 			options = _.defaults( { parse: this.options.parse }, options );

   705 

   706 			if ( this.keyContents instanceof this.relatedModel ) {

   707 				related = this.keyContents;

   708 			}

   709 			else if ( this.keyContents || this.keyContents === 0 ) { // since 0 can be a valid `id` as well

   710 				var opts = _.defaults( { create: this.options.createModels }, options );

   711 				related = this.relatedModel.findOrCreate( this.keyContents, opts );

   712 			}

   713 

   714 			// Nullify `keyId` if we have a related model; in case it was already part of the relation

   715 			if ( this.related ) {

   716 				this.keyId = null;

   717 			}

   718 

   719 			return related;

   720 		},

   721 

   722 		/**

   723 		 * Normalize and reduce `keyContents` to an `id`, for easier comparison

   724 		 * @param {String|Number|Backbone.Model} keyContents

   725 		 */

   726 		setKeyContents: function( keyContents ) {

   727 			this.keyContents = keyContents;

   728 			this.keyId = Backbone.Relational.store.resolveIdForItem( this.relatedModel, this.keyContents );

   729 		},

   730 

   731 		/**

   732 		 * Event handler for `change:<key>`.

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

   734 		 */

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

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

   737 			if ( this.isLocked() ) {

   738 				return;

   739 			}

   740 			this.acquire();

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

   742 			

   743 			// 'options.__related' is set by 'addRelated'/'removeRelated'. If it is set, the change

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

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

   746 			var changed = _.isUndefined( options.__related ),

   747 				oldRelated = changed ? this.related : options.__related;

   748 			

   749 			if ( changed ) {

   750 				this.setKeyContents( attr );

   751 				var related = this.findRelated( options );

   752 				this.setRelated( related );

   753 			}

   754 			

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

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

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

   758 					relation.removeRelated( this.instance, null, options );

   759 				}, this );

   760 			}

   761 

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

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

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

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

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

   767 			}, this );

   768 			

   769 			// Fire the 'change:<key>' event if 'related' was updated

   770 			if ( !options.silent && this.related !== oldRelated ) {

   771 				var dit = this;

   772 				this.changed = true;

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

   774 					dit.instance.trigger( 'change:' + dit.key, dit.instance, dit.related, options, true );

   775 					dit.changed = false;

   776 				});

   777 			}

   778 			this.release();

   779 		},

   780 

   781 		/**

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

   783 		 */

   784 		tryAddRelated: function( model, coll, options ) {

   785 			if ( ( this.keyId || this.keyId === 0 ) && model.id === this.keyId ) { // since 0 can be a valid `id` as well

   786 				this.addRelated( model, options );

   787 				this.keyId = null;

   788 			}

   789 		},

   790 

   791 		addRelated: function( model, options ) {

   792 			// Allow 'model' to set up its relations before proceeding.

   793 			// (which can result in a call to 'addRelated' from a relation of 'model')

   794 			var dit = this;

   795 			model.queue( function() {

   796 				if ( model !== dit.related ) {

   797 					var oldRelated = dit.related || null;

   798 					dit.setRelated( model );

   799 					dit.onChange( dit.instance, model, _.defaults( { __related: oldRelated }, options ) );

   800 				}

   801 			});

   802 		},

   803 

   804 		removeRelated: function( model, coll, options ) {

   805 			if ( !this.related ) {

   806 				return;

   807 			}

   808 			

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

   810 				var oldRelated = this.related || null;

   811 				this.setRelated( null );

   812 				this.onChange( this.instance, model, _.defaults( { __related: oldRelated }, options ) );

   813 			}

   814 		}

   815 	});

   816 

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

   818 		collectionType: null,

   819 

   820 		options: {

   821 			reverseRelation: { type: 'HasOne' },

   822 			collectionType: Backbone.Collection,

   823 			collectionKey: true,

   824 			collectionOptions: {}

   825 		},

   826 

   827 		initialize: function( opts ) {

   828 			this.listenTo( this.instance, 'relational:change:' + this.key, this.onChange );

   829 			

   830 			// Handle a custom 'collectionType'

   831 			this.collectionType = this.options.collectionType;

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

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

   834 			}

   835 			if ( this.collectionType !== Backbone.Collection && !( this.collectionType.prototype instanceof Backbone.Collection ) ) {

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

   837 			}

   838 

   839 			var related = this.findRelated( opts );

   840 			this.setRelated( related );

   841 		},

   842 

   843 		/**

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

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

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

   847 		 * @return {Backbone.Collection}

   848 		 */

   849 		_prepareCollection: function( collection ) {

   850 			if ( this.related ) {

   851 				this.stopListening( this.related );

   852 			}

   853 

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

   855 				var options = _.isFunction( this.options.collectionOptions ) ?

   856 					this.options.collectionOptions( this.instance ) : this.options.collectionOptions;

   857 

   858 				collection = new this.collectionType( null, options );

   859 			}

   860 

   861 			collection.model = this.relatedModel;

   862 			

   863 			if ( this.options.collectionKey ) {

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

   865 				

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

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

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

   869 					}

   870 				}

   871 				else if ( key ) {

   872 					collection[ key ] = this.instance;

   873 				}

   874 			}

   875 

   876 			this.listenTo( collection, 'relational:add', this.handleAddition )

   877 				.listenTo( collection, 'relational:remove', this.handleRemoval )

   878 				.listenTo( collection, 'relational:reset', this.handleReset );

   879 			

   880 			return collection;

   881 		},

   882 

   883 		/**

   884 		 * Find related Models.

   885 		 * @param {Object} [options]

   886 		 * @return {Backbone.Collection}

   887 		 */

   888 		findRelated: function( options ) {

   889 			var related = null;

   890 

   891 			options = _.defaults( { parse: this.options.parse }, options );

   892 

   893 			// Replace 'this.related' by 'this.keyContents' if it is a Backbone.Collection

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

   895 				this._prepareCollection( this.keyContents );

   896 				related = this.keyContents;

   897 			}

   898 			// Otherwise, 'this.keyContents' should be an array of related object ids.

   899 			// Re-use the current 'this.related' if it is a Backbone.Collection; otherwise, create a new collection.

   900 			else {

   901 				var toAdd = [];

   902 

   903 				_.each( this.keyContents, function( attributes ) {

   904 					if ( attributes instanceof this.relatedModel ) {

   905 						var model = attributes;

   906 					}

   907 					else {

   908 						// If `merge` is true, update models here, instead of during update.

   909 						model = this.relatedModel.findOrCreate( attributes,

   910 							_.extend( { merge: true }, options, { create: this.options.createModels } )

   911 						);

   912 					}

   913 

   914 					model && toAdd.push( model );

   915 				}, this );

   916 

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

   918 					related = this.related;

   919 				}

   920 				else {

   921 					related = this._prepareCollection();

   922 				}

   923 

   924 				// By now, both `merge` and `parse` will already have been executed for models if they were specified.

   925 				// Disable them to prevent additional calls.

   926 				related.set( toAdd, _.defaults( { merge: false, parse: false }, options ) );

   927 			}

   928 

   929 			// Remove entries from `keyIds` that were already part of the relation (and are thus 'unchanged')

   930 			this.keyIds = _.difference( this.keyIds, _.pluck( related.models, 'id' ) );

   931 

   932 			return related;

   933 		},

   934 

   935 		/**

   936 		 * Normalize and reduce `keyContents` to a list of `ids`, for easier comparison

   937 		 * @param {String|Number|String[]|Number[]|Backbone.Collection} keyContents

   938 		 */

   939 		setKeyContents: function( keyContents ) {

   940 			this.keyContents = keyContents instanceof Backbone.Collection ? keyContents : null;

   941 			this.keyIds = [];

   942 

   943 			if ( !this.keyContents && ( keyContents || keyContents === 0 ) ) { // since 0 can be a valid `id` as well

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

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

   946 

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

   948 					var itemId = Backbone.Relational.store.resolveIdForItem( this.relatedModel, item );

   949 					if ( itemId || itemId === 0 ) {

   950 						this.keyIds.push( itemId );

   951 					}

   952 				}, this );

   953 			}

   954 		},

   955 

   956 		/**

   957 		 * Event handler for `change:<key>`.

   958 		 * If the contents of the key are changed, notify old & new reverse relations and initialize the new relation.

   959 		 */

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

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

   962 			this.setKeyContents( attr );

   963 			this.changed = false;

   964 

   965 			var related = this.findRelated( options );

   966 			this.setRelated( related );

   967 

   968 			if ( !options.silent ) {

   969 				var dit = this;

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

   971 					// The `changed` flag can be set in `handleAddition` or `handleRemoval`

   972 					if ( dit.changed ) {

   973 						dit.instance.trigger( 'change:' + dit.key, dit.instance, dit.related, options, true );

   974 						dit.changed = false;

   975 					}

   976 				});

   977 			}

   978 		},

   979 

   980 		/**

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

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

   983 		*/

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

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

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

   987 			this.changed = true;

   988 			

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

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

   991 			}, this );

   992 

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

   994 			var dit = this;

   995 			!options.silent && Backbone.Relational.eventQueue.add( function() {

   996 				dit.instance.trigger( 'add:' + dit.key, model, dit.related, options );

   997 			});

   998 		},

   999 

  1000 		/**

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

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

  1003 		 */

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

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

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

  1007 			this.changed = true;

  1008 			

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

  1010 				relation.removeRelated( this.instance, null, options );

  1011 			}, this );

  1012 			

  1013 			var dit = this;

  1014 			!options.silent && Backbone.Relational.eventQueue.add( function() {

  1015 				 dit.instance.trigger( 'remove:' + dit.key, model, dit.related, options );

  1016 			});

  1017 		},

  1018 

  1019 		handleReset: function( coll, options ) {

  1020 			var dit = this;

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

  1022 			!options.silent && Backbone.Relational.eventQueue.add( function() {

  1023 				dit.instance.trigger( 'reset:' + dit.key, dit.related, options );

  1024 			});

  1025 		},

  1026 

  1027 		tryAddRelated: function( model, coll, options ) {

  1028 			var item = _.contains( this.keyIds, model.id );

  1029 

  1030 			if ( item ) {

  1031 				this.addRelated( model, options );

  1032 				this.keyIds = _.without( this.keyIds, model.id );

  1033 			}

  1034 		},

  1035 

  1036 		addRelated: function( model, options ) {

  1037 			// Allow 'model' to set up its relations before proceeding.

  1038 			// (which can result in a call to 'addRelated' from a relation of 'model')

  1039 			var dit = this;

  1040 			model.queue( function() {

  1041 				if ( dit.related && !dit.related.get( model ) ) {

  1042 					dit.related.add( model, _.defaults( { parse: false }, options ) );

  1043 				}

  1044 			});

  1045 		},

  1046 

  1047 		removeRelated: function( model, coll, options ) {

  1048 			if ( this.related.get( model ) ) {

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

  1050 			}

  1051 		}

  1052 	});

  1053 

  1054 	/**

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

  1056 	 * New events when compared to the original:

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

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

  1059 	 *  - 'change:<key>' (model, related model or collection, options)

  1060 	 */

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

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

  1063 		_relations: null, // Relation instances

  1064 		_isInitialized: false,

  1065 		_deferProcessing: false,

  1066 		_queue: null,

  1067 

  1068 		subModelTypeAttribute: 'type',

  1069 		subModelTypes: null,

  1070 

  1071 		constructor: function( attributes, options ) {

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

  1073 			// Defer 'processQueue', so that when 'Relation.createModels' is used we trigger 'HasMany'

  1074 			// collection events only after the model is really fully set up.

  1075 			// Example: event for "p.on( 'add:jobs' )" -> "p.get('jobs').add( { company: c.id, person: p.id } )".

  1076 			if ( options && options.collection ) {

  1077 				var dit = this,

  1078 					collection = this.collection =  options.collection;

  1079 

  1080 				// Prevent `collection` from cascading down to nested models; they shouldn't go into this `if` clause.

  1081 				delete options.collection;

  1082 

  1083 				this._deferProcessing = true;

  1084 

  1085 				var processQueue = function( model ) {

  1086 					if ( model === dit ) {

  1087 						dit._deferProcessing = false;

  1088 						dit.processQueue();

  1089 						collection.off( 'relational:add', processQueue );

  1090 					}

  1091 				};

  1092 				collection.on( 'relational:add', processQueue );

  1093 

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

  1095 				_.defer( function() {

  1096 					processQueue( dit );

  1097 				});

  1098 			}

  1099 

  1100 			Backbone.Relational.store.processOrphanRelations();

  1101 			

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

  1103 			this._queue.block();

  1104 			Backbone.Relational.eventQueue.block();

  1105 

  1106 			try {

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

  1108 			}

  1109 			finally {

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

  1111 				Backbone.Relational.eventQueue.unblock();

  1112 			}

  1113 		},

  1114 

  1115 		/**

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

  1117 		 */

  1118 		trigger: function( eventName ) {

  1119 			if ( eventName.length > 5 && eventName.indexOf( 'change' ) === 0 ) {

  1120 				var dit = this,

  1121 					args = arguments;

  1122 

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

  1124 					if ( !dit._isInitialized ) {

  1125 						return;

  1126 					}

  1127 

  1128 					// Determine if the `change` event is still valid, now that all relations are populated

  1129 					var changed = true;

  1130 					if ( eventName === 'change' ) {

  1131 						changed = dit.hasChanged();

  1132 					}

  1133 					else {

  1134 						var attr = eventName.slice( 7 ),

  1135 							rel = dit.getRelation( attr );