compago-collection - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

dist/node/index.js

@@ -17,11 +17,16 @@ 'use strict';
 
+/**
+ * Manages an ordered set of models providing methods to create, sort, and dispose of the models.
+ *
+ * @mixes Listener
+ */
 class Collection {
 
   /**
-   * @param {Array.<Model>} [models] Models to add to the collection.
+   * @param {Array.<Model>} [models] models to add to the collection
    * @param {Object} [options]
-   * @param {Object} [options.storage] The storage controller for the collection.
-   * @param {Object} [options.model]   The class of models in the collection.
-   * @param {(Function|string)} [options.comparator] A function or an attribute name
-   *                                                   that will be used to sort the collection.
+   * @param {Object} [options.storage] the storage controller for the collection
+   * @param {Object} [options.model]   the class of models in the collection
+   * @param {(Function|string)} [options.comparator] a function or an attribute name
+   *                                                   that will be used to sort the collection
    */
@@ -47,13 +52,13 @@ constructor(models) {
    *
-   * @param {(Array|Object)} models A model, a list of models or objects to be added
-   *                                to the collection or updated if already present.
+   * @param {(Array|Object)} models a model, a list of models or objects to be added
+   *                                to the collection or updated if already present
    * @param {Object} options
-   * @param {number} [options.at]          The position that model(s) will occupy in the collection.
-   * @param {boolean} [options.keep]       to avoid removing the models not present
+   * @param {number} [options.at]          the position at which the model(s) should be placed
+   * @param {boolean} [options.keep]       whether to avoid removing the models not present
    *                                          in the supplied list
-   * @param {boolean} [options.skip]       to avoid updating existing models.
-   * @param {boolean} [options.silent]     to avoid firing any events.
-   * @param {boolean} [options.unsorted]   to avoid sorting the collection.
-   * @param {boolean} [options.save]       to avoid disposing removed models
-   * @return {Collection}
+   * @param {boolean} [options.skip]       whether to avoid updating existing models
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    *
@@ -114,2 +119,7 @@ */
    * Prepares models to be added or removed from the collection.
+   *
+   * @param {Array} models
+   * @param {Object} options
+   * @param {boolean} sortable
+   * @returns {Array}
    */
@@ -148,2 +158,6 @@ _parseModels(models, options, sortable) {
    * Creates models from bare objects when necessary.
+   *
+   * @param {(Model|Object)} data
+   * @param {Object} options
+   * @returns {Model|boolean}
    */
@@ -162,2 +176,5 @@ _prepareModel(data, options) {
    * Listens to all events fired by the models in the collection.
+   *
+   * @param {Object} event
+   * @returns {void}
    */
@@ -183,2 +200,5 @@ _onModelEvent(event) {
    * Ties a model to the collection.
+   *
+   * @param {Model} model
+   * @returns {void}
    */
@@ -193,2 +213,5 @@ _addReference(model) {
    * Severs a model's ties to the collection.
+   *
+   * @param {Model} model
+   * @returns {void}
    */
@@ -204,5 +227,7 @@ _removeReference(model) {
    *
-   * @param {(Object|Array)} models A model(s) or objects to be added to the collection.
-   * @param {Object} [options] The options are sent to `Collection#set`
-   * @return {Collection}
+   * @param {(Object|Array)} models the model(s) or objects to be added to the collection.
+   * @param {number} [options.at]          the position at which the model(s) should be placed
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -220,13 +245,14 @@ add(models) {
    *
-   * @param {(Object|Array)} models A model or a list of models to remove from the collection.
+   * @param {(Model|Array.<Model>)} models the model(s) to remove from the collection
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing any event.
-   * @param {boolean} [options.save]  to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
   remove(models) {
-    let options = arguments.length <= 1 || arguments[1] === undefined ? {} : arguments[1];
-    const silent = options.silent;
-    const save = options.save;
+    var _ref = arguments.length <= 1 || arguments[1] === undefined ? {} : arguments[1];
 
+    let silent = _ref.silent;
+    let save = _ref.save;
+
     let hasChanged = false;
@@ -253,11 +279,12 @@ const modelsArray = [].concat(models);
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `clear` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing the `clear` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
   clear() {
-    let options = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
-    const silent = options.silent;
-    const save = options.save;
+    var _ref2 = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
 
+    let silent = _ref2.silent;
+    let save = _ref2.save;
+
     const models = this.models;
@@ -271,4 +298,3 @@ for (const model of models) {
     if (!silent) {
-      options.previousModels = models;
-      this.emit('clear', options);
+      this.emit('clear', { save, previousModels: models });
     }
@@ -281,15 +307,17 @@ return this;
    *
-   * @param {(Object|Array)} models A model(s) or objects to be added to the collection.
+   * @param {(Object|Array)} models the model(s) or objects to be added to the collection
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `reset` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
   reset(models) {
-    let options = arguments.length <= 1 || arguments[1] === undefined ? {} : arguments[1];
+    var _ref3 = arguments.length <= 1 || arguments[1] === undefined ? {} : arguments[1];
 
-    options.previousModels = this.models;
-    this.clear({ silent: true, save: options.save });
+    let silent = _ref3.silent;
+    let save = _ref3.save;
+
+    this.clear({ silent: true, save });
     this.add(models, { silent: true });
-    if (!options.silent) this.emit('reset', options);
+    if (!silent) this.emit('reset', { save, previousModels: this.models });
     return this;
@@ -301,5 +329,7 @@ }
    *
-   * @param {(Object|Array)} model A model(s) or objects to be added to the collection.
-   * @param {Object} [options] Options are sent to `Collection#add`
-   * @return {Collection}
+   * @param {(Object|Array)} model the model(s) or objects to be added to the collection.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -316,4 +346,6 @@ push(model) {
    *
-   * @param {Object} [options] Options are sent to `Collection#remove`
-   * @return {Model} Returns the removed model.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {Model} the removed model
    */
@@ -329,5 +361,7 @@ pop(options) {
    *
-   * @param {(Object|Array)} model A model(s) or objects to be added to the collection.
-   * @param {Object} [options] Options are sent to `Collection#add`
-   * @return {Collection}
+   * @param {(Object|Array)} model the model(s) or objects to be added to the collection.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -344,4 +378,6 @@ unshift(model) {
    *
-   * @param {Object} [options] Options are sent to `Collection#remove`
-   * @return {Model} Returns the removed model.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {Model}the removed model
    */
@@ -358,8 +394,8 @@ shift(options) {
    * @param {Object} [options]
-   * @param {(Function|string)} [options.comparator] A comparator function or an attribute name
-   *                                                 for sorting.
-   * @param {boolean} [options.silent] to avoids firing `sort` event.
-   * @param {boolean} [options.descending] Sorts in descending order if the comparator is
-   *                                        an attribute name.
-   * @return {Collection}
+   * @param {(Function|string)} [options.comparator] a comparator function or an attribute name
+   *                                                 for sorting
+   * @param {boolean} [options.silent] whether to avoid firing the `sort` event
+   * @param {boolean} [options.descending] whether to sort in descending order if the comparator is
+   *                                        an attribute name
+   * @returns {this}
    */
@@ -384,5 +420,5 @@ sort() {
         if (descending) {
-          var _ref = [b, a];
-          a = _ref[0];
-          b = _ref[1];
+          var _ref4 = [b, a];
+          a = _ref4[0];
+          b = _ref4[1];
         }
@@ -412,10 +448,12 @@
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `sort` event.
-   * @return {Collection}
+   * @param {boolean} [options.silent] whether to avoid firing the `sort` event
+   * @returns {this}
    */
   reverse() {
-    let options = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
+    var _ref5 = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
 
+    let silent = _ref5.silent;
+
     this.models.reverse();
-    if (!options.silent) this.emit('sort');
+    if (!silent) this.emit('sort');
     return this;
@@ -427,4 +465,4 @@ }
    *
-   * @param {(Model|string)} id The id.
-   * @return {Model|undefined} Returns either a model or `undefined` if no model is found.
+   * @param {string} id the model's id
+   * @returns {(Model|undefined)} a model or `undefined` if no model is found
    *
@@ -439,4 +477,4 @@ */
    *
-   * @param {Model} model The model to look for.
-   * @return {boolean}
+   * @param {Model} model the model to look for
+   * @returns {boolean} True if the model is in the collection
    *
@@ -449,6 +487,6 @@ */
   /**
-   * Gets a model at the given index.
+   * Returns a model at the given index.
    *
-   * @param {number} index The index at which to look for a model.
-   * @return {Model}
+   * @param {number} index the index at which to look for a model
+   * @returns {(Model|undefined)} the model or `undefined` if no model is found
    */
@@ -462,13 +500,12 @@ at(index) {
    *
-   * @param {Object} attributes A hash of attributes to match models against.
-   * @param {boolean} [first] to return the first matching model.
-   * @return {Array.<Model>} Returns an array of matching models.
+   * @param {Object} attributes a hash of attributes to match models against
+   * @param {boolean} [first] whether to return the first matching model
+   * @returns {Array.<Model>} an array of matching models
    */
   where() {
     let attributes = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
-    let first = arguments.length <= 1 || arguments[1] === undefined ? false : arguments[1];
+    let first = arguments[1];
 
     const keys = Object.keys(attributes);
-    const l = keys.length;
-    if (!l) return [];
+    if (!keys.length) return [];
     return this.models[first ? 'find' : 'filter'](model => {
@@ -483,11 +520,11 @@ for (const key of keys) {
   /**
-   * Fetches the collection's models from the storage.
+   * Updates the collection with its stored version.
    *
    * @param {Object} [options]
-   * @param {Function} [options.success] An optional success callback.
-   * @param {Function} [options.error]   An optional error callback.
-   * @param {boolean} [options.silent]   to avoid firing events.
-   * @param {boolean} [options.reset]   to pass the response data through the `Collection#reset`
-   *                                    method instead of `Collection#set`.
-   * @return {*}
+   * @param {Function} [options.success] the success callback
+   * @param {Function} [options.error]   the error callback
+   * @param {boolean} [options.silent]   whether to avoid firing events
+   * @param {boolean} [options.reset]   whether to pass the response data through the
+   *                                      `Collection#reset` method instead of `Collection#set`.
+   * @returns {*}
    */
@@ -511,3 +548,3 @@ read() {
     _compagoModel2.default.wrapError(this, options);
-    return this.sync('read', this, options);
+    return this.sync('read', options);
   }
@@ -518,3 +555,3 @@
    *
-   * @return {Array}
+   * @returns {Array} an array of stringified models
    */
@@ -529,9 +566,8 @@ toJSON() {
    *
-   * @param {string} method The internal method name.
-   * @param {Collection} collection The collection to be synchronized.
+   * @param {string} method the internal method name.
    * @param {Object} options
    * @returns {*}
    */
-  sync(method, collection, options) {
-    if (this.storage) return this.storage.sync(method, collection, options);
+  sync(method, options) {
+    if (this.storage) return this.storage.sync(method, this, options);
     return false;
@@ -544,12 +580,13 @@ }
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `dispose` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent] whether to avoid firing `dispose` event
+   * @param {boolean} [options.save] whether to avoid disposing removed models
+   * @returns {this}
    */
   dispose() {
-    let options = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
-    const silent = options.silent;
-    const save = options.save;
+    var _ref6 = arguments.length <= 0 || arguments[0] === undefined ? {} : arguments[0];
 
-    if (!silent) this.emit('dispose', options);
+    let silent = _ref6.silent;
+    let save = _ref6.save;
+
+    if (!silent) this.emit('dispose', { save });
     this.clear({ silent: true, save });
@@ -560,2 +597,3 @@ this.off().free();
 }
+
 exports.default = Collection;

package.json

 {
   "name": "compago-collection",
-  "version": "1.0.1",
-  "description": "",
+  "version": "1.0.2",
+  "description": "A component of the Compago framework for managing ordered sets of models.",
   "main": "dist/node/index.js",
   "keywords": [
-    "collection"
+    "collection",
+    "compago"
   ],
@@ -51,2 +52,12 @@ "repository": {
         }
+      ],
+      "valid-jsdoc": [
+        2,
+        {
+          "prefer": {
+            "return": "returns"
+          },
+          "requireReturnDescription": false,
+          "requireParamDescription": false
+        }
       ]
@@ -75,5 +86,5 @@ }
   "dependencies": {
-    "compago-model": "^1.0.1",
-    "compago-listener": "^1.0.2"
+    "compago-listener": "^1.0.4",
+    "compago-model": "^1.0.1"
   }
 }

src/index.js

 import { Listener } from 'compago-listener';
 import Model from 'compago-model';
 
-export default class Collection {
+/**
+ * Manages an ordered set of models providing methods to create, sort, and dispose of the models.
+ *
+ * @mixes Listener
+ */
+class Collection {
 
   /**
-   * @param {Array.<Model>} [models] Models to add to the collection.
+   * @param {Array.<Model>} [models] models to add to the collection
    * @param {Object} [options]
-   * @param {Object} [options.storage] The storage controller for the collection.
-   * @param {Object} [options.model]   The class of models in the collection.
-   * @param {(Function|string)} [options.comparator] A function or an attribute name
-   *                                                   that will be used to sort the collection.
+   * @param {Object} [options.storage] the storage controller for the collection
+   * @param {Object} [options.model]   the class of models in the collection
+   * @param {(Function|string)} [options.comparator] a function or an attribute name
+   *                                                   that will be used to sort the collection
    */
@@ -29,13 +34,13 @@ constructor(models, options = {}) {
    *
-   * @param {(Array|Object)} models A model, a list of models or objects to be added
-   *                                to the collection or updated if already present.
+   * @param {(Array|Object)} models a model, a list of models or objects to be added
+   *                                to the collection or updated if already present
    * @param {Object} options
-   * @param {number} [options.at]          The position that model(s) will occupy in the collection.
-   * @param {boolean} [options.keep]       to avoid removing the models not present
+   * @param {number} [options.at]          the position at which the model(s) should be placed
+   * @param {boolean} [options.keep]       whether to avoid removing the models not present
    *                                          in the supplied list
-   * @param {boolean} [options.skip]       to avoid updating existing models.
-   * @param {boolean} [options.silent]     to avoid firing any events.
-   * @param {boolean} [options.unsorted]   to avoid sorting the collection.
-   * @param {boolean} [options.save]       to avoid disposing removed models
-   * @return {Collection}
+   * @param {boolean} [options.skip]       whether to avoid updating existing models
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    *
@@ -86,2 +91,7 @@ */
    * Prepares models to be added or removed from the collection.
+   *
+   * @param {Array} models
+   * @param {Object} options
+   * @param {boolean} sortable
+   * @returns {Array}
    */
@@ -119,2 +129,6 @@ _parseModels(models, options, sortable) {
    * Creates models from bare objects when necessary.
+   *
+   * @param {(Model|Object)} data
+   * @param {Object} options
+   * @returns {Model|boolean}
    */
@@ -133,2 +147,5 @@ _prepareModel(data, options) {
    * Listens to all events fired by the models in the collection.
+   *
+   * @param {Object} event
+   * @returns {void}
    */
@@ -151,2 +168,5 @@ _onModelEvent(event) {
    * Ties a model to the collection.
+   *
+   * @param {Model} model
+   * @returns {void}
    */
@@ -161,2 +181,5 @@ _addReference(model) {
    * Severs a model's ties to the collection.
+   *
+   * @param {Model} model
+   * @returns {void}
    */
@@ -172,5 +195,7 @@ _removeReference(model) {
    *
-   * @param {(Object|Array)} models A model(s) or objects to be added to the collection.
-   * @param {Object} [options] The options are sent to `Collection#set`
-   * @return {Collection}
+   * @param {(Object|Array)} models the model(s) or objects to be added to the collection.
+   * @param {number} [options.at]          the position at which the model(s) should be placed
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -186,10 +211,9 @@ add(models, options = {}) {
    *
-   * @param {(Object|Array)} models A model or a list of models to remove from the collection.
+   * @param {(Model|Array.<Model>)} models the model(s) to remove from the collection
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing any event.
-   * @param {boolean} [options.save]  to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
-  remove(models, options = {}) {
-    const { silent, save } = options;
+  remove(models, { silent, save } = {}) {
     let hasChanged = false;
@@ -216,8 +240,7 @@ const modelsArray = [].concat(models);
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `clear` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing the `clear` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
-  clear(options = {}) {
-    const { silent, save } = options;
+  clear({ silent, save } = {}) {
     const models = this.models;
@@ -231,4 +254,3 @@ for (const model of models) {
     if (!silent) {
-      options.previousModels = models;
-      this.emit('clear', options);
+      this.emit('clear', { save, previousModels: models });
     }
@@ -241,13 +263,12 @@ return this;
    *
-   * @param {(Object|Array)} models A model(s) or objects to be added to the collection.
+   * @param {(Object|Array)} models the model(s) or objects to be added to the collection
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `reset` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {this}
    */
-  reset(models, options = {}) {
-    options.previousModels = this.models;
-    this.clear({ silent: true, save: options.save });
+  reset(models, { silent, save } = {}) {
+    this.clear({ silent: true, save });
     this.add(models, { silent: true });
-    if (!options.silent) this.emit('reset', options);
+    if (!silent) this.emit('reset', { save, previousModels: this.models });
     return this;
@@ -259,5 +280,7 @@ }
    *
-   * @param {(Object|Array)} model A model(s) or objects to be added to the collection.
-   * @param {Object} [options] Options are sent to `Collection#add`
-   * @return {Collection}
+   * @param {(Object|Array)} model the model(s) or objects to be added to the collection.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -272,4 +295,6 @@ push(model, options = {}) {
    *
-   * @param {Object} [options] Options are sent to `Collection#remove`
-   * @return {Model} Returns the removed model.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {Model} the removed model
    */
@@ -285,5 +310,7 @@ pop(options) {
    *
-   * @param {(Object|Array)} model A model(s) or objects to be added to the collection.
-   * @param {Object} [options] Options are sent to `Collection#add`
-   * @return {Collection}
+   * @param {(Object|Array)} model the model(s) or objects to be added to the collection.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing any events
+   * @param {boolean} [options.unsorted]   whether to avoid sorting the collection
+   * @returns {this}
    */
@@ -298,4 +325,6 @@ unshift(model, options = {}) {
    *
-   * @param {Object} [options] Options are sent to `Collection#remove`
-   * @return {Model} Returns the removed model.
+   * @param {Object} [options]
+   * @param {boolean} [options.silent]     whether to avoid firing the `reset` event
+   * @param {boolean} [options.save]       whether to avoid disposing removed models
+   * @returns {Model}the removed model
    */
@@ -312,8 +341,8 @@ shift(options) {
    * @param {Object} [options]
-   * @param {(Function|string)} [options.comparator] A comparator function or an attribute name
-   *                                                 for sorting.
-   * @param {boolean} [options.silent] to avoid firing the `sort` event.
-   * @param {boolean} [options.descending] to sort in descending order if the comparator is
-   *                                        an attribute name.
-   * @return {Collection}
+   * @param {(Function|string)} [options.comparator] a comparator function or an attribute name
+   *                                                 for sorting
+   * @param {boolean} [options.silent] whether to avoid firing the `sort` event
+   * @param {boolean} [options.descending] whether to sort in descending order if the comparator is
+   *                                        an attribute name
+   * @returns {this}
    */
@@ -360,8 +389,8 @@ sort(options = {}) {
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `sort` event.
-   * @return {Collection}
+   * @param {boolean} [options.silent] whether to avoid firing the `sort` event
+   * @returns {this}
    */
-  reverse(options = {}) {
+  reverse({ silent } = {}) {
     this.models.reverse();
-    if (!options.silent) this.emit('sort');
+    if (!silent) this.emit('sort');
     return this;
@@ -374,4 +403,4 @@ }
    *
-   * @param {(Model|string)} id The id.
-   * @return {Model|undefined} Returns either a model or `undefined` if no model is found.
+   * @param {string} id the model's id
+   * @returns {(Model|undefined)} a model or `undefined` if no model is found
    *
@@ -386,4 +415,4 @@ */
    *
-   * @param {Model} model The model to look for.
-   * @return {boolean}
+   * @param {Model} model the model to look for
+   * @returns {boolean} True if the model is in the collection
    *
@@ -396,6 +425,6 @@ */
   /**
-   * Gets a model at the given index.
+   * Returns a model at the given index.
    *
-   * @param {number} index The index at which to look for a model.
-   * @return {Model}
+   * @param {number} index the index at which to look for a model
+   * @returns {(Model|undefined)} the model or `undefined` if no model is found
    */
@@ -409,10 +438,9 @@ at(index) {
    *
-   * @param {Object} attributes A hash of attributes to match models against.
-   * @param {boolean} [first] to return the first matching model.
-   * @return {Array.<Model>} Returns an array of matching models.
+   * @param {Object} attributes a hash of attributes to match models against
+   * @param {boolean} [first] whether to return the first matching model
+   * @returns {Array.<Model>} an array of matching models
    */
-  where(attributes = {}, first = false) {
+  where(attributes = {}, first) {
     const keys = Object.keys(attributes);
-    const l = keys.length;
-    if (!l) return [];
+    if (!keys.length) return [];
     return this.models[first ? 'find' : 'filter']((model) => {
@@ -427,11 +455,11 @@ for (const key of keys) {
   /**
-   * Fetches the collection's models from the storage.
+   * Updates the collection with its stored version.
    *
    * @param {Object} [options]
-   * @param {Function} [options.success] An optional success callback.
-   * @param {Function} [options.error]   An optional error callback.
-   * @param {boolean} [options.silent]   to avoid firing events.
-   * @param {boolean} [options.reset]   to pass the response data through the `Collection#reset`
-   *                                    method instead of `Collection#set`.
-   * @return {*}
+   * @param {Function} [options.success] the success callback
+   * @param {Function} [options.error]   the error callback
+   * @param {boolean} [options.silent]   whether to avoid firing events
+   * @param {boolean} [options.reset]   whether to pass the response data through the
+   *                                      `Collection#reset` method instead of `Collection#set`.
+   * @returns {*}
    */
@@ -451,3 +479,3 @@ read(options = {}) {
     Model.wrapError(this, options);
-    return this.sync('read', this, options);
+    return this.sync('read', options);
   }
@@ -458,3 +486,3 @@
    *
-   * @return {Array}
+   * @returns {Array} an array of stringified models
    */
@@ -469,9 +497,8 @@ toJSON() {
    *
-   * @param {string} method The internal method name.
-   * @param {Collection} collection The collection to be synchronized.
+   * @param {string} method the internal method name.
    * @param {Object} options
    * @returns {*}
    */
-  sync(method, collection, options) {
-    if (this.storage) return this.storage.sync(method, collection, options);
+  sync(method, options) {
+    if (this.storage) return this.storage.sync(method, this, options);
     return false;
@@ -484,9 +511,8 @@ }
    * @param {Object} [options]
-   * @param {boolean} [options.silent] to avoid firing `dispose` event.
-   * @param {boolean} [options.save] to avoid disposing removed models.
-   * @return {Collection}
+   * @param {boolean} [options.silent] whether to avoid firing `dispose` event
+   * @param {boolean} [options.save] whether to avoid disposing removed models
+   * @returns {this}
    */
-  dispose(options = {}) {
-    const { silent, save } = options;
-    if (!silent) this.emit('dispose', options);
+  dispose({ silent, save } = {}) {
+    if (!silent) this.emit('dispose', { save });
     this.clear({ silent: true, save });
@@ -497,1 +523,3 @@ this.off().free();
 }
+
+export default Collection;

tests/unit.test.js

@@ -513,3 +513,3 @@ /* eslint-env node, mocha */
       const nc = new Collection(undefined, { storage });
-      nc.sync('read', nc, options);
+      nc.sync('read', options);
       expect(storage.sync).toHaveBeenCalledWith('read', nc, options);
@@ -521,3 +521,3 @@ });
     beforeEach(() => {
-      c.sync = (method, model, options) => {
+      c.sync = (method, options) => {
         options.success([m1, m2, m3]);
@@ -553,3 +553,3 @@ };
     it('fires `error` event and executes `error` callback if an error happens', () => {
-      c.sync = (method, model, options) => {
+      c.sync = (method, options) => {
         options.error('inappropriate data');
@@ -556,0 +556,0 @@ };

No alert changes

Improved metrics

Total package byte prevSize

56524

increased by4.06%

Lines of code

1482

increased by4.15%

Dependency changes

• Updatedcompago-listener@^1.0.4