sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/datastore/system/store.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -32,7 +32,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     An (optional) name of the store, which can be useful during debugging,
     especially if you have multiple nested stores.
     
-    @property {String}
+    @type String
   */
   name: null,
 
@@ -40,7 +40,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     An array of all the chained stores that current rely on the receiver 
     store.
     
-    @property {Array}
+    @type Array
   */
   nestedStores: null,
 
@@ -49,21 +49,23 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     store and save changes.  You normally will set your data source when you
     first create your store in your application.
     
-    @property {SC.DataSource}
+    @type SC.DataSource
   */
   dataSource: null,
   
   /**
     This type of store is not nested.
     
-    @property {Boolean}
+		@default NO
+    @type Boolean
   */
   isNested: NO,
   
   /**
     This type of store is not nested.
     
-    @property {Boolean}
+		@default NO
+    @type Boolean
   */
   commitRecordsAutomatically: NO,
   
@@ -75,7 +77,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     Convenience method.  Sets the current data source to the passed property.
     This will also set the store property on the dataSource to the receiver.
     
-    If you are using this from the core.js method of your app, you may need to
+    If you are using this from the `core.js` method of your app, you may need to
     just pass a string naming your data source class.  If this is the case,
     then your data source will be instantiated the first time it is requested.
     
@@ -92,15 +94,15 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     var ret = this.get('dataSource');
     if (typeof ret === SC.T_STRING) {
       ret = SC.objectForPropertyPath(ret);
-      if (ret) ret = ret.create();
+      if (ret && ret.isClass) ret = ret.create();
       if (ret) this.set('dataSource', ret);
     }
     return ret;
   },
   
   /**
-    Convenience method.  Creates a CascadeDataSource with the passed 
-    data source arguments and sets the CascadeDataSource as the data source 
+    Convenience method.  Creates a `CascadeDataSource` with the passed 
+    data source arguments and sets the `CascadeDataSource` as the data source 
     for the receiver.
     
     @param {SC.DataSource...} dataSource one or more data source arguments
@@ -121,14 +123,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   /**  
     Returns a new nested store instance that can be used to buffer changes
     until you are ready to commit them.  When you are ready to commit your 
-    changes, call commitChanges() or destroyChanges() and then destroy() when
-    you are finished with the chained store altogether.
+    changes, call `commitChanges()` or `destroyChanges()` and then `destroy()`
+    when you are finished with the chained store altogether.
     
-    {{{
-      store = MyApp.store.chain();
-      .. edit edit edit
-      store.commitChanges().destroy();
-    }}}
+        store = MyApp.store.chain();
+        .. edit edit edit
+        store.commitChanges().destroy();
     
     @param {Hash} attrs optional attributes to set on new store
     @param {Class} newStoreClass optional the class of the newly-created nested store (defaults to SC.NestedStore)
@@ -147,6 +147,10 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       newStoreClass = SC.NestedStore;
     }
     
+    // Replicate parent records references
+    attrs.childRecords = this.childRecords ? SC.clone(this.childRecords) : {};
+    attrs.parentRecords = this.parentRecords ? SC.clone(this.parentRecords) : {};
+    
     var ret    = newStoreClass.create(attrs),
         nested = this.nestedStores;
         
@@ -192,7 +196,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
 
     Shared by a store and its child stores until you make edits to it.
     
-    @property {Hash}
+    @type Hash
   */
   dataHashes: null,
 
@@ -203,7 +207,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
 
     Shared by a store and its child stores until you make edits to it.
     
-    @property {Hash}
+    @type Hash
   */
   statuses: null,
     
@@ -217,7 +221,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     changed. A store shares the revisions data with its parent until it 
     starts to make changes to it.
     
-    @property {Hash}
+    @type Hash
   */
   revisions: null,
 
@@ -230,50 +234,51 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     Note that this is kept as an array because it will be stored as a dense 
     array on some browsers, making it faster.
     
-    @property {Array}
+    @type Array
   */
   editables: null,
     
   /**
     A set of storeKeys that need to be committed back to the data source. If
-    you call commitRecords() without passing any other parameters, the keys
+    you call `commitRecords()` without passing any other parameters, the keys
     in this set will be committed instead.
   
-    @property {SC.Set}
+    @type SC.Set
   */
   changelog: null,
   
   /**
-    A set of SC.RecordArray that have been returned from findAll with an 
-    SC.Query. These will all be notified with _notifyRecordArraysWithQuery() 
-    whenever the store changes.
-  
-    @property {Array}
-  */
-  recordArraysWithQuery: null,
-  
-  /**
-    An array of SC.Error objects associated with individual records in the
+    An array of `SC.Error` objects associated with individual records in the
     store (indexed by store keys).
     
     Errors passed form the data source in the call to dataSourceDidError() are
     stored here.
     
-    @property {Array}
+    @type Array
   */
   recordErrors: null,
   
   /**
-    A hash of SC.Error objects associated with queries (indexed by the GUID
+    A hash of `SC.Error` objects associated with queries (indexed by the GUID
     of the query).
     
-    Errors passed from the data source in the call to dataSourceDidErrorQuery()
-    are stored here.
+    Errors passed from the data source in the call to
+    `dataSourceDidErrorQuery()` are stored here.
     
-    @property {Hash}
+    @type Hash
   */
   queryErrors: null,
   
+  /**
+    A hash of child Records and there immediate parents
+  */
+  childRecords: null,
+  
+  /**
+    A hash of parent records with registered children
+  */
+  parentRecords: null,
+  
   // ..........................................................
   // CORE ATTRIBUTE API
   // 
@@ -282,8 +287,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // to use these methods.
   
   /**
-    Returns the current edit status of a storekey.  May be one of EDITABLE or
-    LOCKED.  Used mostly for unit testing.
+    Returns the current edit status of a storekey.  May be one of
+    `EDITABLE` or `LOCKED`.  Used mostly for unit testing.
     
     @param {Number} storeKey the store key
     @returns {Number} edit status
@@ -294,7 +299,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
    
   /** 
-    Returns the data hash for the given storeKey.  This will also 'lock'
+    Returns the data hash for the given `storeKey`.  This will also 'lock'
     the hash so that further edits to the parent store will no 
     longer be reflected in this store until you reset.
     
@@ -306,12 +311,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /** 
-    Returns the data hash for the storeKey, cloned so that you can edit
+    Returns the data hash for the `storeKey`, cloned so that you can edit
     the contents of the attributes if you like.  This will do the extra work
     to make sure that you only clone the attributes one time.  
     
     If you use this method to modify data hash, be sure to call 
-    dataHashDidChange() when you make edits to record the change.
+    `dataHashDidChange()` when you make edits to record the change.
     
     @param {Number} storeKey the store key to retrieve
     @returns {Hash} the attributes hash
@@ -353,7 +358,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     // clone if needed
     if (!editables[propertyName]) {
       ret = hash[propertyName];
-      if (ret && ret.isCopyable) ret = hash[propertyName] = ret.copy();
+      if (ret && ret.isCopyable) ret = hash[propertyName] = ret.copy(YES);
       editables[propertyName] = YES ;
     }
     
@@ -361,12 +366,13 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Replaces the data hash for the storeKey.  This will lock the data hash and
-    mark them as cloned.  This will also call dataHashDidChange() for you.
+    Replaces the data hash for the `storeKey`.  This will lock the data hash
+    and mark them as cloned.  This will also call `dataHashDidChange()` for
+    you.
     
     Note that the hash you set here must be a different object from the 
     original data hash.  Once you make a change here, you must also call
-    dataHashDidChange() to register the changes.
+    `dataHashDidChange()` to register the changes.
 
     If the data hash does not yet exist in the store, this method will add it.
     Pass the optional status to edit the status as well.
@@ -387,21 +393,26 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     if (!editables) editables = this.editables = [];
     editables[storeKey] = 1 ; // use number for dense array support
     
+    var that = this;
+    this._propagateToChildren(storeKey, function(storeKey){
+      that.writeDataHash(storeKey, null, status);
+    });
+    
     return this ;
   },
 
   /**
     Removes the data hash from the store.  This does not imply a deletion of
-    the record.  You could be simply unloading the record.  Eitherway, 
+    the record.  You could be simply unloading the record.  Either way, 
     removing the dataHash will be synced back to the parent store but not to 
     the server.
     
     Note that you can optionally pass a new status to go along with this. If
-    you do not pass a status, it will change the status to SC.RECORD_EMPTY
+    you do not pass a status, it will change the status to `SC.RECORD_EMPTY`
     (assuming you just unloaded the record).  If you are deleting the record
-    you may set it to SC.Record.DESTROYED_CLEAN.
+    you may set it to `SC.Record.DESTROYED_CLEAN`.
     
-    Be sure to also call dataHashDidChange() to register this change.
+    Be sure to also call `dataHashDidChange()` to register this change.
     
     @param {Number} storeKey
     @param {String} status optional new status
@@ -421,7 +432,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   
   /**
     Reads the current status for a storeKey.  This will also lock the data 
-    hash.  If no status is found, returns SC.RECORD_EMPTY.
+    hash.  If no status is found, returns `SC.RECORD_EMPTY`.
     
     @param {Number} storeKey the store key
     @returns {Number} status
@@ -447,7 +458,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   
   /**
     Writes the current status for a storeKey.  If the new status is 
-    SC.Record.ERROR, you may also pass an optional error object.  Otherwise 
+    `SC.Record.ERROR`, you may also pass an optional error object.  Otherwise 
     this param is ignored.
     
     @param {Number} storeKey the store key
@@ -489,10 +500,15 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       storeKey = storeKeys;
     }
     
+    var that = this;
     for(idx=0;idx<len;idx++) {
       if (isArray) storeKey = storeKeys[idx];
       this.revisions[storeKey] = rev;
       this._notifyRecordPropertyChange(storeKey, statusOnly, key);
+      
+      this._propagateToChildren(storeKey, function(storeKey){
+        that.dataHashDidChange(storeKey, null, statusOnly, key);
+      });
     }
     
     return this ;
@@ -500,7 +516,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
 
   /** @private 
     Will push all changes to a the recordPropertyChanges property
-    and execute flush() once at the end of the runloop.
+    and execute `flush()` once at the end of the runloop.
   */
   _notifyRecordPropertyChange: function(storeKey, statusOnly, key) {
     
@@ -546,13 +562,13 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       // If there are changes other than just the status we need to record
       // that information so we do the right thing during the next flush.
       // Note that if we're called multiple times before flush and one call
-      // has statusOnly=true and another has statusOnly=false, the flush will
-      // (correctly) operate in statusOnly=false mode.
+      // has `statusOnly=true` and another has `statusOnly=false`, the flush
+      // will (correctly) operate in `statusOnly=false` mode.
       if (!statusOnly) changes.hasDataChanges.push(storeKey);
       
       // If this is a key specific change, make sure that only those
       // properties/keys are notified.  However, if a previous invocation of
-      // _notifyRecordPropertyChange specified that all keys have changed, we
+      // `_notifyRecordPropertyChange` specified that all keys have changed, we
       // need to respect that.
       if (key) {
         if (!(keys = changes.propertyForStoreKeys[storeKey])) {
@@ -680,27 +696,33 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     // OK, no locking issues.  So let's just copy them changes. 
     // get local reference to values.
     var len = changes.length, i, storeKey, myDataHashes, myStatuses, 
-      myEditables, myRevisions, chDataHashes, chStatuses, chRevisions;
+      myEditables, myRevisions, myParentRecords, myChildRecords, 
+      chDataHashes, chStatuses, chRevisions, chParentRecords, chChildRecords;
     
-    myRevisions  = this.revisions ;
-    myDataHashes = this.dataHashes;
-    myStatuses   = this.statuses;
-    myEditables  = this.editables ;
+    myRevisions     = this.revisions ;
+    myDataHashes    = this.dataHashes;
+    myStatuses      = this.statuses;
+    myEditables     = this.editables ;
+    myParentRecords = this.parentRecords ? this.parentRecords : this.parentRecords ={} ;
+    myChildRecords  = this.childRecords ? this.childRecords : this.childRecords = {} ;
     
     // setup some arrays if needed
     if (!myEditables) myEditables = this.editables = [] ;
-    
-    chDataHashes = nestedStore.dataHashes;
-    chRevisions  = nestedStore.revisions ;
-    chStatuses   = nestedStore.statuses;
+    chDataHashes    = nestedStore.dataHashes;
+    chRevisions     = nestedStore.revisions ;
+    chStatuses      = nestedStore.statuses;
+    chParentRecords = nestedStore.parentRecords || {};
+    chChildRecords  = nestedStore.childRecords || {};
     
     for(i=0;i<len;i++) {
       storeKey = changes[i];
 
       // now copy changes
-      myDataHashes[storeKey] = chDataHashes[storeKey];
-      myStatuses[storeKey]   = chStatuses[storeKey];
-      myRevisions[storeKey]  = chRevisions[storeKey];
+      myDataHashes[storeKey]    = chDataHashes[storeKey];
+      myStatuses[storeKey]      = chStatuses[storeKey];
+      myRevisions[storeKey]     = chRevisions[storeKey];
+      myParentRecords[storeKey] = chParentRecords[storeKey];
+      myChildRecords[storeKey]  = chChildRecords[storeKey];
       
       myEditables[storeKey] = 0 ; // always make dataHash no longer editable
       
@@ -753,65 +775,61 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // 
   
   /**
-    Finds a single record instance with the specified recordType and id or an 
-    array of records matching some query conditions.
+    Finds a single record instance with the specified `recordType` and id or
+    an  array of records matching some query conditions.
     
-    h2. Finding a Single Record
+    Finding a Single Record
+    ---
     
-    If you pass a single recordType and id, this method will return an actual
-    record instance.  If the record has not been loaded into the store yet,
-    this method will ask the data source to retrieve it.  If no data source
-    indicates that it can retrieve the record, then this method will return
-    null.
+    If you pass a single `recordType` and id, this method will return an
+    actual record instance.  If the record has not been loaded into the store
+    yet, this method will ask the data source to retrieve it.  If no data
+    source indicates that it can retrieve the record, then this method will
+    return `null`.
     
     Note that if the record needs to be retrieved from the server, then the
     record instance returned from this method will not have any data yet. 
-    Instead it will have a status of SC.Record.READY_LOADING.  You can monitor
-    the status property to be notified when the record data is available for 
-    you to use it.
+    Instead it will have a status of `SC.Record.READY_LOADING`.  You can
+    monitor the status property to be notified when the record data is
+    available for you to use it.
     
-    h2. Find a Collection of Records
+    Find a Collection of Records
+    ---
     
     If you pass only a record type or a query object, you can instead find 
-    all records matching a specified set of conditions.  When you call find()
-    in this way, it will create a query if needed and pass it to the data
-    source to fetch the results.
+    all records matching a specified set of conditions.  When you call
+    `find()` in this way, it will create a query if needed and pass it to the
+    data source to fetch the results.
     
     If this is the first time you have fetched the query, then the store will
     automatically ask the data source to fetch any records related to it as 
     well.  Otherwise you can refresh the query results at anytime by calling
-    refresh() on the returned RecordArray.
+    `refresh()` on the returned `RecordArray`.
 
     You can detect whether a RecordArray is fetching from the server by 
     checking its status.
     
-    h2. Examples
+    Examples
+    ---
     
     Finding a single record:
     
-    {{{
-      MyApp.store.find(MyApp.Contact, "23"); // returns MyApp.Contact
-    }}}
+        MyApp.store.find(MyApp.Contact, "23"); // returns MyApp.Contact
     
     Finding all records of a particular type:
     
-    {{{
-      MyApp.store.find(MyApp.Contact); // returns SC.RecordArray of contacts
-    }}}
+        MyApp.store.find(MyApp.Contact); // returns SC.RecordArray of contacts
+    
     
     Finding all contacts with first name John:
     
-    {{{
-      var query = SC.Query.local(MyApp.Contact, "firstName = %@", "John");
-      MyApp.store.find(query); // returns SC.RecordArray of contacts
-    }}}
+        var query = SC.Query.local(MyApp.Contact, "firstName = %@", "John");
+        MyApp.store.find(query); // returns SC.RecordArray of contacts
     
     Finding all contacts using a remote query:
     
-    {{{
-      var query = SC.Query.remote(MyApp.Contact);
-      MyApp.store.find(query); // returns SC.RecordArray filled by server
-    }}}
+        var query = SC.Query.remote(MyApp.Contact);
+        MyApp.store.find(query); // returns SC.RecordArray filled by server
     
     @param {SC.Record|String} recordType the expected record type
     @param {String} id the id to load
@@ -843,14 +861,14 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     
     This method will accept a record type or query and return a record array
     matching the results.  This method was commonly used prior to SproutCore 
-    1.0.  It has been deprecated in favor of a single find() method instead.
+    1.0.  It has been deprecated in favor of a single `find()` method instead.
     
     For compatibility, this method will continue to work in SproutCore 1.0 but
     it will raise a warning.  It will be removed in a future version of 
     SproutCore.
   */
   findAll: function(recordType, conditions, params) {
-    console.warn("SC.Store#findAll() will be removed in a future version of SproutCore.  Use SC.Store#find() instead");
+    SC.Logger.warn("SC.Store#findAll() will be removed in a future version of SproutCore.  Use SC.Store#find() instead");
     
 
     if (!recordType || !recordType.isQuery) {
@@ -916,8 +934,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     Called by the record array just before it is destroyed.  This will 
     de-register it from receiving future notifications.
 
-    You should never call this method yourself.  Instead call destroy() on the
-    RecordArray directly.
+    You should never call this method yourself.  Instead call `destroy()` on
+    the `RecordArray` directly.
     
     @param {SC.RecordArray} recordArray the record array
     @returns {SC.Store} receiver
@@ -934,10 +952,10 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   /**
     Called by the record array whenever it needs the data source to refresh
     its contents.  Nested stores will actually just pass this along to the
-    parent store.  The parent store will call fetch() on the data source.
+    parent store.  The parent store will call `fetch()` on the data source.
 
-    You should never call this method yourself.  Instead call refresh() on the
-    RecordArray directly.
+    You should never call this method yourself.  Instead call `refresh()` on
+    the `RecordArray` directly.
     
     @param {SC.Query} query the record array query to refresh
     @returns {SC.Store} receiver
@@ -958,8 +976,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /** @private 
-    Will ask all record arrays that have been returned from findAll
-    with an SC.Query to check their arrays with the new storeKeys
+    Will ask all record arrays that have been returned from `findAll`
+    with an `SC.Query` to check their arrays with the new `storeKey`s
     
     @param {SC.IndexSet} storeKeys set of storeKeys that changed
     @param {SC.Set} recordTypes
@@ -1012,11 +1030,11 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   _TMP_REC_ATTRS: {},
   
   /** 
-    Given a storeKey, return a materialized record.  You will not usually
+    Given a `storeKey`, return a materialized record.  You will not usually
     call this method yourself.  Instead it will used by other methods when
     you find records by id or perform other searches.
 
-    If a recordType has been mapped to the storeKey, then a record instance
+    If a `recordType` has been mapped to the storeKey, then a record instance
     will be returned even if the data hash has not been requested yet.
     
     Each Store instance returns unique record instances for each storeKey.
@@ -1051,12 +1069,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // actually creating record instances.
   
   /**
-    Creates a new record instance with the passed recordType and dataHash.
+    Creates a new record instance with the passed `recordType` and `dataHash`.
     You can also optionally specify an id or else it will be pulled from the 
     data hash.
 
     Note that the record will not yet be saved back to the server.  To save
-    a record to the server, call commitChanges() on the store.
+    a record to the server, call `commitChanges()` on the store.
 
     @param {SC.Record} recordType the record class to use on creation
     @param {Hash} dataHash the JSON attributes to assign to the hash.
@@ -1090,11 +1108,11 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     // any busy or ready state or destroyed dirty state is not allowed
     if ((status & K.BUSY)  || 
         (status & K.READY) || 
-        (status == K.DESTROYED_DIRTY)) { 
+        (status === K.DESTROYED_DIRTY)) { 
       throw id ? K.RECORD_EXISTS_ERROR : K.BAD_STATE_ERROR;
       
     // allow error or destroyed state only with id
-    } else if (!id && (status==SC.DESTROYED_CLEAN || status==SC.ERROR)) {
+    } else if (!id && (status===SC.DESTROYED_CLEAN || status===SC.ERROR)) {
       throw K.BAD_STATE_ERROR;
     }
     
@@ -1120,15 +1138,15 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     ret = this.materializeRecord(storeKey);
     if (ret) ret.propagateToAggregates();
     return ret;
-  },
+  },  
   
   /**
-    Creates an array of new records.  You must pass an array of dataHashes 
-    plus a recordType and, optionally, an array of ids.  This will create an
+    Creates an array of new records.  You must pass an array of `dataHash`es 
+    plus a `recordType` and, optionally, an array of ids.  This will create an
     array of record instances with the same record type.
     
     If you need to instead create a bunch of records with different data types
-    you can instead pass an array of recordTypes, one for each data hash.
+    you can instead pass an array of `recordType`s, one for each data hash.
     
     @param {SC.Record|Array} recordTypes class or array of classes
     @param {Array} dataHashes array of data hashes
@@ -1177,7 +1195,13 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     // remove the data hash, set new status
     this.removeDataHash(storeKey, status);
     this.dataHashDidChange(storeKey);
-            
+    
+    // Handle all the child Records
+    var that = this;
+    this._propagateToChildren(storeKey, function(storeKey){
+      that.unloadRecord(null, null, storeKey, newStatus);
+    });
+      
     return this ;
   },
   
@@ -1186,12 +1210,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     them this way can be faster than retrieving each record and unloading 
     it individually.
 
-    You can pass either a single recordType or an array of recordTypes.  If
-    you pass a single recordType, then the record type will be used for each
+    You can pass either a single `recordType` or an array of `recordType`s. If
+    you pass a single `recordType`, then the record type will be used for each
     record.  If you pass an array, then each id must have a matching record 
     type in the array.
 
-    You can optionally pass an array of storeKeys instead of the recordType
+    You can optionally pass an array of `storeKey`s instead of the `recordType`
     and ids.  In this case the first two parameters will be ignored.  This
     is usually only used by low-level internal methods.  You will not usually
     unload records this way.
@@ -1253,7 +1277,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       return this; // nothing to do
       
     // error out if empty
-    } else if (status == K.EMPTY) {
+    } else if (status === K.EMPTY) {
       throw K.NOT_FOUND_ERROR ;
       
     // error out if busy
@@ -1261,7 +1285,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       throw K.BUSY_ERROR ;
       
     // if new status, destroy but leave in clean state
-    } else if (status == K.READY_NEW) {
+    } else if (status === K.READY_NEW) {
       status = K.DESTROYED_CLEAN ;
       
     // otherwise, destroy in dirty state
@@ -1282,6 +1306,11 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     if(this.get('commitRecordsAutomatically')){
       this.invokeLast(this.commitRecords);
     }
+    
+    var that = this;
+    this._propagateToChildren(storeKey, function(storeKey){
+      that.destroyRecord(null, null, storeKey);
+    });
         
     return this ;
   },
@@ -1291,12 +1320,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     them this way can be faster than retrieving each record and destroying 
     it individually.
     
-    You can pass either a single recordType or an array of recordTypes.  If
-    you pass a single recordType, then the record type will be used for each
+    You can pass either a single `recordType` or an array of `recordType`s. If
+    you pass a single `recordType`, then the record type will be used for each
     record.  If you pass an array, then each id must have a matching record 
     type in the array.
 
-    You can optionally pass an array of storeKeys instead of the recordType
+    You can optionally pass an array of `storeKey`s instead of the `recordType`
     and ids.  In this case the first two parameters will be ignored.  This
     is usually only used by low-level internal methods.  You will not usually
     destroy records this way.
@@ -1327,6 +1356,68 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     return this ;
   },
   
+  /**
+    register a Child Record to the parent
+  */
+  registerChildToParent: function(parentStoreKey, childStoreKey, path){
+    var prs, crs, oldPk, oldChildren, pkRef;
+    // Check the child to see if it has a parent
+    crs = this.childRecords || {};
+    prs = this.parentRecords || {};
+    // first rid of the old parent
+    oldPk = crs[childStoreKey];
+    if (oldPk){
+      oldChildren = prs[oldPk];
+      delete oldChildren[childStoreKey];
+      // this.recordDidChange(null, null, oldPk, key);
+    }
+    pkRef = prs[parentStoreKey] || {};
+    pkRef[childStoreKey] = path || YES;
+    prs[parentStoreKey] = pkRef;
+    crs[childStoreKey] = parentStoreKey;
+    // sync the status of the child
+    this.writeStatus(childStoreKey, this.statuses[parentStoreKey]);
+    this.childRecords = crs;
+    this.parentRecords = prs;
+  },
+  
+  /**
+    materialize the parent when passing in a store key for the child
+  */
+  materializeParentRecord: function(childStoreKey){
+    var pk, crs;
+    if (SC.none(childStoreKey)) return null;
+    crs = this.childRecords;
+    pk = crs ? this.childRecords[childStoreKey] : null ;
+    if (SC.none(pk)) return null;
+    
+    return this.materializeRecord(pk);
+  },
+  
+  /**
+    function for retrieving a parent record key
+
+		@param {Number} storeKey The store key of the parent
+  */
+  parentStoreKeyExists: function(storeKey){
+    if (SC.none(storeKey)) return ;
+    var crs = this.childRecords || {};
+    return crs[storeKey];
+  },
+  
+  /**
+    function that propigates a function all to all children
+  */
+  _propagateToChildren: function(storeKey, func){
+    // Handle all the child Records
+    if ( SC.none(this.parentRecords) ) return;
+    var children = this.parentRecords[storeKey] || {};
+    if (SC.none(func)) return;
+    for (var key in children) {
+      if (children.hasOwnProperty(key)) func(key);
+    }
+  },
+  
   /**
     Notes that the data for the given record id has changed.  The record will
     be committed to the server the next time you commit the root store.  Only
@@ -1382,12 +1473,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     set of record ids, marking them dirty this way can be faster than 
     retrieving each record and destroying it individually.
     
-    You can pass either a single recordType or an array of recordTypes.  If
-    you pass a single recordType, then the record type will be used for each
+    You can pass either a single `recordType` or an array of `recordType`s. If
+    you pass a single `recordType`, then the record type will be used for each
     record.  If you pass an array, then each id must have a matching record 
     type in the array.
 
-    You can optionally pass an array of storeKeys instead of the recordType
+    You can optionally pass an array of `storeKey`s instead of the `recordType`
     and ids.  In this case the first two parameters will be ignored.  This
     is usually only used by low-level internal methods.  
     
@@ -1421,29 +1512,31 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   /**
     Retrieves a set of records from the server.  If the records has 
     already been loaded in the store, then this method will simply return.  
-    Otherwise if your store has a dataSource, this will call the 
-    dataSource to retrieve the record.  Generally you will not need to 
-    call this method yourself. Instead you can just use find().
+    Otherwise if your store has a `dataSource`, this will call the 
+    `dataSource` to retrieve the record.  Generally you will not need to 
+    call this method yourself. Instead you can just use `find()`.
     
     This will not actually create a record instance but it will initiate a 
     load of the record from the server.  You can subsequently get a record 
-    instance itself using materializeRecord()
+    instance itself using `materializeRecord()`.
     
     @param {SC.Record|Array} recordTypes class or array of classes
     @param {Array} ids ids to retrieve
     @param {Array} storeKeys (optional) store keys to retrieve
     @param {Boolean} isRefresh
+    @param {Function|Array} callback function or array of functions
     @returns {Array} storeKeys to be retrieved
   */
-  retrieveRecords: function(recordTypes, ids, storeKeys, isRefresh) {
+  retrieveRecords: function(recordTypes, ids, storeKeys, isRefresh, callbacks) {
     
     var source  = this._getDataSource(),
         isArray = SC.typeOf(recordTypes) === SC.T_ARRAY,
+        hasCallbackArray = SC.typeOf(callbacks) === SC.T_ARRAY,
         len     = (!storeKeys) ? ids.length : storeKeys.length,
         ret     = [],
         rev     = SC.Store.generateStoreKey(),
         K       = SC.Record,
-        recordType, idx, storeKey, status, ok;
+        recordType, idx, storeKey, status, ok, callback;
         
     if (!isArray) recordType = recordTypes;
     
@@ -1457,6 +1550,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
         if (isArray) recordType = recordTypes[idx];
         storeKey = recordType.storeKeyFor(ids[idx]);
       }
+      //collect the callback
+      callback = hasCallbackArray ? callbacks[idx] : callbacks;
       
       // collect status and process
       status = this.readStatus(storeKey);
@@ -1466,7 +1561,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
         this.writeStatus(storeKey, K.BUSY_LOADING);
         this.dataHashDidChange(storeKey, rev, YES);
         ret.push(storeKey);
-
+        this._setCallbackForStoreKey(storeKey, callback, hasCallbackArray, storeKeys);
       // otherwise, ignore record unless isRefresh is YES.
       } else if (isRefresh) {
         // K.READY_CLEAN, K.READY_DIRTY, ignore K.READY_NEW
@@ -1474,7 +1569,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
           this.writeStatus(storeKey, K.BUSY_REFRESH | (status & 0x03)) ;
           this.dataHashDidChange(storeKey, rev, YES);
           ret.push(storeKey);
-
+          this._setCallbackForStoreKey(storeKey, callback, hasCallbackArray, storeKeys);
         // K.BUSY_DESTROYING, K.BUSY_COMMITTING, K.BUSY_CREATING
         } else if ((status == K.BUSY_DESTROYING) || (status == K.BUSY_CREATING) || (status == K.BUSY_COMMITTING)) {
           throw K.BUSY_ERROR ;
@@ -1518,24 +1613,80 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   
   _TMP_RETRIEVE_ARRAY: [],
   
+  _callback_queue: {},
+  
+  /**
+    @private
+    stores the callbacks for the storeKeys that are inflight
+  **/
+  _setCallbackForStoreKey: function(storeKey, callback, hasCallbackArray, storeKeys){
+    var queue = this._callback_queue;
+    if(hasCallbackArray) queue[storeKey] = {callback: callback, otherKeys: storeKeys};
+    else queue[storeKey] = callback;
+  },
+  /**
+    @private
+    retreives and calls callback for `storkey` if exists
+    also handles if a single callback is need for one key
+  **/
+  _retreiveCallbackForStoreKey: function(storeKey){
+    var queue = this._callback_queue,
+        callback = queue[storeKey],
+        allFinished, keys;
+    if(callback){
+      if(SC.typeOf(callback) === SC.T_FUNCTION){
+        callback.call(); //args?
+        delete queue[storeKey]; //cleanup
+      }
+      else if(SC.typeOf(callback) == SC.T_HASH){
+        callback.completed = YES;
+        keys = callback.storeKeys;
+        keys.forEach(function(key){
+          if(!queue[key].completed) allFinished = YES;
+        });
+        if(allFinished){
+          callback.callback.call(); // args?
+          //cleanup
+          keys.forEach(function(key){
+            delete queue[key];
+          });
+        }
+        
+      }
+    }
+  },
+  
+  /*
+    @private
+    
+  */
+  _cancelCallback: function(storeKey){
+    var queue = this._callback_queue;
+    if(queue[storeKey]){
+      delete queue[storeKey];
+    }
+  },
+  
+  
   /**
     Retrieves a record from the server.  If the record has already been loaded
     in the store, then this method will simply return.  Otherwise if your 
-    store has a dataSource, this will call the dataSource to retrieve the 
+    store has a `dataSource`, this will call the `dataSource` to retrieve the 
     record.  Generally you will not need to call this method yourself.  
-    Instead you can just use find().
+    Instead you can just use `find()`.
     
     This will not actually create a record instance but it will initiate a 
     load of the record from the server.  You can subsequently get a record 
-    instance itself using materializeRecord()
+    instance itself using `materializeRecord()`.
 
     @param {SC.Record} recordType class
     @param {String} id id to retrieve
     @param {Number} storeKey (optional) store key
     @param {Boolean} isRefresh
+    @param {Function} callback (optional)
     @returns {Number} storeKey that was retrieved 
   */
-  retrieveRecord: function(recordType, id, storeKey, isRefresh) {
+  retrieveRecord: function(recordType, id, storeKey, isRefresh, callback) {
     var array = this._TMP_RETRIEVE_ARRAY,
         ret;
     
@@ -1548,42 +1699,44 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       id = array;
     }
     
-    ret = this.retrieveRecords(recordType, id, storeKey, isRefresh);
+    ret = this.retrieveRecords(recordType, id, storeKey, isRefresh, callback);
     array.length = 0 ;
     return ret[0];
   },
 
   /**
     Refreshes a record from the server.  If the record has already been loaded
-    in the store, then this method will request a refresh from the dataSource.
-    Otherwise it will attempt to retrieve the record.
+    in the store, then this method will request a refresh from the
+    `dataSource`. Otherwise it will attempt to retrieve the record.
     
     @param {String} id to id of the record to load
     @param {SC.Record} recordType the expected record type
     @param {Number} storeKey (optional) optional store key
+    @param {Function} callback (optional) when refresh complets
     @returns {Boolean} YES if the retrieval was a success.
   */
-  refreshRecord: function(recordType, id, storeKey) {
-    return !!this.retrieveRecord(recordType, id, storeKey, YES);
+  refreshRecord: function(recordType, id, storeKey, callback) {
+    return !!this.retrieveRecord(recordType, id, storeKey, YES, callback);
   },
 
   /**
     Refreshes a set of records from the server.  If the records has already been loaded
-    in the store, then this method will request a refresh from the dataSource.
-    Otherwise it will attempt to retrieve them.
+    in the store, then this method will request a refresh from the
+    `dataSource`. Otherwise it will attempt to retrieve them.
     
     @param {SC.Record|Array} recordTypes class or array of classes
     @param {Array} ids ids to destroy
     @param {Array} storeKeys (optional) store keys to destroy
+    @param {Function} callback (optional) when refresh complets
     @returns {Boolean} YES if the retrieval was a success.
   */
-  refreshRecords: function(recordTypes, ids, storeKeys) {
-    var ret = this.retrieveRecords(recordTypes, ids, storeKeys, YES);
+  refreshRecords: function(recordTypes, ids, storeKeys, callback) {
+    var ret = this.retrieveRecords(recordTypes, ids, storeKeys, YES, callback);
     return ret && ret.length>0;
   },
     
   /**
-    Commits the passed store keys or ids. If no storeKeys are given 
+    Commits the passed store keys or ids. If no `storeKey`s are given,
     it will commit any records in the changelog. 
     
     Based on the current state of the record, this will ask the data 
@@ -1595,17 +1748,18 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     @param {SC.Set} storeKeys to commit
     @param {Hash} params optional additional parameters to pass along to the
       data source
-
+    @param {Function|Array} callback function or array of callbacks
+    
     @returns {Boolean} if the action was succesful.
   */
-  commitRecords: function(recordTypes, ids, storeKeys, params) {
-    
+  commitRecords: function(recordTypes, ids, storeKeys, params, callbacks) {
     var source    = this._getDataSource(),
-        isArray   = SC.typeOf(recordTypes) === SC.T_ARRAY,    
+        isArray   = SC.typeOf(recordTypes) === SC.T_ARRAY,
+        hasCallbackArray = SC.typeOf(callbacks) === SC.T_ARRAY,    
         retCreate= [], retUpdate= [], retDestroy = [], 
         rev       = SC.Store.generateStoreKey(),
         K         = SC.Record,
-        recordType, idx, storeKey, status, key, ret, len ;
+        recordType, idx, storeKey, status, key, ret, len, callback;
 
     // If no params are passed, look up storeKeys in the changelog property.
     // Remove any committed records from changelog property.
@@ -1627,6 +1781,9 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
         storeKey = recordType.storeKeyFor(ids[idx]);
       }
       
+      //collect the callback
+      callback = hasCallbackArray ? callbacks[idx] : callbacks;
+      
       // collect status and process
       status = this.readStatus(storeKey);
       
@@ -1638,14 +1795,17 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
           this.writeStatus(storeKey, K.BUSY_CREATING);
           this.dataHashDidChange(storeKey, rev, YES);
           retCreate.push(storeKey);
+          this._setCallbackForStoreKey(storeKey, callback, hasCallbackArray, storeKeys);
         } else if (status==K.READY_DIRTY) {
           this.writeStatus(storeKey, K.BUSY_COMMITTING);
           this.dataHashDidChange(storeKey, rev, YES);
           retUpdate.push(storeKey);
+          this._setCallbackForStoreKey(storeKey, callback, hasCallbackArray, storeKeys);
         } else if (status==K.DESTROYED_DIRTY) {
           this.writeStatus(storeKey, K.BUSY_DESTROYING);
           this.dataHashDidChange(storeKey, rev, YES);
           retDestroy.push(storeKey);
+          this._setCallbackForStoreKey(storeKey, callback, hasCallbackArray, storeKeys);
         } else if (status==K.DESTROYED_CLEAN) {
           this.dataHashDidChange(storeKey, rev, YES);
         }
@@ -1684,9 +1844,10 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     @param {Number} storeKey the storeKey of the record to commit
     @param {Hash} params optional additonal params that will passed down
       to the data source
+    @param {Function|Array} callback function or array of functions
     @returns {Boolean} if the action was successful.
   */
-  commitRecord: function(recordType, id, storeKey, params) {
+  commitRecord: function(recordType, id, storeKey, params, callback) {
     var array = this._TMP_RETRIEVE_ARRAY,
         ret ;
     if (id === undefined && storeKey === undefined ) return NO;
@@ -1699,7 +1860,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       id = array;
     }
     
-    ret = this.commitRecords(recordType, id, storeKey, params);
+    ret = this.commitRecords(recordType, id, storeKey, params, callback);
     array.length = 0 ;
     return ret;
   },
@@ -1735,11 +1896,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
       }
       if(storeKey) {
         status = this.readStatus(storeKey);
-
+        
         if ((status == K.EMPTY) || (status == K.ERROR)) {
           throw K.NOT_FOUND_ERROR ;
         }
         ret.push(storeKey);
+        this._cancelCallback(storeKey);
       }
     }
     
@@ -1782,19 +1944,19 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     recordType and a data hashes and either add or update the 
     record in the store. 
     
-    The loaded records will be in an SC.Record.READY_CLEAN state, indicating
+    The loaded records will be in an `SC.Record.READY_CLEAN` state, indicating
     they were loaded from the data source and do not need to be committed 
     back before changing.
     
     This method will check the state of the storeKey and call either 
-    pushRetrieve() or dataSourceDidComplete().  The standard state constraints 
+    `pushRetrieve()` or `dataSourceDidComplete()`.  The standard state constraints 
     for these methods apply here.
     
-    The return value will be the storeKey used for the push.  This is often
-    convenient to pass into loadQuery(), if you are fetching a remote query.
+    The return value will be the `storeKey` used for the push.  This is often
+    convenient to pass into `loadQuery()`, if you are fetching a remote query.
     
     If you are upgrading from a pre SproutCore 1.0 application, this method 
-    is the closest to the old updateRecord().
+    is the closest to the old `updateRecord()`.
     
     @param {SC.Record} recordType the record type
     @param {Array} dataHash to update
@@ -1815,8 +1977,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     ret = storeKey = recordType.storeKeyFor(id); // needed to cache
       
     if (this.readStatus(storeKey) & K.BUSY) {
-        this.dataSourceDidComplete(storeKey, dataHash, id);
-      } else this.pushRetrieve(recordType, id, dataHash, storeKey);
+      this.dataSourceDidComplete(storeKey, dataHash, id);
+    } else this.pushRetrieve(recordType, id, dataHash, storeKey);
     
     // return storeKey
     return ret ;
@@ -1828,19 +1990,19 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     recordType and an array of data hashes and either add or update the 
     record in the store. 
     
-    The loaded records will be in an SC.Record.READY_CLEAN state, indicating
+    The loaded records will be in an `SC.Record.READY_CLEAN` state, indicating
     they were loaded from the data source and do not need to be committed 
     back before changing.
     
     This method will check the state of each storeKey and call either 
-    pushRetrieve() or dataSourceDidComplete().  The standard state constraints 
-    for these methods apply here.
+    `pushRetrieve()` or `dataSourceDidComplete()`.  The standard state 
+    constraints for these methods apply here.
     
     The return value will be the storeKeys used for each push.  This is often
-    convenient to pass into loadQuery(), if you are fetching a remote query.
+    convenient to pass into `loadQuery()`, if you are fetching a remote query.
     
     If you are upgrading from a pre SproutCore 1.0 application, this method 
-    is the closest to the old updateRecords().
+    is the closest to the old `updateRecords()`.
     
     @param {SC.Record} recordTypes the record type or array of record types
     @param {Array} dataHashes array of data hashes to update
@@ -1877,7 +2039,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
 
   /**
-    Returns the SC.Error object associated with a specific record.
+    Returns the `SC.Error` object associated with a specific record.
 
     @param {Number} storeKey The store key of the record.
  
@@ -1889,7 +2051,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
 
   /**
-    Returns the SC.Error object associated with a specific query.
+    Returns the `SC.Error` object associated with a specific query.
 
     @param {SC.Query} query The SC.Query with which the error is associated.
  
@@ -1906,7 +2068,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // Mathods called by the data source on the store
 
   /**
-    Called by a dataSource when it cancels an inflight operation on a 
+    Called by a `dataSource` when it cancels an inflight operation on a 
     record.  This will transition the record back to it non-inflight state.
     
     @param {Number} storeKey record store key to cancel
@@ -1920,7 +2082,6 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     // DESTROYED_DIRTY
     if (!(status & K.BUSY)) {
       throw K.BAD_STATE_ERROR; // should never be called in this state
-      
     }
     
     // otherwise, determine proper state transition
@@ -1954,13 +2115,14 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     } 
     this.writeStatus(storeKey, status) ;
     this.dataHashDidChange(storeKey, null, YES);
+    this._cancelCallback(storeKey);
     
     return this ;
   },
   
   /**
     Called by a data source when it creates or commits a record.  Passing an
-    optional id will remap the storeKey to the new record id.  This is 
+    optional id will remap the `storeKey` to the new record id.  This is 
     required when you commit a record that does not have an id yet.
     
     @param {Number} storeKey record store key to change to READY_CLEAN state
@@ -1988,6 +2150,14 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     
     statusOnly = dataHash || newId ? NO : YES;
     this.dataHashDidChange(storeKey, null, statusOnly);
+
+    // Force record to refresh its cached properties based on store key
+    var record = this.materializeRecord(storeKey);
+    if (record != null) {
+      record.notifyPropertyChange('status');
+    }
+    //update callbacks
+    this._retreiveCallbackForStoreKey(storeKey);
     
     return this ;
   },
@@ -2014,6 +2184,14 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     this.removeDataHash(storeKey, status) ;
     this.dataHashDidChange(storeKey);
 
+    // Force record to refresh its cached properties based on store key
+    var record = this.materializeRecord(storeKey);
+    if (record != null) {
+      record.notifyPropertyChange('status');
+    }
+
+    this._retreiveCallbackForStoreKey(storeKey);
+
     return this ;
   },
 
@@ -2029,7 +2207,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
 
     // EMPTY, ERROR, READY_CLEAN, READY_NEW, READY_DIRTY, DESTROYED_CLEAN,
     // DESTROYED_DIRTY
-    if (!(status & K.BUSY)) throw K.BAD_STATE_ERROR; 
+    if (!(status & K.BUSY)) { throw K.BAD_STATE_ERROR; }
 
     // otherwise, determine proper state transition
     else status = K.ERROR ;
@@ -2043,6 +2221,13 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     this.writeStatus(storeKey, status) ;
     this.dataHashDidChange(storeKey, null, YES);
 
+    // Force record to refresh its cached properties based on store key
+    var record = this.materializeRecord(storeKey);
+    if (record != null) {
+      record.notifyPropertyChange('status');
+    }
+
+    this._retreiveCallbackForStoreKey(storeKey);
     return this ;
   },
 
@@ -2142,21 +2327,21 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // FETCH CALLBACKS
   // 
   
-  // NOTE: although these method works on RecordArray instances right now.
+  // **NOTE**: although these method works on RecordArray instances right now.
   // They could be optimized to actually share query results between nested
   // stores.  This is why these methods are implemented here instead of 
-  // directly on Query or RecordArray objects.
+  // directly on `Query` or `RecordArray` objects.
   
   /**
     Sets the passed array of storeKeys as the new data for the query.  You
     can call this at any time for a remote query to update its content.  If
-    you want to use incremental loading, then pass a SparseArray object.
+    you want to use incremental loading, then pass a `SparseArray` object.
     
     If the query you pass is not a REMOTE query, then this method will raise
     an exception.  This will also implicitly transition the query state to 
-    SC.Record.READY.
+    `SC.Record.READY`.
     
-    If you called loadRecords() before to load the actual content, you can
+    If you called `loadRecords()` before to load the actual content, you can
     call this method with the return value of that method to actually set the
     storeKeys on the result.
     
@@ -2181,7 +2366,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
     query.  This will put the query into a READY state if it was loading.
     
     Note that if the query is a REMOTE query, then you must separately load 
-    the results into the query using loadQueryResults().  If the query is 
+    the results into the query using `loadQueryResults()`.  If the query is 
     LOCAL, then the query will update automatically with any new records you 
     added to the store.
     
@@ -2302,7 +2487,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   // 
 
   /** 
-    Given a storeKey, return the primaryKey.
+    Given a `storeKey`, return the `primaryKey`.
   
     @param {Number} storeKey the store key
     @returns {String} primaryKey value
@@ -2322,8 +2507,8 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Given a recordType and primaryKey, find the storeKey. If the primaryKey 
-    has not been assigned a storeKey yet, it will be added.
+    Given a `recordType` and `primaryKey`, find the `storeKey`. If the
+    `primaryKey` has not been assigned a `storeKey` yet, it will be added.
     
     @param {SC.Record} recordType the record type
     @param {String} primaryKey the primary key
@@ -2334,11 +2519,12 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Given a primaryKey value for the record, returns the associated
-    storeKey.  As opposed to storeKeyFor() however, this method
-    will NOT generate a new storeKey but returned undefined.
+    Given a `primaryKey` value for the record, returns the associated
+    `storeKey`.  As opposed to `storeKeyFor()` however, this method
+    will **NOT** generate a new `storeKey` but returned `undefined`.
     
-    @param {String} id a record id
+    @param {SC.Record} recordType the record type
+    @param {String} primaryKey the primary key
     @returns {Number} a storeKey.
   */
   storeKeyExists: function(recordType, primaryKey) {
@@ -2346,7 +2532,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Finds all storeKeys of a certain record type in this store
+    Finds all `storeKey`s of a certain record type in this store
     and returns an array.
     
     @param {SC.Record} recordType
@@ -2372,7 +2558,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Finds all storeKeys in this store
+    Finds all `storeKey`s in this store
     and returns an array.
     
     @returns {Array} set of storeKeys
@@ -2392,7 +2578,7 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   },
   
   /**
-    Returns string representation of a storeKey, with status.
+    Returns string representation of a `storeKey`, with status.
     
     @param {Number} storeKey
     @returns {String}
@@ -2404,13 +2590,13 @@ SC.Store = SC.Object.extend( /** @scope SC.Store.prototype */ {
   
 }) ;
 
-SC.Store.mixin({
+SC.Store.mixin(/** @scope SC.Store.prototype */{
   
   /**
     Standard error raised if you try to commit changes from a nested store
     and there is a conflict.
     
-    @property {Error}
+    @type Error
   */
   CHAIN_CONFLICT_ERROR: new Error("Nested Store Conflict"),
   
@@ -2418,7 +2604,7 @@ SC.Store.mixin({
     Standard error if you try to perform an operation on a nested store 
     without a parent.
   
-    @property {Error}
+    @type Error
   */
   NO_PARENT_STORE_ERROR: new Error("Parent Store Required"),
   
@@ -2426,7 +2612,7 @@ SC.Store.mixin({
     Standard error if you try to perform an operation on a nested store that
     is only supported in root stores.
     
-    @property {Error}
+    @type Error
   */
   NESTED_STORE_UNSUPPORTED_ERROR: new Error("Unsupported In Nested Store"),
   
@@ -2434,14 +2620,14 @@ SC.Store.mixin({
     Standard error if you try to retrieve a record in a nested store that is
     dirty.  (This is allowed on the main store, but not in nested stores.)
     
-    @property {Error}
+    @type Error
   */
   NESTED_STORE_RETRIEVE_DIRTY_ERROR: new Error("Cannot Retrieve Dirty Record in Nested Store"),
 
   /**
     Data hash state indicates the data hash is currently editable
     
-    @property {String}
+    @type String
   */
   EDITABLE:  'editable',
   
@@ -2449,7 +2635,7 @@ SC.Store.mixin({
     Data hash state indicates the hash no longer tracks changes from a 
     parent store, but it is not editable.
     
-    @property {String}
+    @type String
   */
   LOCKED:    'locked',
 
@@ -2457,28 +2643,28 @@ SC.Store.mixin({
     Data hash state indicates the hash is tracking changes from the parent
     store and is not editable.
     
-    @property {String}
+    @type String
   */
   INHERITED: 'inherited',
   
   /** @private
     This array maps all storeKeys to primary keys.  You will not normally
-    access this method directly.  Instead use the idFor() and 
-    storeKeyFor() methods on SC.Record.
+    access this method directly.  Instead use the `idFor()` and 
+    `storeKeyFor()` methods on `SC.Record`.
   */
   idsByStoreKey: [],
   
   /** @private
-    Maps all storeKeys to a recordType.  Once a storeKey is associated with 
-    a primaryKey and recordType that remains constant throughout the lifetime
-    of the application.
+    Maps all `storeKey`s to a `recordType`.  Once a `storeKey` is associated
+    with a `primaryKey` and `recordType` that remains constant throughout the
+    lifetime of the application.
   */
   recordTypesByStoreKey: {},
   
   /** @private
-    Maps some storeKeys to query instance.  Once a storeKey is associated with
-    a query instance, that remains constant through the lifetime of the 
-    application.  If a Query is destroyed, it will remove itself from this 
+    Maps some `storeKeys` to query instance.  Once a `storeKey` is associated
+    with a query instance, that remains constant through the lifetime of the 
+    application.  If a `Query` is destroyed, it will remove itself from this 
     list.
     
     Don't access this directly.  Use queryFor().
@@ -2493,13 +2679,13 @@ SC.Store.mixin({
   /**
     Generates a new store key for use.
     
-    @property {Number}
+    @type Number
   */
   generateStoreKey: function() { return this.nextStoreKey++; },
   
   /** 
-    Given a storeKey returns the primaryKey associated with the key.
-    If not primaryKey is associated with the storeKey, returns null.
+    Given a `storeKey` returns the `primaryKey` associated with the key.
+    If no `primaryKey` is associated with the `storeKey`, returns `null`.
     
     @param {Number} storeKey the store key
     @returns {String} the primary key or null
@@ -2509,8 +2695,8 @@ SC.Store.mixin({
   },
   
   /**
-    Given a storeKey, returns the query object associated with the key.  If
-    no query is associated with the storeKey, returns null.
+    Given a `storeKey`, returns the query object associated with the key.  If
+    no query is associated with the `storeKey`, returns `null`.
     
     @param {Number} storeKey the store key
     @returns {SC.Query} query query object
@@ -2520,8 +2706,8 @@ SC.Store.mixin({
   },
   
   /**
-    Given a storeKey returns the SC.Record class associated with the key.
-    If no record type is associated with the store key, returns null.
+    Given a `storeKey` returns the `SC.Record` class associated with the key.
+    If no record type is associated with the store key, returns `null`.
     
     The SC.Record class will only be found if you have already called
     storeKeyFor() on the record.
@@ -2534,8 +2720,8 @@ SC.Store.mixin({
   },
   
   /**
-    Swaps the primaryKey mapped to the given storeKey with the new 
-    primaryKey.  If the storeKey is not currently associated with a record
+    Swaps the `primaryKey` mapped to the given storeKey with the new 
+    `primaryKey`.  If the `storeKey` is not currently associated with a record
     this will raise an exception.
     
     @param {Number} storeKey the existing store key
@@ -2566,10 +2752,10 @@ SC.Store.mixin({
   },
   
   /**
-    Swaps the recordType recorded for a given storeKey.  Normally you should
-    not call this method directly as it can damage the store behavior.  This
-    method is used by other store methods to set the recordType for a 
-    storeKey.
+    Swaps the `recordType` recorded for a given `storeKey`.  Normally you
+    should not call this method directly as it can damage the store behavior.
+    This method is used by other store methods to set the `recordType` for a 
+    `storeKey`.
     
     @param {Integer} storeKey the store key
     @param {SC.Record} recordType a record class
@@ -2604,11 +2790,11 @@ SC.Store._getDefaultStore = function() {
 
   DEPRECATED
   
-  Included for compatibility, loads data hashes with the named recordType. 
-  If no recordType is passed, expects to find a recordType property in the 
-  data hashes.  dataSource and isLoaded params are ignored.
+  Included for compatibility, loads data hashes with the named `recordType`. 
+  If no `recordType` is passed, expects to find a `recordType` property in the 
+  data hashes.  `dataSource` and `isLoaded` params are ignored.
   
-  Calls SC.Store#loadRecords() on the default store. Do not use this method in 
+  Calls `SC.Store#loadRecords()` on the default store. Do not use this method in 
   new code.  
   
   @param {Array} dataHashes data hashes to import
@@ -2619,7 +2805,7 @@ SC.Store._getDefaultStore = function() {
 */
 SC.Store.updateRecords = function(dataHashes, dataSource, recordType, isLoaded) {
   
-  console.warn("SC.Store.updateRecords() is deprecated.  Use loadRecords() instead");
+  SC.Logger.warn("SC.Store.updateRecords() is deprecated.  Use loadRecords() instead");
   
   var store = this._getDefaultStore(),
       len   = dataHashes.length,
@@ -2646,8 +2832,8 @@ SC.Store.updateRecords = function(dataHashes, dataSource, recordType, isLoaded)
   DEPRECATED 
 
   Finds a record with the passed guid on the default store.  This is included
-  only for compatibility.  You should use the newer find() method defined on
-  SC.Store instead.
+  only for compatibility.  You should use the newer `find()` method defined on
+  `SC.Store` instead.
   
   @param {String} guid the guid
   @param {SC.Record} recordType expected record type
@@ -2661,8 +2847,8 @@ SC.Store.find = function(guid, recordType) {
 
   DEPRECATED 
 
-  Passes through to findAll on default store.  This is included only for 
-  compatibility.  You should use the newer findAll() defined on SC.Store
+  Passes through to `findAll` on default store.  This is included only for 
+  compatibility.  You should use the newer `findAll()` defined on `SC.Store`
   instead.
   
   @param {Hash} filter search parameters