Renamed DataSet option `convert` to `type`.

HISTORY.md

@@ -2,7 +2,7 @@
 http://visjs.org
 
 
-## not yet released, version 1.1.1
+## not yet released, version 2.0.0
 
 ### Timeline
 
@@ -19,6 +19,10 @@ http://visjs.org
 - Fixed dataManipulation.initiallyVisible functionality (thanks theGrue).
 - Forced typecast of fontSize to Number.
 
+### DataSet
+
+- Renamed option `convert` to `type`.
+
 
 ## 2014-06-06, version 1.1.0
 

docs/dataset.html

@@ -91,7 +91,7 @@ console.log('filtered items', items);
 // retrieve formatted items
 var items = data.get({
   fields: ['id', 'date'],
-  convert: {
+  type: {
     date: 'ISODate'
   }
 });
@@ -149,7 +149,7 @@ var data = new vis.DataSet([data] [, options])
     </td>
   </tr>
   <tr>
-    <td>convert</td>
+    <td>type</td>
     <td>Object.&lt;String,&nbsp;String&gt;</td>
     <td>none</td>
     <td>
@@ -227,7 +227,7 @@ var data = new vis.DataSet([data] [, options])
     <td>Number[]</td>
     <td>
       Get ids of all items or of a filtered set of items.
-      Available <code>options</code> are described in section <a href="#Data_Selection">Data Selection</a>, except that options <code>fields</code> and <code>convert</code> are not applicable in case of <code>getIds</code>.
+      Available <code>options</code> are described in section <a href="#Data_Selection">Data Selection</a>, except that options <code>fields</code> and <code>type</code> are not applicable in case of <code>getIds</code>.
     </td>
   </tr>
 
@@ -649,7 +649,7 @@ DataSet.map(callback [, options]);
   </tr>
 
   <tr>
-    <td>convert</td>
+    <td>type</td>
     <td>Object.&lt;String,&nbsp;String&gt;</td>
     <td>
       An object containing field names as key, and data types as value.
@@ -700,7 +700,7 @@ data.add([
 // retrieve formatted items
 var items = data.get({
   fields: ['id', 'date', 'group'],    // output the specified fields only
-  convert: {
+  type: {
     date: 'Date',                   // convert the date fields to Date objects
     group: 'String'                 // convert the group fields to Strings
   }

examples/timeline/02_interactive.html

@@ -22,7 +22,7 @@
 <script>
   // create a dataset with items
   var items = new vis.DataSet({
-    convert: {
+    type: {
       start: 'Date',
       end: 'Date'
     }

examples/timeline/03_a_lot_of_data.html

@@ -31,7 +31,7 @@
   // create a dataset with items
   var now = moment().minutes(0).seconds(0).milliseconds(0);
   var items = new vis.DataSet({
-    convert: {
+    type: {
       start: 'Date',
       end: 'Date'
     }

examples/timeline/06_event_listeners.html

@@ -19,10 +19,7 @@
 
   <script type="text/javascript">
     var items = new vis.DataSet({
-      convert: {
-        start: 'Date',
-        end: 'Date'
-      }
+      type: { start: 'Date', end: 'Date' }
     });
     items.add([
       {id: 1, content: 'item 1', start: '2013-04-20'},

src/DataSet.js

@@ -4,7 +4,7 @@
  * Usage:
  *     var dataSet = new DataSet({
  *         fieldId: '_id',
- *         convert: {
+ *         type: {
  *             // ...
  *         }
  *     });
@@ -30,7 +30,7 @@
  * @param {Object} [options]   Available options:
  *                             {String} fieldId Field name of the id in the
  *                                              items, 'id' by default.
- *                             {Object.<String, String} convert
+ *                             {Object.<String, String} type
  *                                              A map with field names as key,
  *                                              and the field type as value.
  * @constructor DataSet
@@ -48,23 +48,28 @@ function DataSet (data, options) {
   this.options = options || {};
   this.data = {};                                 // map with data indexed by id
   this.fieldId = this.options.fieldId || 'id';    // name of the field containing id
-  this.convert = {};                              // field types by field name
+  this.type = {};                                 // field types by field name
   this.showInternalIds = this.options.showInternalIds || false; // show internal ids with the get function
 
-  if (this.options.convert) {
-    for (var field in this.options.convert) {
-      if (this.options.convert.hasOwnProperty(field)) {
-        var value = this.options.convert[field];
+  if (this.options.type) {
+    for (var field in this.options.type) {
+      if (this.options.type.hasOwnProperty(field)) {
+        var value = this.options.type[field];
         if (value == 'Date' || value == 'ISODate' || value == 'ASPDate') {
-          this.convert[field] = 'Date';
+          this.type[field] = 'Date';
         }
         else {
-          this.convert[field] = value;
+          this.type[field] = value;
         }
       }
     }
   }
 
+  // TODO: deprecated since version 1.1.1 (or 2.0.0?)
+  if (this.options.convert) {
+    throw new Error('Option "convert" is deprecated. Use "type" instead.');
+  }
+
   this.subscribers = {};  // event subscribers
   this.internalIds = {};  // internally generated id's
 
@@ -277,9 +282,9 @@ DataSet.prototype.update = function (data, senderId) {
  * {Number | String} id         The id of an item
  * {Number[] | String{}} ids    An array with ids of items
  * {Object} options             An Object with options. Available options:
- *                              {String} [type] Type of data to be returned. Can
- *                                              be 'DataTable' or 'Array' (default)
- *                              {Object.<String, String>} [convert]
+ *                              {String} [returnType] Type of data to be
+ *                                  returned. Can be 'DataTable' or 'Array' (default)
+ *                              {Object.<String, String>} [type]
  *                              {String[]} [fields] field names to be returned
  *                              {function} [filter] filter items
  *                              {String | function} [order] Order the items by
@@ -316,24 +321,24 @@ DataSet.prototype.get = function (args) {
   }
 
   // determine the return type
-  var type;
-  if (options && options.type) {
-    type = (options.type == 'DataTable') ? 'DataTable' : 'Array';
+  var returnType;
+  if (options && options.returnType) {
+    returnType = (options.returnType == 'DataTable') ? 'DataTable' : 'Array';
 
-    if (data && (type != util.getType(data))) {
+    if (data && (returnType != util.getType(data))) {
       throw new Error('Type of parameter "data" (' + util.getType(data) + ') ' +
           'does not correspond with specified options.type (' + options.type + ')');
     }
-    if (type == 'DataTable' && !util.isDataTable(data)) {
+    if (returnType == 'DataTable' && !util.isDataTable(data)) {
       throw new Error('Parameter "data" must be a DataTable ' +
           'when options.type is "DataTable"');
     }
   }
   else if (data) {
-    type = (util.getType(data) == 'DataTable') ? 'DataTable' : 'Array';
+    returnType = (util.getType(data) == 'DataTable') ? 'DataTable' : 'Array';
   }
   else {
-    type = 'Array';
+    returnType = 'Array';
   }
 
   // we allow the setting of this value for a single get request.
@@ -344,14 +349,14 @@ DataSet.prototype.get = function (args) {
   }
 
   // build options
-  var convert = options && options.convert || this.options.convert;
+  var type = options && options.type || this.options.type;
   var filter = options && options.filter;
   var items = [], item, itemId, i, len;
 
   // convert items
   if (id != undefined) {
     // return a single item
-    item = me._getItem(id, convert);
+    item = me._getItem(id, type);
     if (filter && !filter(item)) {
       item = null;
     }
@@ -359,7 +364,7 @@ DataSet.prototype.get = function (args) {
   else if (ids != undefined) {
     // return a subset of items
     for (i = 0, len = ids.length; i < len; i++) {
-      item = me._getItem(ids[i], convert);
+      item = me._getItem(ids[i], type);
       if (!filter || filter(item)) {
         items.push(item);
       }
@@ -369,7 +374,7 @@ DataSet.prototype.get = function (args) {
     // return all items
     for (itemId in this.data) {
       if (this.data.hasOwnProperty(itemId)) {
-        item = me._getItem(itemId, convert);
+        item = me._getItem(itemId, type);
         if (!filter || filter(item)) {
           items.push(item);
         }
@@ -399,7 +404,7 @@ DataSet.prototype.get = function (args) {
   }
 
   // return the results
-  if (type == 'DataTable') {
+  if (returnType == 'DataTable') {
     var columns = this._getColumnNames(data);
     if (id != undefined) {
       // append a single item to the data table
@@ -448,7 +453,7 @@ DataSet.prototype.getIds = function (options) {
   var data = this.data,
       filter = options && options.filter,
       order = options && options.order,
-      convert = options && options.convert || this.options.convert,
+      type = options && options.type || this.options.type,
       i,
       len,
       id,
@@ -463,7 +468,7 @@ DataSet.prototype.getIds = function (options) {
       items = [];
       for (id in data) {
         if (data.hasOwnProperty(id)) {
-          item = this._getItem(id, convert);
+          item = this._getItem(id, type);
           if (filter(item)) {
             items.push(item);
           }
@@ -480,7 +485,7 @@ DataSet.prototype.getIds = function (options) {
       // create unordered list
       for (id in data) {
         if (data.hasOwnProperty(id)) {
-          item = this._getItem(id, convert);
+          item = this._getItem(id, type);
           if (filter(item)) {
             ids.push(item[this.fieldId]);
           }
@@ -523,7 +528,7 @@ DataSet.prototype.getIds = function (options) {
  * Execute a callback function for every item in the dataset.
  * @param {function} callback
  * @param {Object} [options]    Available options:
- *                              {Object.<String, String>} [convert]
+ *                              {Object.<String, String>} [type]
  *                              {String[]} [fields] filter fields
  *                              {function} [filter] filter items
  *                              {String | function} [order] Order the items by
@@ -531,7 +536,7 @@ DataSet.prototype.getIds = function (options) {
  */
 DataSet.prototype.forEach = function (callback, options) {
   var filter = options && options.filter,
-      convert = options && options.convert || this.options.convert,
+      type = options && options.type || this.options.type,
       data = this.data,
       item,
       id;
@@ -550,7 +555,7 @@ DataSet.prototype.forEach = function (callback, options) {
     // unordered
     for (id in data) {
       if (data.hasOwnProperty(id)) {
-        item = this._getItem(id, convert);
+        item = this._getItem(id, type);
         if (!filter || filter(item)) {
           callback(item, id);
         }
@@ -563,7 +568,7 @@ DataSet.prototype.forEach = function (callback, options) {
  * Map every item in the dataset.
  * @param {function} callback
  * @param {Object} [options]    Available options:
- *                              {Object.<String, String>} [convert]
+ *                              {Object.<String, String>} [type]
  *                              {String[]} [fields] filter fields
  *                              {function} [filter] filter items
  *                              {String | function} [order] Order the items by
@@ -572,7 +577,7 @@ DataSet.prototype.forEach = function (callback, options) {
  */
 DataSet.prototype.map = function (callback, options) {
   var filter = options && options.filter,
-      convert = options && options.convert || this.options.convert,
+      type = options && options.type || this.options.type,
       mappedItems = [],
       data = this.data,
       item;
@@ -580,7 +585,7 @@ DataSet.prototype.map = function (callback, options) {
   // convert and filter items
   for (var id in data) {
     if (data.hasOwnProperty(id)) {
-      item = this._getItem(id, convert);
+      item = this._getItem(id, type);
       if (!filter || filter(item)) {
         mappedItems.push(callback(item, id));
       }
@@ -773,7 +778,7 @@ DataSet.prototype.min = function (field) {
 DataSet.prototype.distinct = function (field) {
   var data = this.data,
       values = [],
-      fieldType = this.options.convert[field],
+      fieldType = this.options.type[field],
       count = 0;
 
   for (var prop in data) {
@@ -823,7 +828,7 @@ DataSet.prototype._addItem = function (item) {
   var d = {};
   for (var field in item) {
     if (item.hasOwnProperty(field)) {
-      var fieldType = this.convert[field];  // type may be undefined
+      var fieldType = this.type[field];  // type may be undefined
       d[field] = util.convert(item[field], fieldType);
     }
   }
@@ -835,11 +840,11 @@ DataSet.prototype._addItem = function (item) {
 /**
  * Get an item. Fields can be converted to a specific type
  * @param {String} id
- * @param {Object.<String, String>} [convert]  field types to convert
+ * @param {Object.<String, String>} [type]  field types to convert
  * @return {Object | null} item
  * @private
  */
-DataSet.prototype._getItem = function (id, convert) {
+DataSet.prototype._getItem = function (id, type) {
   var field, value;
 
   // get the item from the dataset
@@ -852,13 +857,13 @@ DataSet.prototype._getItem = function (id, convert) {
   var converted = {},
       fieldId = this.fieldId,
       internalIds = this.internalIds;
-  if (convert) {
+  if (type) {
     for (field in raw) {
       if (raw.hasOwnProperty(field)) {
         value = raw[field];
         // output all fields, except internal ids
         if ((field != fieldId) || (!(value in internalIds) || this.showInternalIds)) {
-          converted[field] = util.convert(value, convert[field]);
+          converted[field] = util.convert(value, type[field]);
         }
       }
     }
@@ -900,7 +905,7 @@ DataSet.prototype._updateItem = function (item) {
   // merge with current item
   for (var field in item) {
     if (item.hasOwnProperty(field)) {
-      var fieldType = this.convert[field];  // type may be undefined
+      var fieldType = this.type[field];  // type may be undefined
       d[field] = util.convert(item[field], fieldType);
     }
   }

src/timeline/Timeline.js

@@ -296,7 +296,7 @@ Timeline.prototype.setItems = function(items) {
   else {
     // turn an array into a dataset
     newDataSet = new DataSet(items, {
-      convert: {
+      type: {
         start: 'Date',
         end: 'Date'
       }

test/dataset.js

@@ -6,7 +6,7 @@ var assert = require('assert'),
 var now = new Date();
 
 var data = new DataSet({
-  convert: {
+  type: {
     start: 'Date',
     end: 'Date'
   }
@@ -44,7 +44,7 @@ assert.deepEqual(data.get({
 // convert dates
 assert.deepEqual(data.get({
   fields: ['id', 'start'],
-  convert: {start: 'Number'}
+  type: {start: 'Number'}
 }).sort(sort), [
   {id: 1, start: now.valueOf()},
   {id: 2, start: now.valueOf()},
@@ -56,7 +56,7 @@ assert.deepEqual(data.get({
 // get a single item
 assert.deepEqual(data.get(1, {
   fields: ['id', 'start'],
-  convert: {start: 'ISODate'}
+  type: {start: 'ISODate'}
 }), {
   id: 1,
   start: now.toISOString()