sproutcore 1.9.2 → 1.10.0.rc.1

data/lib/frameworks/sproutcore/frameworks/datastore/models/child_attribute.js

@@ -38,7 +38,7 @@ SC.ChildAttribute = SC.RecordAttribute.extend(
         recordType  = this.get('typeClass');
 
     if (!record) {
-      throw 'SC.Child: Error during transform: Unable to retrieve parent record.';
+      throw new Error('SC.Child: Error during transform: Unable to retrieve parent record.');
     }
     if (!SC.none(value)) ret = record.registerNestedRecord(value, key);
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/fetched_attribute.js

@@ -14,14 +14,14 @@ sc_require('models/record_attribute');
   when you request it.  Normally getting a property value with this attribute
   applied will cause call the `find()` method on the record store passing
   the attribute record type as the query key along with the property value,
-  owner record, and property key name as parameters. 
-  
-  The DataSource you hook up to your store must know how to load this kind 
+  owner record, and property key name as parameters.
+
+  The DataSource you hook up to your store must know how to load this kind
   of relationship for this fetched property to work properly.
-  
+
   The return value is usually an `SC.RecordArray` that will populate with the
   record data so that you can display it.
-  
+
   @extends SC.RecordAttribute
   @since SproutCore 1.0
 */
@@ -29,53 +29,53 @@ SC.FetchedAttribute = SC.RecordAttribute.extend(
   /** @scope SC.FetchedAttribute.prototype */ {
 
   /**
-    Define the param key that will be passed to the `findAll` method on the
+    Define the param key that will be passed to the `find` method on the
     store.  If `null`, the param will not be sent.  Defaults to `'link'`
-    
-    @property {String}
+
+    @type String
   */
   paramValueKey: 'link',
 
   /**
     Define the param key used to send the parent record.  If `null`, the param
     will not be sent.  Defaults to '`owner'`.
-    
-    @property {String}
+
+    @type String
   */
   paramOwnerKey: 'owner',
-  
+
   /**
-    Define the param key used to send the key name used to reference this 
+    Define the param key used to send the key name used to reference this
     attribute.  If `null`, the param will not be sent.  Defaults to `"rel"`
-    
-    @property {String}
+
+    @type String
   */
   paramRelKey: 'rel',
-  
+
   /**
-    Optional query key to pass to findAll.  Otherwise type class will be 
+    Optional query key to pass to find.  Otherwise type class will be
     passed.
-    
-    @property {String}
+
+    @type String
   */
   queryKey: null,
 
-  /** 
-    Fetched attributes are not editable 
-    
-    @property {Boolean}
+  /**
+    Fetched attributes are not editable
+
+    @type Boolean
   */
-  isEditable: NO,  
-  
+  isEditable: NO,
+
   // ..........................................................
   // LOW-LEVEL METHODS
-  // 
-  
-  /**  @private - adapted for fetching. do findAll */
+  //
+
+  /**  @private - adapted for fetching. do find */
   toType: function(record, key, value) {
     var store = record.get('store');
     if (!store) return null ; // nothing to do
-    
+
     var paramValueKey = this.get('paramValueKey'),
         paramOwnerKey = this.get('paramOwnerKey'),
         paramRelKey   = this.get('paramRelKey'),
@@ -86,15 +86,15 @@ SC.FetchedAttribute = SC.RecordAttribute.extend(
     if (paramValueKey) params[paramValueKey] = value ;
     if (paramOwnerKey) params[paramOwnerKey] = record ;
     if (paramRelKey)   params[paramRelKey]   = this.get('key') || key ;
-    
+
     // make request - should return SC.RecordArray instance
-    return store.findAll(queryKey, params);
+    return store.find(queryKey, params);
   },
 
   /** @private - fetched attributes are read only. */
   fromType: function(record, key, value) {
     return value;
   }
-  
+
 }) ;
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/many_attribute.js

@@ -39,7 +39,7 @@ SC.ManyAttribute = SC.RecordAttribute.extend(
     `toMany()` relationship as well. Modifying this many array will modify
     the `inverse` property as well.
 
-    @property {String}
+    @type String
   */
   inverse: null,
 
@@ -50,7 +50,7 @@ SC.ManyAttribute = SC.RecordAttribute.extend(
     property also set. Only one of the inverse relationships should be marked
     as master so you can control which record should be committed.
 
-    @property {Boolean}
+    @type Boolean
   */
   isMaster: YES,
 
@@ -99,7 +99,7 @@ SC.ManyAttribute = SC.RecordAttribute.extend(
   fromType: function(record, key, value) {
     var ret = [];
 
-    if(!SC.isArray(value)) throw "Expects toMany attribute to be an array";
+    if(!SC.isArray(value)) throw new Error("Expects toMany attribute to be an array");
 
     var len = value.get('length');
     for(var i=0;i<len;i++) {

data/lib/frameworks/sproutcore/frameworks/datastore/models/record.js

@@ -449,8 +449,8 @@ SC.Record = SC.Object.extend(
 
       // If the key is the primaryKey of the record, we need to tell the store
       // about the change.
-      if (key===this.get('primaryKey')) {
-        SC.Store.replaceIdFor(storeKey, value) ;
+      if (key === this.get('primaryKey')) {
+        SC.Store.replaceIdFor(storeKey, value);
         this.propertyDidChange('id'); // Reset computed value
       }
 
@@ -941,7 +941,7 @@ SC.Record = SC.Object.extend(
 
     // When all else fails throw and exception.
     if (!recordType || !SC.kindOf(recordType, SC.Record)) {
-      throw 'SC.Child: Error during transform: Invalid record type.';
+      throw new Error('SC.Child: Error during transform: Invalid record type.');
     }
 
     return recordType;
@@ -960,7 +960,7 @@ SC.Record = SC.Object.extend(
 
     hash = hash || {}; // init if needed
 
-    if (SC.none(store)) throw 'Error: during the creation of a child record: NO STORE ON PARENT!';
+    if (SC.none(store)) throw new Error('Error: during the creation of a child record: NO STORE ON PARENT!');
 
     // Check for a primary key in the child record hash and if not found, then
     // check for a custom id generation function and if we still have no id,
@@ -1425,8 +1425,8 @@ SC.Record.mixin( /** @scope SC.Record */ {
 
   _throwUnlessRecordTypeDefined: function(recordType, relationshipType) {
     if (!recordType) {
-      throw "Attempted to create " + relationshipType + " attribute with " +
-            "undefined recordType. Did you forget to sc_require a dependency?";
+      throw new Error("Attempted to create " + relationshipType + " attribute with " +
+            "undefined recordType. Did you forget to sc_require a dependency?");
     }
   },
 

data/lib/frameworks/sproutcore/frameworks/datastore/models/record_attribute.js

@@ -150,7 +150,7 @@ SC.RecordAttribute = SC.Object.extend(
     Note that you will have to take care of destroying the created record
     once all relationships are removed from it.
 
-    @property {Boolean}
+    @type Boolean
     @default NO
    */
   lazilyInstantiate: NO,

data/lib/frameworks/sproutcore/frameworks/datastore/models/single_attribute.js

@@ -60,7 +60,7 @@ SC.SingleAttribute = SC.RecordAttribute.extend(
 
       // can only take other records or null
       if (newRec && !SC.kindOf(newRec, SC.Record)) {
-        throw "%@ is not an instance of SC.Record".fmt(newRec);
+        throw new Error("%@ is not an instance of SC.Record".fmt(newRec));
       }
 
       inverseKey = this.get('inverse');

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

@@ -224,7 +224,7 @@ SC.ManyArray = SC.Object.extend(SC.Enumerable, SC.Array,
   replace: function(idx, amt, recs) {
 
     if (!this.get('isEditable')) {
-      throw "%@.%@[] is not editable".fmt(this.get('record'), this.get('propertyName'));
+      throw new Error("%@.%@[] is not editable".fmt(this.get('record'), this.get('propertyName')));
     }
 
     var storeIds = this.get('editableStoreIds'),

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

@@ -118,7 +118,7 @@ SC.NestedStore = SC.Store.extend(
   */
   find: function(query) {
     if (query && query.isQuery && query.get('location') !== SC.Query.LOCAL) {
-      throw "SC.Store#find() can only accept LOCAL queries in nested stores";
+      throw new Error("SC.Store#find() can only accept LOCAL queries in nested stores");
     }
     return sc_super();
   },
@@ -470,12 +470,6 @@ SC.NestedStore = SC.Store.extend(
     return this.get('parentStore').queryFor(recordType, conditions, params);
   },
 
-  /** @private - adapt for nested store */
-  findAll: function(recordType, conditions, params, recordArray, _store) {
-    if (!_store) _store = this;
-    return this.get('parentStore').findAll(recordType, conditions, params, recordArray, _store);
-  },
-
   // ..........................................................
   // CORE RECORDS API
   //
@@ -568,7 +562,7 @@ SC.NestedStore = SC.Store.extend(
   // ..........................................................
   // DATA SOURCE CALLBACKS
   //
-  // Mathods called by the data source on the store
+  // Methods called by the data source on the store
 
   /** @private - adapt for nested store */
   dataSourceDidCancel: function(storeKey) {

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

@@ -11,39 +11,35 @@ sc_require('models/record');
 /**
   @class
 
-  This permits you to perform queries on your data store,
-  written in a SQL-like language. Here is a simple example:
+  This class permits you to perform queries on your data store or a remote
+  data store. Here is a simple example of a local query:
 
-      q = SC.Query.create({
+      query = SC.Query.create({
         conditions: "firstName = 'Jonny' AND lastName = 'Cash'"
-      })
-
-  You can check if a certain record matches the query by calling
-
-      q.contains(record)
+      });
 
-  To find all records of your store, that match query q, use findAll with
-  query q as argument:
+  To find all records of your store, that match the query, use find with
+  the query as an argument:
 
-      r = MyApp.store.findAll(q)
+      records = MyApp.store.find(query);
 
-  `r` will be a record array containing all matching records.
+  `records` will be a record array containing all matching records.
   To limit the query to a record type of `MyApp.MyModel`,
   you can specify the type as a property of the query like this:
 
-      q = SC.Query.create({
+      query = SC.Query.create({
         conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
         recordType: MyApp.MyModel
-      })
+      });
 
-  Calling `find()` like above will now return only records of type t.
+  Calling `find()` like above will now return only records of type MyApp.MyModel.
   It is recommended to limit your query to a record type, since the query will
-  have to look for matching records in the whole store, if no record type
+  have to look for matching records in the whole store if no record type
   is given.
 
   You can give an order, which the resulting records should follow, like this:
 
-      q = SC.Query.create({
+      query = SC.Query.create({
         conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
         recordType: MyApp.MyModel,
         orderBy: "lastName, year DESC"
@@ -54,6 +50,10 @@ sc_require('models/record');
   If no order is given, or records are equal in respect to a given order,
   records will be ordered by their storeKey.
 
+  You can check if a certain record matches the query by calling
+
+      query.contains(record);
+
   SproutCore Query Language
   =====
 
@@ -130,12 +130,6 @@ sc_require('models/record');
 
       SC.Query.registerComparison(property_name, comparison_for_this_property);
 
-  Examples
-
-  Some example queries:
-
-  TODO add examples
-
   @extends SC.Object
   @extends SC.Copyable
   @extends SC.Freezable
@@ -166,7 +160,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
 
   /**
     Optional orderBy parameters.  This can be a string of keys, optionally
-    beginning with the strings `"DESC "` or `"ASC "` to select descending or
+    ending with the strings `" DESC"` or `" ASC"` to select descending or
     ascending order.
 
     Alternatively, you can specify a comparison function, in which case the
@@ -420,7 +414,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
 
     // return result or compare by storeKey
     if (result !== 0) return result ;
-    else return SC.compare(record1.get('storeKey'),record2.get('storeKey'));
+    else return SC.compare(record1.get('storeKey'), record2.get('storeKey'));
   },
 
   /** @private
@@ -1350,11 +1344,11 @@ SC.Query.mixin( /** @scope SC.Query */ {
 
     @param {String} location the query location.
     @param {SC.Record|Array} recordType the record type or types.
-    @param {String} conditions optional conditions
-    @param {Hash} params optional params. or pass multiple args.
+    @param {String} [conditions] The conditions string.
+    @param {Object} [parameters] The parameters object.
     @returns {SC.Query}
   */
-  build: function(location, recordType, conditions, params) {
+  build: function(location, recordType, conditions, parameters) {
 
     var opts = null,
         ret, cache, key, tmp;
@@ -1368,29 +1362,29 @@ SC.Query.mixin( /** @scope SC.Query */ {
     // normalize recordType
     if (typeof recordType === SC.T_STRING) {
       ret = SC.objectForPropertyPath(recordType);
-      if (!ret) throw "%@ did not resolve to a class".fmt(recordType);
+      if (!ret) throw new Error("%@ did not resolve to a class".fmt(recordType));
       recordType = ret ;
     } else if (recordType && recordType.isEnumerable) {
       ret = [];
       recordType.forEach(function(t) {
         if (typeof t === SC.T_STRING) t = SC.objectForPropertyPath(t);
-        if (!t) throw "cannot resolve record types: %@".fmt(recordType);
+        if (!t) throw new Error("cannot resolve record types: %@".fmt(recordType));
         ret.push(t);
       }, this);
       recordType = ret ;
     } else if (!recordType) recordType = SC.Record; // find all records
 
-    if (params === undefined) params = null;
+    if (parameters === undefined) parameters = null;
     if (conditions === undefined) conditions = null;
 
-    // normalize other params. if conditions is just a hash, treat as opts
-    if (!params && (typeof conditions !== SC.T_STRING)) {
+    // normalize other parameters. if conditions is just a hash, treat as opts
+    if (!parameters && (typeof conditions !== SC.T_STRING)) {
       opts = conditions;
       conditions = null ;
     }
 
     // special case - easy to cache.
-    if (!params && !opts) {
+    if (!parameters && !opts) {
 
       tmp = SC.Query._scq_recordTypeCache;
       if (!tmp) tmp = SC.Query._scq_recordTypeCache = {};
@@ -1425,9 +1419,9 @@ SC.Query.mixin( /** @scope SC.Query */ {
         opts.recordTypes = recordType;
       } else opts.recordType = recordType;
 
-      // set conditions and params if needed
+      // set conditions and parameters if needed
       if (conditions) opts.conditions = conditions;
-      if (params) opts.parameters = params;
+      if (parameters) opts.parameters = parameters;
 
       ret = SC.Query.create(opts).freeze();
     }
@@ -1436,29 +1430,61 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
 
   /**
-    Returns a `LOCAL` query with the passed options.  For a full description of
-    the parameters you can pass to this method, see `SC.Query.build()`.
+    Returns a `LOCAL` query with the passed properties.
+
+    For example,
+
+        // Show all the accounts with a value greater than 100.
+        query = SC.Query.local(MyApp.Account, {
+          conditions: 'value > {amt}',
+          parameters: { amt: 100 },
+          orderBy: 'value DESC'
+        });
 
     @param {SC.Record|Array} recordType the record type or types.
-    @param {String} conditions optional conditions
-    @param {Hash} params optional params. or pass multiple args.
+    @param {Object} [properties] Additional properties to be added to the query.
     @returns {SC.Query}
   */
-  local: function(recordType, conditions, params) {
-    return this.build(SC.Query.LOCAL, recordType, conditions, params);
+  local: function(recordType, properties, oldParameters) {
+    //@if(debug)
+    // We are going to remove all argument overloading in the framework.  It adds
+    // code bloat, increased complexity, edge case errors and makes
+    // memorizing the API difficult.  Rather than support a long list of
+    // arguments that we can't safely collapse, it makes more sense to just
+    // accept a properties object as the proper argument.
+    if (SC.none(properties) && !SC.none(oldParameters) || SC.typeOf(properties) === SC.T_STRING) {
+      SC.warn("Developer Warning: Passing a conditions string and parameters object to SC.Query.local has been deprecated.  Please use a properties hash as per the documentation.");
+    }
+    //@endif
+    return this.build(SC.Query.LOCAL, recordType, properties, oldParameters);
   },
 
   /**
-    Returns a `REMOTE` query with the passed options.  For a full description of
-    the parameters you can pass to this method, see `SC.Query.build()`.
+    Returns a `REMOTE` query with the passed properties.
+
+    For example,
+
+        // The data source can alter its remote request using the value of
+        // `query.beginsWith`.
+        query = SC.Query.remote(MyApp.Person, { beginsWith: 'T' });
 
     @param {SC.Record|Array} recordType the record type or types.
-    @param {String} conditions optional conditions
-    @param {Hash} params optional params. or pass multiple args.
+    @param {Object} [properties] Additional properties to be added to the query.
     @returns {SC.Query}
   */
-  remote: function(recordType, conditions, params) {
-    return this.build(SC.Query.REMOTE, recordType, conditions, params);
+  remote: function(recordType, properties, oldParameters) {
+    // This used to have arguments: conditions and params.  Because both
+    // conditions and params are optional, the developer may be passing in null
+    // conditions with a params object in order to use query.parameters or they
+    // may be passing a conditions object which ended up becoming direct
+    // properties of the query.
+    // Long story short, argument overloading continues to suck ass!
+    // @if(debug)
+    if (SC.none(properties) && !SC.none(oldParameters) || SC.typeOf(properties) === SC.T_STRING) {
+      SC.warn("Developer Warning: SC.Query.remote should not include conditions and parameters arguments.  These properties are unique to local queries.  To add properties to a remote query for the data source to use, please pass a properties hash as the second argument to `remote`.");
+    }
+    // @endif
+    return this.build(SC.Query.REMOTE, recordType, properties, oldParameters);
   },
 
   /** @private