sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

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

@@ -8,12 +8,12 @@
 /**
   @class
 
-  A ManyArray is used to map an array of record ids back to their 
+  A `ManyArray` is used to map an array of record ids back to their 
   record objects which will be materialized from the owner store on demand.
   
-  Whenever you create a toMany() relationship, the value returned from the 
-  property will be an instance of ManyArray.  You can generally customize the
-  behavior of ManyArray by passing settings to the toMany() helper.
+  Whenever you create a `toMany()` relationship, the value returned from the 
+  property will be an instance of `ManyArray`.  You can generally customize the
+  behavior of ManyArray by passing settings to the `toMany()` helper.
   
   @extends SC.Enumerable
   @extends SC.Array
@@ -24,55 +24,55 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
   /** @scope SC.ManyArray.prototype */ {
 
   /**
-    recordType will tell what type to transform the record to when
+    `recordType` will tell what type to transform the record to when
     materializing the record.
 
     @default null
     @type String
   */
   recordType: null,
-  
+
   /**
-    If set, the record will be notified whenever the array changes so that 
+    If set, the record will be notified whenever the array changes so that
     it can change its own state
-    
+
     @default null
     @type SC.Record
   */
   record: null,
-  
+
   /**
     If set will be used by the many array to get an editable version of the
     storeIds from the owner.
-    
+
     @default null
     @type String
   */
   propertyName: null,
-  
-  
+
+
   /**
-    The ManyAttribute that created this array.
+    The `ManyAttribute` that created this array.
   
     @default null
     @type SC.ManyAttribute
   */
   manyAttribute: null,
-  
+
   /**
-    The store that owns this record array.  All record arrays must have a 
+    The store that owns this record array.  All record arrays must have a
     store to function properly.
-    
+
     @type SC.Store
-    @property 
+    @property
   */
   store: function() {
     return this.get('record').get('store');
   }.property('record').cacheable(),
-  
+
   /**
-    The storeKey for the parent record of this many array.  Editing this 
-    array will place the parent record into a READY_DIRTY state.
+    The `storeKey` for the parent record of this many array.  Editing this 
+    array will place the parent record into a `READY_DIRTY` state.
 
     @type Number
     @property
@@ -83,19 +83,19 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
 
 
   /**
-    Returns the storeIds in read only mode.  Avoids modifying the record 
+    Returns the `storeId`s in read-only mode.  Avoids modifying the record 
     unnecessarily.
-    
+
     @type SC.Array
-    @property 
+    @property
   */
   readOnlyStoreIds: function() {
     return this.get('record').readAttribute(this.get('propertyName'));
   }.property(),
-  
-  
+
+
   /**
-    Returns an editable array of storeIds.  Marks the owner records as 
+    Returns an editable array of `storeId`s.  Marks the owner records as 
     modified. 
     
     @type {SC.Array}
@@ -106,49 +106,49 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
         storeKey = this.get('storeKey'),
         pname    = this.get('propertyName'),
         ret, hash;
-        
-    ret = store.readEditableProperty(storeKey, pname);    
+
+    ret = store.readEditableProperty(storeKey, pname);
     if (!ret) {
       hash = store.readEditableDataHash(storeKey);
-      ret = hash[pname] = [];      
+      ret = hash[pname] = [];
     }
-    
+
     if (ret !== this._prevStoreIds) this.recordPropertyDidChange();
     return ret ;
   }.property(),
-  
-  
+
+
   // ..........................................................
   // COMPUTED FROM OWNER
-  // 
-  
+  //
+
   /**
     Computed from owner many attribute
-    
+
     @type Boolean
-    @property 
+    @property
   */
   isEditable: function() {
     // NOTE: can't use get() b/c manyAttribute looks like a computed prop
     var attr = this.manyAttribute;
     return attr ? attr.get('isEditable') : NO;
   }.property('manyAttribute').cacheable(),
-  
+
   /**
     Computed from owner many attribute
-    
+
     @type String
-    @property 
+    @property
   */
   inverse: function() {
     // NOTE: can't use get() b/c manyAttribute looks like a computed prop
     var attr = this.manyAttribute;
     return attr ? attr.get('inverse') : null;
   }.property('manyAttribute').cacheable(),
-  
+
   /**
     Computed from owner many attribute
-    
+
     @type Boolean
     @property
   */
@@ -160,22 +160,22 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
 
   /**
     Computed from owner many attribute
-    
+
     @type Array
-    @property 
+    @property
   */
   orderBy: function() {
     // NOTE: can't use get() b/c manyAttribute looks like a computed prop
     var attr = this.manyAttribute;
     return attr ? attr.get('orderBy') : null;
   }.property("manyAttribute").cacheable(),
-  
+
   // ..........................................................
   // ARRAY PRIMITIVES
-  // 
+  //
 
   /** @private
-    Returned length is a pass-through to the storeIds array.
+    Returned length is a pass-through to the `storeIds` array.
     
     @type Number
     @property
@@ -190,12 +190,12 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     records.
   */
   objectAt: function(idx) {
-    var recs      = this._records, 
+    var recs      = this._records,
         storeIds  = this.get('readOnlyStoreIds'),
         store     = this.get('store'),
         recordType = this.get('recordType'),
         storeKey, ret, storeId ;
-        
+
     if (!storeIds || !store) return undefined; // nothing to do
     if (recs && (ret=recs[idx])) return ret ; // cached
 
@@ -204,14 +204,14 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     storeId = storeIds.objectAt(idx);
     if (storeId) {
 
-      // if record is not loaded already, then ask the data source to 
+      // if record is not loaded already, then ask the data source to
       // retrieve it
       storeKey = store.storeKeyFor(recordType, storeId);
-      
+
       if (store.readStatus(storeKey) === SC.Record.EMPTY) {
         store.retrieveRecord(recordType, null, storeKey);
       }
-      
+
       recs[idx] = ret = store.materializeRecord(storeKey);
     }
     return ret ;
@@ -219,15 +219,15 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
 
   /** @private
     Pass through to the underlying array.  The passed in objects must be
-    records, which can be converted to storeIds.
+    records, which can be converted to `storeId`s.
   */
   replace: function(idx, amt, recs) {
-    
+
     if (!this.get('isEditable')) {
       throw "%@.%@[] is not editable".fmt(this.get('record'), this.get('propertyName'));
     }
-    
-    var storeIds = this.get('editableStoreIds'), 
+
+    var storeIds = this.get('editableStoreIds'),
         len      = recs ? (recs.get ? recs.get('length') : recs.length) : 0,
         record   = this.get('record'),
         pname    = this.get('propertyName'),
@@ -237,24 +237,24 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     ids = [] ;
     for(i=0;i<len;i++) ids[i] = recs.objectAt(i).get('id');
 
-    // if we have an inverse - collect the list of records we are about to 
+    // if we have an inverse - collect the list of records we are about to
     // remove
     inverse = this.get('inverse');
     if (inverse && amt>0) {
       toRemove = SC.ManyArray._toRemove;
       if (toRemove) SC.ManyArray._toRemove = null; // reuse if possible
       else toRemove = [];
-      
+
       for(i=0;i<amt;i++) toRemove[i] = this.objectAt(idx + i);
     }
-    
-    // pass along - if allowed, this should trigger the content observer 
+
+    // pass along - if allowed, this should trigger the content observer
     storeIds.replace(idx, amt, ids);
 
     // ok, notify records that were removed then added; this way reordered
     // objects are added and removed
     if (inverse) {
-      
+
       // notive removals
       for(i=0;i<amt;i++) {
         inverseRecord = toRemove[i];
@@ -277,77 +277,77 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
           attr.inverseDidAddRecord(inverseRecord, inverse, record, pname);
         }
       }
-      
+
     }
 
     // only mark record dirty if there is no inverse or we are master
     if (record && (!inverse || this.get('isMaster'))) {
       record.recordDidChange(pname);
-    } 
-    
+    }
+
     this.enumerableContentDidChange(idx, amt, len - amt);
-    
+
     return this;
   },
-  
+
   // ..........................................................
   // INVERSE SUPPORT
-  // 
-  
+  //
+
   /**
-    Called by the ManyAttribute whenever a record is removed on the inverse
+    Called by the `ManyAttribute` whenever a record is removed on the inverse
     of the relationship.
-    
+
     @param {SC.Record} inverseRecord the record that was removed
     @returns {SC.ManyArray} receiver
   */
   removeInverseRecord: function(inverseRecord) {
-    
+
     if (!inverseRecord) return this; // nothing to do
     var id = inverseRecord.get('id'),
         storeIds = this.get('editableStoreIds'),
         idx      = (storeIds && id) ? storeIds.indexOf(id) : -1,
         record;
-    
+
     if (idx >= 0) {
       storeIds.removeAt(idx);
       if (this.get('isMaster') && (record = this.get('record'))) {
         record.recordDidChange(this.get('propertyName'));
       }
     }
-    
+
     return this;
   },
 
   /**
-    Called by the ManyAttribute whenever a record is added on the inverse
+    Called by the `ManyAttribute` whenever a record is added on the inverse
     of the relationship.
-    
+
     @param {SC.Record} inverseRecord the record this array is a part of
     @returns {SC.ManyArray} receiver
   */
   addInverseRecord: function(inverseRecord) {
-    
+
     if (!inverseRecord) return this;
     var id = inverseRecord.get('id'),
         storeIds = this.get('editableStoreIds'),
         orderBy  = this.get('orderBy'),
         len      = storeIds.get('length'),
         idx, record;
-        
+
     // find idx to insert at.
     if (orderBy) {
       idx = this._findInsertionLocation(inverseRecord, 0, len, orderBy);
     } else idx = len;
-    
+
     storeIds.insertAt(idx, inverseRecord.get('id'));
     if (this.get('isMaster') && (record = this.get('record'))) {
       record.recordDidChange(this.get('propertyName'));
     }
-    
+
     return this;
   },
-  
+
   /** @private
       binary search to find insertion location
   */
@@ -370,7 +370,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
   _compare: function(a, b, orderBy) {
     var t = SC.typeOf(orderBy),
         ret, idx, len;
-        
+
     if (t === SC.T_FUNCTION) ret = orderBy(a, b);
     else if (t === SC.T_STRING) ret = SC.compare(a,b);
     else {
@@ -381,30 +381,50 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
 
     return ret ;
   },
-  
+
   // ..........................................................
   // INTERNAL SUPPORT
-  //  
+  //
 
-  /** @private 
-    Invoked whenever the storeIds array changes.  Observes changes.
+  /** @private
+    Invoked whenever the `storeIds` array changes.  Observes changes.
   */
   recordPropertyDidChange: function(keys) {
-    
+
     if (keys && !keys.contains(this.get('propertyName'))) return this;
-    
-    var storeIds = this.get('readOnlyStoreIds');
+
+    var storeIds = this.get('readOnlyStoreIds'), oldLen, newLen;
     var prev = this._prevStoreIds, f = this._storeIdsContentDidChange;
 
     if (storeIds === prev) return this; // nothing to do
 
-    if (prev) prev.removeObserver('[]', this, f);
-    this._prevStoreIds = storeIds;
-    if (storeIds) storeIds.addObserver('[]', this, f);
+    if (prev) {
+      prev.removeArrayObservers({
+        target: this,
+        willChange: this.arrayContentWillChange,
+        didChange: f
+      });
 
-    var rev = (storeIds) ? storeIds.propertyRevision : -1 ;
-    this._storeIdsContentDidChange(storeIds, '[]', storeIds, rev);
-    
+      oldLen = prev.get('length');
+    } else {
+      oldLen = 0;
+    }
+
+    if (storeIds) {
+      storeIds.addArrayObservers({
+        target: this,
+        willChange: this.arrayContentWillChange,
+        didChange: f
+      });
+
+      newLen = storeIds.get('length');
+    } else {
+      newLen = 0;
+    }
+
+    this.arrayContentWillChange(0, oldLen, newLen);
+    this._prevStoreIds = storeIds;
+    this._storeIdsContentDidChange(0, oldLen, newLen);
   },
 
   /** @private
@@ -412,11 +432,11 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     dump any cached record lookup and then notify that the enumerable content
     has changed.
   */
-  _storeIdsContentDidChange: function(target, key, value, rev) {
+  _storeIdsContentDidChange: function(start, removedCount, addedCount) {
     this._records = null ; // clear cache
-    this.enumerableContentDidChange();
+    this.arrayContentDidChange(start, removedCount, addedCount);
   },
-  
+
   /** @private */
   unknownProperty: function(key, value) {
     var ret;
@@ -429,5 +449,5 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     sc_super();
     this.recordPropertyDidChange();
   }
-  
+
 }) ;

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

@@ -11,13 +11,13 @@ sc_require('system/store');
   @class
 
   A nested store can buffer changes to a parent store and then commit them
-  all at once.  You usually will use a NestedStore as part of store chaining
+  all at once.  You usually will use a `NestedStore` as part of store chaining
   to stage changes to your object graph before sharing them with the rest of
   the application.
   
   Normally you will not create a nested store directly.  Instead, you can 
-  retrieve a nested store by using the chain() method.  When you are finished
-  working with the nested store, destroy() will dispose of it.
+  retrieve a nested store by using the `chain()` method.  When you are finished
+  working with the nested store, `destroy()` will dispose of it.
   
   @extends SC.Store
   @since SproutCore 1.0
@@ -37,7 +37,7 @@ SC.NestedStore = SC.Store.extend(
   /**
     The parent store this nested store is chained to.  Nested stores must have
     a parent store in order to function properly.  Normally, you create a 
-    nested store using the SC.Store#chain() method and this property will be
+    nested store using the `SC.Store#chain()` method and this property will be
     set for you.
     
     @type SC.Store
@@ -46,7 +46,7 @@ SC.NestedStore = SC.Store.extend(
   parentStore: null,
 
   /**
-    YES if the view is nested. Walk like a duck
+    `YES` if the view is nested. Walk like a duck
     
     @type Boolean
     @default YES
@@ -59,7 +59,7 @@ SC.NestedStore = SC.Store.extend(
     then change the record in the parent store, the changes will not be 
     visible to your nested store until you commit or discard changes.
     
-    If NO, then the attribute hash will lock only when you write data.
+    If `NO`, then the attribute hash will lock only when you write data.
     
     Normally you want to lock your attribute hash the first time you read it.
     This will make your nested store behave most consistently.  However, if
@@ -109,8 +109,8 @@ SC.NestedStore = SC.Store.extend(
   // 
   
   /**
-    find() cannot accept REMOTE queries in a nested store.  This override will
-    verify that condition for you.  See SC.Store#find() for info on using this
+    `find()` cannot accept REMOTE queries in a nested store.  This override will
+    verify that condition for you.  See `SC.Store#find()` for info on using this
     method.
     
     @param {SC.Query} query query object to use.
@@ -223,7 +223,7 @@ SC.NestedStore = SC.Store.extend(
   },
 
   /**
-    Returns the SC.Error object associated with a specific record.
+    Returns the `SC.Error` object associated with a specific record.
 
     Delegates the call to the parent store.
 
@@ -237,7 +237,7 @@ SC.NestedStore = SC.Store.extend(
   },
 
   /**
-    Returns the SC.Error object associated with a specific query.
+    Returns the `SC.Error` object associated with a specific query.
 
     Delegates the call to the parent store.
 
@@ -258,8 +258,8 @@ SC.NestedStore = SC.Store.extend(
   // to use these methods.
   
   /**
-    Returns the current edit status of a storekey.  May be one of INHERITED,
-    EDITABLE, and LOCKED.  Used mostly for unit testing.
+    Returns the current edit status of a storekey.  May be one of `INHERITED`,
+    `EDITABLE`, and `LOCKED`.  Used mostly for unit testing.
     
     @param {Number} storeKey the store key
     @returns {Number} edit status
@@ -399,7 +399,7 @@ SC.NestedStore = SC.Store.extend(
     return sc_super();
   },
   
-  /** @private - book-keeping for a single data hash. */
+  /** @private - bookkeeping for a single data hash. */
   dataHashDidChange: function(storeKeys, rev, statusOnly, key) {
     // update the revision for storeKey.  Use generateStoreKey() because that
     // gaurantees a universally (to this store hierarchy anyway) unique