Added return types to promises

Jan Aagaard Meier
Commit 7961c7ca authored May 16, 2014 by Jan Aagaard Meier
Showing with 23 additions and 24 deletions
lib/instance.js
lib/model.js
--- a/lib/instance.js
+++ b/lib/instance.js
@@ -400,7 +400,7 @@ module.exports = (function() {
   * @param {Boolean} [options.silent=false] If true, the updatedAt timestamp will not be updated. 
   * @param {Transaction} [options.transaction]
   *
-   * @return {Promise}
+   * @return {Promise<this>}
   */
  Instance.prototype.save = function(fieldsOrOptions, options) {
    if (fieldsOrOptions instanceof Array) {
@@ -571,7 +571,7 @@ module.exports = (function() {
  *
  * @see {Model#find}
  * @param {Object} [options] Options that are passed on to `Model.find`
-  * @return {Promise}
+  * @return {Promise<this>}
  */
  Instance.prototype.reload = function(options) {
    var self = this
@@ -598,7 +598,7 @@ module.exports = (function() {
   * @param {Array} [options.skip] An array of strings. All properties that are in this array will not be validated
   * @see {InstanceValidator}
   * 
-   * @return {Promise}
+   * @return {Promise<undefined|Error}
   */
  Instance.prototype.validate = function(options) {
    return new InstanceValidator(this, options).validate()
@@ -618,7 +618,7 @@ module.exports = (function() {
   * @param {Object} updates See `setAttributes`
   * @param {Object} options See `save`
   *
-   * @return {Promise}
+   * @return {Promise<this>}
   */
  Instance.prototype.updateAttributes = function(updates, options) {
    if (options instanceof Array) {
@@ -639,7 +639,7 @@ module.exports = (function() {
   * @param {Object}  [options={}]
   * @param {Boolean} [options.force=false] If set to true, paranoid models will actually be deleted
   *
-   * @return {Promise}
+   * @return {Promise<undefined>}
   */
  Instance.prototype.destroy = function(options) {
    options = options || {}

--- a/lib/model.js
+++ b/lib/model.js
@@ -382,7 +382,7 @@ module.exports = (function() {
  /**
   * Sync this Model to the DB, that is create the table. Upon success, the callback will be called with the model instance (this)
   * @see {Sequelize#sync} for options
-   * @return {Promise} 
+   * @return {Promise<this>} 
   */
  Model.prototype.sync = function(options) {
    options = Utils._.extend({}, this.options, options || {})
@@ -487,7 +487,7 @@ module.exports = (function() {
   * ```
   *
   * @param {Array|Object|String|null}    options* The scope(s) to apply. Scopes can either be passed as consecutive arguments, or as an array of arguments. To apply simple scopes, pass them as strings. For scope function, pass an object, with a `method` property. The value can either be a string, if the method does not take any arguments, or an array, where the first element is the name of the method, and consecutive elements are arguments to that method. Pass null to remove all scopes, including the default.  
-   * @return {Model}                 A reference to the model, with the scope(s) applied. Calling scope again on the returned model will clear the previous scope.
+   * @return {Model}                      A reference to the model, with the scope(s) applied. Calling scope again on the returned model will clear the previous scope.
   */
  Model.prototype.scope = function(option) {
    var self = Object.create(this)
@@ -645,7 +645,7 @@ module.exports = (function() {
   * @param  {Transaction}               [queryOptions.transaction]
   *
   * @see    {Sequelize#query}
-   * @return {Promise}
+   * @return {Promise<Array<Instance>>}
   * @alias all
   */
  Model.prototype.findAll = function(options, queryOptions) {
@@ -706,7 +706,7 @@ module.exports = (function() {
  * @param  {Object}                    [queryOptions]
  * 
  * @see {Model#findAll}           for an explanation of options and queryOptions
-  * @return {Promise}
+  * @return {Promise<Instance>}
  */
  Model.prototype.find = function(options, queryOptions) {
    var hasJoin = false
@@ -800,9 +800,9 @@ module.exports = (function() {
   * @param {String}          field The field to aggregate over. Can be a field name or *
   * @param {String}          aggregateFunction The function to use for aggregation, e.g. sum, max etc.
   * @param {Object}          [options] Query options. See sequelize.query for full options
-   * @param {DataType|String} [options.dataType] The type of the result. If field is a field in the Instance, the default will be the type of that field, otherwise defaults to float.
+   * @param {DataType|String} [options.dataType] The type of the result. If `field` is a field in this Model, the default will be the type of that field, otherwise defaults to float.
   *
-   * @return {Promise}
+   * @return {Promise<options.dataType>}
   */
  Model.prototype.aggregate = function(field, aggregateFunction, options) {
    options = Utils._.extend({ attributes: [] }, options || {})
@@ -831,7 +831,7 @@ module.exports = (function() {
   * @param {Object}  [options]
   * @param {Object}  [options.include] Include options. See `find` for details
   *
-   * @return {Promise}
+   * @return {Promise<Integer>}
   */
  Model.prototype.count = function(options) {
    options = Utils._.clone(options || {})
@@ -866,7 +866,7 @@ module.exports = (function() {
   * @param {Object} [queryOptions] See Sequelize.query
   *
   * @see {Model#findAll} for a specification of find and query options 
-   * @return {Promise}
+   * @return {Promise<Object>}
   */
  Model.prototype.findAndCountAll = function(findOptions, queryOptions) {
    var self  = this
@@ -896,7 +896,7 @@ module.exports = (function() {
   * @param {Object} [options] See aggregate
   * @see {Model#aggregate} for options
   *
-   * @return {Promise}
+   * @return {Promise<Any>}
   */
  Model.prototype.max = function(field, options) {
    return this.aggregate(field, 'max', options)
@@ -909,7 +909,7 @@ module.exports = (function() {
   * @param {Object} [options] See aggregate
   * @see {Model#aggregate} for options
   *
-   * @return {Promise}
+   * @return {Promise<Any>}
   */
  Model.prototype.min = function(field, options) {
    return this.aggregate(field, 'min', options)
@@ -922,7 +922,7 @@ module.exports = (function() {
   * @param {Object} [options] See aggregate
   * @see {Model#aggregate} for options
   *
-   * @return {Promise}
+   * @return {Promise<Number>}
   */
  Model.prototype.sum = function(field, options) {
    return this.aggregate(field, 'sum', options)
@@ -993,7 +993,7 @@ module.exports = (function() {
   * @param {Array}         [options.include] an array of include options - Used to build prefetched/included model instances
   * @param {Transaction}   [options.transaction]
   *
-   * @return {Promise}
+   * @return {Promise<Instance>}
   */  
  Model.prototype.create = function(values, options) {
    Utils.validateParameter(values, Object, { optional: true })
@@ -1021,8 +1021,7 @@ module.exports = (function() {
   * @param {Object}  [options] Options passed to the find call
   * @deprecated The syntax is due for change, in order to make `where` more consistent with the rest of the API
   *
-   * @return {Promise}
+   * @return {Promise<Instance>}
-   * @return {EventEmitter}
   * @method
   * @alias findOrBuild
   */
@@ -1069,7 +1068,7 @@ module.exports = (function() {
   * @param {Object}  [options] Options passed to the find and create calls
   * @deprecated The syntax is due for change, in order to make `where` more consistent with the rest of the API
   *
-   * @return {Promise}
+   * @return {Promise<Instance>}
   */
  Model.prototype.findOrCreate = function (where, defaults, options) {
    var self   = this
@@ -1118,7 +1117,7 @@ module.exports = (function() {
   * @param  {Boolean}      [options.hooks=false] Run before / after create hooks for each individual Instance? BulkCreate hooks will still be run.
   * @param  {Boolean}      [options.ignoreDuplicates=false] Ignore duplicate values for primary keys? (not supported by postgres)
   * 
-   * @return {Promise}
+   * @return {Promise<Array<Instance>>}
   */
  Model.prototype.bulkCreate = function(records, fieldsOrOptions, options) {
    Utils.validateParameter(fieldsOrOptions, Object, { deprecated: Array, optional: true, index: 2, method: 'Model#bulkCreate' })
@@ -1256,7 +1255,7 @@ module.exports = (function() {
   * @param  {Number}   [options.limit]     How many rows to delete
   * @param  {Boolean}  [options.truncate]  If set to true, dialects that support it will use TRUNCATE instead of DELETE FROM. If a table is truncated the where and limit options are ignored
   *
-   * @return {Promise}
+   * @return {Promise<undefined>}
   */
  Model.prototype.destroy = function(where, options) {
    options = options || {}
@@ -1339,7 +1338,7 @@ module.exports = (function() {
   * @param  {Number}   [options.limit]         How many rows to update (only for mysql and mariadb)
   * @deprecated The syntax is due for change, in order to make `where` more consistent with the rest of the API
   *
-   * @return {EventEmitter}
+   * @return {Promise}
   */
  Model.prototype.update = function(attrValueHash, where, options) {
    var self  = this
@@ -1432,7 +1431,7 @@ module.exports = (function() {
  /**
   * Run a describe query on the table. The result will be return to the listener as a hash of attributes and their types.
   * 
-   * @return {EventEmitter}
+   * @return {Promise}
   */
  Model.prototype.describe = function(schema) {
    return this.QueryInterface.describeTable(this.tableName, schema || this.options.schema || undefined)