Linked collection state for ampersand-state

ampersand-link-collection-state.js

// Use this helper function in the model's constructor or initialize function to link a state property to
// a parent collection, using `linkIdKey` to look up the child state.
// Very handy for keeping a sticky reference to a single item in a collection and still maintain
// all the goodness of a child state (like change event bubbling).
// Derived properties that use the linked state property will work as expected.
//
// **NOTE:** *DO NOT* use a derived property to accomplish this. While it may seem tempting at first,
// ampersand collections do not emit `change` events when the collection itself or any of the
// children change (this would be very inefficient). Because of this, the derived property would have
// no way to know when to update. This helper fixes that by tracking changes to the collection
// and setting the linked state as needed.
//
// - `collectionKey`: A string identifying the collection to pull the linked property from.
// - `linkedStateKey`: A string identifying the linked state property. This property should be
//   declared as a session property:
//   ```
//   session: {
//     linkedState: 'state'
//   }
//   ```
// - `linkIdKey`: A string or function identifying the property used to look up the child state in the collection.
//                If `linkIdKey` is a derived property it's up to you to fire change events for that key if you know the result of that function will change.

// Example:

// ```javascript
// var CarDealer = AmpersandState.extend(linkCollectionStateMixin, {
//   collections: {
//     carLot: Cars
//   },
//   
//   initialize: function() {
//     this.linkCollectionState('carLot', 'lastSoldCar', 'lastSoldCarId');
//   },
//   
//   props: {
//     lastSoldCarId: 'number'
//   },
//   
//   session: {
//     lastSoldCar: 'state'
//   }
// });
// ```

var linkCollectionStateMixin = {
  linkCollectionState: function(collectionKey, linkedStateKey, linkIdKey) {
    var updateLinkedState = function() {
      var linkedState = this.get(linkedStateKey);
      var collection = this.get(collectionKey);
      var linkId = this.get(linkIdKey);
      
      if (!collection || !collection.get) {
        throw new Error('expected ' + collectionKey + ' to be a collection');
      }
      
      if (typeof linkedState === 'undefined') {
        this.stopListening(linkedState);
      }
      
      linkedState = collection.get(linkId);
      this.set(linkedStateKey, linkedState);
      
      if (linkedState) {
        this.listenTo(linkedState, 'all', this._getEventBubblingHandler(linkedStateKey));
      }
    }.bind(this);
    
    this.listenTo(this.get(collectionKey), 'all', updateLinkedState);
    this.on('change:' + linkIdKey, updateLinkedState);
    updateLinkedState();
  }
};

Example:

var CarDealer = AmpersandState.extend(linkCollectionStateMixin, {
  collections: {
    carLot: Cars
  },

  initialize: function() {
    this.linkCollectionState('carLot', 'lastSoldCar', 'lastSoldCarId');
  },

  props: {
    lastSoldCarId: 'number'
  },

  session: {
    lastSoldCar: 'state'
  }
});