sproutcore 1.10.3.1 → 1.11.0.rc1

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

@@ -31,7 +31,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     var readOnlyStoreIds = this.get('readOnlyStoreIds'),
       length = this.get('length');
 
-    return "%@({\n    ids: [%@],\n    length: %@,\n    … })".fmt(this.constructor.toString(), readOnlyStoreIds, length);
+    return "%@({\n  ids: [%@],\n  length: %@,\n  … })".fmt(sc_super(), readOnlyStoreIds, length);
   },
 
   /* END DEBUG ONLY PROPERTIES AND METHODS */
@@ -80,7 +80,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type SC.Store
     @property
   */
-  store: function() {
+  store: function () {
     return this.get('record').get('store');
   }.property('record').cacheable(),
 
@@ -91,10 +91,28 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type Number
     @property
   */
-  storeKey: function() {
+  storeKey: function () {
     return this.get('record').get('storeKey');
   }.property('record').cacheable(),
 
+  /**
+    Determines whether the new record (i.e. unsaved) support should be enabled
+    or not.
+
+    Normally, all records in the many array should already have been previously
+    committed to a remote data store and have an actual `id`. However, with
+    `supportNewRecords` set to true, adding records without an `id `to the many
+    array will assign unique temporary ids to the new records.
+
+    *Note:* You must update the many array after the new records are successfully
+    committed and have real ids. This is done by calling `updateNewRecordId()`
+    on the many array. In the future this should be automatic.
+
+    @type Boolean
+    @default false
+    @since SproutCore 1.11.0
+  */
+  supportNewRecords: NO,
 
   /**
     Returns the `storeId`s in read-only mode.  Avoids modifying the record
@@ -103,7 +121,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type SC.Array
     @property
   */
-  readOnlyStoreIds: function() {
+  readOnlyStoreIds: function () {
     return this.get('record').readAttribute(this.get('propertyName'));
   }.property(),
 
@@ -115,7 +133,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type {SC.Array}
     @property
   */
-  editableStoreIds: function() {
+  editableStoreIds: function () {
     var store    = this.get('store'),
         storeKey = this.get('storeKey'),
         pname    = this.get('propertyName'),
@@ -127,8 +145,8 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
       ret = hash[pname] = [];
     }
 
-    if (ret !== this._prevStoreIds) this.recordPropertyDidChange();
-    return ret ;
+    // if (ret !== this._sc_prevStoreIds) this.recordPropertyDidChange();
+    return ret;
   }.property(),
 
 
@@ -142,7 +160,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type Boolean
     @property
   */
-  isEditable: function() {
+  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;
@@ -154,7 +172,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type String
     @property
   */
-  inverse: function() {
+  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;
@@ -166,7 +184,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type Boolean
     @property
   */
-  isMaster: function() {
+  isMaster: function () {
     // NOTE: can't use get() b/c manyAttribute looks like a computed prop
     var attr = this.manyAttribute;
     return attr ? attr.get('isMaster') : null;
@@ -178,7 +196,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type Array
     @property
   */
-  orderBy: function() {
+  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;
@@ -194,7 +212,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @type Number
     @property
   */
-  length: function() {
+  length: function () {
     var storeIds = this.get('readOnlyStoreIds');
     return storeIds ? storeIds.get('length') : 0;
   }.property('readOnlyStoreIds'),
@@ -203,39 +221,47 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     Looks up the store id in the store ids array and materializes a
     records.
   */
-  objectAt: function(idx) {
-    var recs      = this._records,
-        storeIds  = this.get('readOnlyStoreIds'),
-        store     = this.get('store'),
-        recordType = this.get('recordType'),
-        storeKey, ret, storeId ;
+  objectAt: function (idx) {
+    var recs = this._records,
+      storeIds  = this.get('readOnlyStoreIds'),
+      store = this.get('store'),
+      recordType = this.get('recordType'),
+      len = storeIds ? storeIds.length : 0,
+      storeKey, ret, storeId;
 
     if (!storeIds || !store) return undefined; // nothing to do
-    if (recs && (ret=recs[idx])) return ret ; // cached
+    if (recs && (ret = recs[idx])) return ret; // cached
 
-    // not in cache, materialize
-    if (!recs) this._records = recs = [] ; // create cache
+    // If not a good index return undefined
+    if (idx >= len) return undefined;
     storeId = storeIds.objectAt(idx);
-    if (storeId) {
+    if (!storeId) return undefined;
 
-      // if record is not loaded already, then ask the data source to
-      // retrieve it
-      storeKey = store.storeKeyFor(recordType, storeId);
+    // not in cache, materialize
+    if (!recs) this._records = recs = []; // create cache
 
-      if (store.readStatus(storeKey) === SC.Record.EMPTY) {
-        store.retrieveRecord(recordType, null, storeKey);
-      }
+    // Handle transient records.
+    if (typeof storeId === SC.T_STRING && storeId.indexOf('_sc_id_placeholder_') === 0) {
+      storeKey = storeId.replace('_sc_id_placeholder_', '');
+    } else {
+      storeKey = store.storeKeyFor(recordType, storeId);
+    }
 
-      recs[idx] = ret = store.materializeRecord(storeKey);
+    // If record is not loaded already, then ask the data source to retrieve it.
+    if (store.readStatus(storeKey) === SC.Record.EMPTY) {
+      store.retrieveRecord(recordType, null, storeKey);
     }
-    return ret ;
+
+    recs[idx] = ret = store.materializeRecord(storeKey);
+
+    return ret;
   },
 
   /** @private
     Pass through to the underlying array.  The passed in objects must be
     records, which can be converted to `storeId`s.
   */
-  replace: function(idx, amt, recs) {
+  replace: function (idx, amt, recs) {
     //@if(debug)
     if (!this.get('isEditable')) {
       throw new Error("Developer Error: %@.%@[] is not editable.".fmt(this.get('record'), this.get('propertyName')));
@@ -243,47 +269,73 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     //@endif
 
     var storeIds = this.get('editableStoreIds'),
-        len      = recs ? (recs.get ? recs.get('length') : recs.length) : 0,
-        record   = this.get('record'),
-        pname    = this.get('propertyName'),
-        i, ids, toRemove, inverse, attr, inverseRecord;
+      recsLen = recs ? (recs.get ? recs.get('length') : recs.length) : 0,
+      parent   = this.get('record'),
+      pname    = this.get('propertyName'),
+      supportNewRecords = this.get('supportNewRecords'),
+      ids, toRemove, inverse, attr, inverseRecord,
+      i;
+
+    // Create the cache, we will need it.
+    if (!this._records) this._records = [];
 
     // map to store keys
-    ids = [] ;
-    for(i=0;i<len;i++) {
-      //@if(debug)
-      if (SC.none(recs.objectAt(i).get('id'))) {
-        throw new Error("Developer Error: Attempted to add a record without a primary key to a to-many relationship. Relationships require that the id always be specified. The record, \"%@\", must be assigned an id (i.e. be saved) before it can be used in the '%@' relationship.".fmt(recs.objectAt(i), pname));
+    ids = [];
+    for (i = 0; i < recsLen; i++) {
+      var rec = recs.objectAt(i),
+        id = rec.get('id');
+
+      if (SC.none(id)) {
+        // If the record inserted doesn't have an id yet, use a unique placeholder based on the storeKey.
+        if (supportNewRecords) {
+          ids[i] = '_sc_id_placeholder_' + rec.get('storeKey');
+        } else {
+          throw new Error("Developer Error: Attempted to add a record without a primary key to a to-many relationship (%@). The record must have a real id or be given a temporary id before it can be used. ".fmt(pname));
+        }
+      } else {
+        ids[i] = id;
       }
-      //@endif
-
-      ids[i] = recs.objectAt(i).get('id');
     }
 
     // if we have an inverse - collect the list of records we are about to
     // remove
     inverse = this.get('inverse');
     if (inverse && amt > 0) {
+      // Use a shared array to save on processing.
       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);
+      for (i = 0; i < amt; i++) {
+        toRemove[i] = this.objectAt(idx + i);
+      }
     }
 
-    // pass along - if allowed, this should trigger the content observer
-    storeIds.replace(idx, amt, ids);
+    // Notify that the content will change.
+    this.arrayContentWillChange(idx, amt, recsLen);
+
+    // Perform a raw array replace without any KVO checks.
+    // NOTE: the cache must be updated to mirror changes to the storeIds
+    if (ids.length === 0) {
+      storeIds.splice(idx, amt);
+      this._records.splice(idx, amt);
+    } else {
+      var args = [idx, amt].concat(ids);
+      storeIds.splice.apply(storeIds, args);
+      args = [idx, amt].concat(new Array(ids.length)); // Insert empty items into the cache
+      this._records.splice.apply(this._records, args);
+    }
 
     // ok, notify records that were removed then added; this way reordered
     // objects are added and removed
     if (inverse) {
 
       // notify removals
-      for(i=0;i<amt;i++) {
+      for (i = 0; i < amt; i++) {
         inverseRecord = toRemove[i];
         attr = inverseRecord ? inverseRecord[inverse] : null;
         if (attr && attr.inverseDidRemoveRecord) {
-          attr.inverseDidRemoveRecord(inverseRecord, inverse, record, pname);
+          attr.inverseDidRemoveRecord(inverseRecord, inverse, parent, pname);
         }
       }
 
@@ -293,22 +345,29 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
       }
 
       // notify additions
-      for(i=0;i<len;i++) {
+      for (i = 0; i < recsLen; i++) {
         inverseRecord = recs.objectAt(i);
         attr = inverseRecord ? inverseRecord[inverse] : null;
         if (attr && attr.inverseDidAddRecord) {
-          attr.inverseDidAddRecord(inverseRecord, inverse, record, pname);
+          attr.inverseDidAddRecord(inverseRecord, inverse, parent, pname);
         }
       }
 
     }
 
-    // only mark record dirty if there is no inverse or we are master
-    if (record && (!inverse || this.get('isMaster'))) {
-      record.recordDidChange(pname);
-    }
+    // Notify that the content did change.
+    this.arrayContentDidChange(idx, amt, recsLen);
+
+    // Update our cache! So when the record property change comes back down we can ignore it.
+    this._sc_prevStoreIds = storeIds;
 
-    this.enumerableContentDidChange(idx, amt, len - amt);
+    // Only mark record dirty if there is no inverse or we are master.
+    if (parent && (!inverse || this.get('isMaster'))) {
+
+      // We must indicate to the parent that we have been modified, so they can
+      // update their status.
+      parent.recordDidChange(pname);
+    }
 
     return this;
   },
@@ -324,16 +383,31 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     @param {SC.Record} inverseRecord the record that was removed
     @returns {SC.ManyArray} receiver
   */
-  removeInverseRecord: function(inverseRecord) {
-
+  removeInverseRecord: function (inverseRecord) {
+    // Fast path!
     if (!inverseRecord) return this; // nothing to do
+
     var id = inverseRecord.get('id'),
-        storeIds = this.get('editableStoreIds'),
-        idx      = (storeIds && id) ? storeIds.indexOf(id) : -1,
-        record;
+      storeIds = this.get('editableStoreIds'),
+      idx = (storeIds && id) ? storeIds.indexOf(id) : -1,
+      record;
 
     if (idx >= 0) {
-      storeIds.removeAt(idx);
+
+      // Notify that the content will change.
+      this.arrayContentWillChange(idx, 1, 0);
+
+      // Perform a raw array replace without any KVO checks.
+      // NOTE: the cache must be updated to mirror changes to the storeIds
+      storeIds.splice(idx, 1);
+      if (this._records) { this._records.splice(idx, 1); }
+
+      // Notify that the content did change.
+      this.arrayContentDidChange(idx, 1, 0);
+
+      // Update our cache! So when the record property change comes back down we can ignore it.
+      this._sc_prevStoreIds = storeIds;
+
       if (this.get('isMaster') && (record = this.get('record'))) {
         record.recordDidChange(this.get('propertyName'));
       }
@@ -354,16 +428,39 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
     if (!inverseRecord) return this;
 
     var storeIds = this.get('editableStoreIds'),
-        orderBy  = this.get('orderBy'),
-        len      = storeIds.get('length'),
-        idx, record;
+      orderBy  = this.get('orderBy'),
+      len = storeIds.get('length'),
+      idx, record,
+      removeCount, addCount;
 
     // find idx to insert at.
     if (orderBy) {
       idx = this._findInsertionLocation(inverseRecord, 0, len, orderBy);
-    } else idx = len;
 
-    storeIds.insertAt(idx, inverseRecord.get('id'));
+      // All objects from idx to the end must be removed to do an ordered insert.
+      removeCount = storeIds.length - idx;
+      addCount = storeIds.length - idx + 1;
+    } else {
+      idx = len;
+
+      removeCount = 0;
+      addCount = 1;
+    }
+
+    // Notify that the content will change.
+    this.arrayContentWillChange(idx, removeCount, addCount);
+
+    // Perform a raw array replace without any KVO checks.
+    // NOTE: the cache must be updated to mirror changes to the storeIds
+    storeIds.splice(idx, 0, inverseRecord.get('id'));
+    if (this._records) { this._records.splice(idx, 0, null); }
+
+    // Notify that the content did change.
+    this.arrayContentDidChange(idx, removeCount, addCount);
+
+    // Update our cache! So when the record property change comes back down we can ignore it.
+    this._sc_prevStoreIds = storeIds;
+
     if (this.get('isMaster') && (record = this.get('record'))) {
       record.recordDidChange(this.get('propertyName'));
     }
@@ -401,82 +498,81 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
         ret, idx, len;
 
     if (t === SC.T_FUNCTION) ret = orderBy(a, b);
-    else if (t === SC.T_STRING) ret = SC.compare(a,b);
+    else if (t === SC.T_STRING) ret = SC.compare(a, b);
     else {
       len = orderBy.get('length');
       ret = 0;
-      for(idx=0;(ret===0) && (idx<len);idx++) ret = SC.compare(a,b);
+      for (idx = 0; ret === 0 && idx < len; idx++) ret = SC.compare(a, b);
     }
 
-    return ret ;
+    return ret;
   },
 
-  // ..........................................................
-  // INTERNAL SUPPORT
-  //
+  /**
+    Call this when a new record that was added to the many array previously
+    has been committed and now has a proper `id`. This will fix up the temporary
+    id that was used to allow the new record to be a part of this many array.
 
-  /** @private
-    Invoked whenever the `storeIds` array changes.  Observes changes.
+    @return {void}
   */
-  recordPropertyDidChange: function(keys) {
-
-    if (keys && !keys.contains(this.get('propertyName'))) return this;
-
-    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.removeArrayObservers({
-        target: this,
-        willChange: this.arrayContentWillChange,
-        didChange: f
-      });
-
-      oldLen = prev.get('length');
-    } else {
-      oldLen = 0;
-    }
+  updateNewRecordId: function (rec) {
+    var storeIds = this.get('editableStoreIds'),
+      idx;
 
-    if (storeIds) {
-      storeIds.addArrayObservers({
-        target: this,
-        willChange: this.arrayContentWillChange,
-        didChange: f
-      });
+    // Update the storeIds array with the new record id.
+    idx = storeIds.indexOf('_sc_id_placeholder_' + rec.get('storeKey'));
 
-      newLen = storeIds.get('length');
-    } else {
-      newLen = 0;
+    // Beware of records that are no longer a part of storeIds.
+    if (idx >= 0) {
+      storeIds.replace(idx, 1, [rec.get('id')]);
     }
-
-    this.arrayContentWillChange(0, oldLen, newLen);
-    this._prevStoreIds = storeIds;
-    this._storeIdsContentDidChange(0, oldLen, newLen);
   },
 
-  /** @private
-    Invoked whenever the content of the storeIds array changes.  This will
-    dump any cached record lookup and then notify that the enumerable content
-    has changed.
-  */
-  _storeIdsContentDidChange: function(start, removedCount, addedCount) {
-    this._records = null ; // clear cache
-    this.arrayContentDidChange(start, removedCount, addedCount);
-  },
+  // ..........................................................
+  // INTERNAL SUPPORT
+  //
 
   /** @private */
-  unknownProperty: function(key, value) {
+  unknownProperty: function (key, value) {
     var ret;
     if (SC.typeOf(key) === SC.T_STRING) ret = this.reducedProperty(key, value);
     return ret === undefined ? sc_super() : ret;
   },
 
   /** @private */
-  init: function() {
+  init: function () {
     sc_super();
+
+    // Initialize.
     this.recordPropertyDidChange();
+  },
+
+  /** @private
+    This is called by the parent record whenever its properties change. It is
+    also called by the ChildrenAttribute transform when the attribute is set
+    to a new array.
+  */
+  recordPropertyDidChange: function (keys) {
+    if (keys && !keys.contains(this.get('propertyName'))) return this;
+
+    var oldLength = this.get('length'),
+      storeIds = this.get('readOnlyStoreIds'),
+      newLength = storeIds ? storeIds.length : 0,
+      prev = this._sc_prevStoreIds;
+
+    // Fast Path! No actual change to our backing array attribute so we should
+    // not notify any changes.
+    if (storeIds === prev) { return; }
+
+    // Throw away our cache.
+    this._records = null;
+
+    // Notify that the content did change.
+    this.arrayContentDidChange(0, oldLength, newLength);
+
+    // Cache our backing array so we can avoid updates when we haven't actually
+    // changed. See fast path above.
+    this._sc_prevStoreIds = storeIds;
   }
 
 });