Added return types to promises

Jan Aagaard Meier
Commit 7961c7ca authored May 16, 2014 by Jan Aagaard Meier
Showing with 22 additions and 23 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 || {})
@@ -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)