Skip to content

public / sequelize

Go to a project

不要怂，就是干，撸起袖子干！

Commit 14d14468 by Sushant Committed by GitHub
Options

docs: cleanup / correct jsdocs (#9702)

1 parent 84f80481
Expand all
Inline Side-by-side
Showing with 441 additions and 284 deletions
.eslintrc.json
...@@ -3,6 +3,22 @@ ...@@ -3,6 +3,22 @@
"mocha/no-exclusive-tests": "error", "mocha/no-exclusive-tests": "error",
"mocha/no-skipped-tests": "warn", "mocha/no-skipped-tests": "warn",
// "jsdoc/check-param-names": "error",
// "jsdoc/check-tag-names": "error",
// "jsdoc/check-types": "error",
// "jsdoc/newline-after-description": "error",
// "jsdoc/no-undefined-types": "error",
// "jsdoc/require-description-complete-sentence": "off",
// "jsdoc/require-example": "off",
// "jsdoc/require-hyphen-before-param-description": "off",
// "jsdoc/require-param": "error",
// "jsdoc/require-param-description": "error",
// "jsdoc/require-param-name": "error",
// "jsdoc/require-param-type": "error",
// "jsdoc/require-returns-description": "off",
// "jsdoc/require-returns-type": "error",
// "jsdoc/valid-types": "off",
"array-bracket-spacing": "error", "array-bracket-spacing": "error",
"comma-spacing": "error", "comma-spacing": "error",
"key-spacing": "error", "key-spacing": "error",
...@@ -90,11 +106,25 @@ ...@@ -90,11 +106,25 @@
"sourceType": "script" "sourceType": "script"
}, },
"plugins": [ "plugins": [
"mocha" "mocha",
"jsdoc"
], ],
"env": { "env": {
"node": true, "node": true,
"mocha": true, "mocha": true,
"es6": true "es6": true
},
"globals": {
"Association": true,
"HasMany": true,
"BelongsTo": true,
"HasOne": true,
"BelongsToMany": true,
"DataTypes": true,
"Sequelize": true,
"Transaction": true,
"Model": true,
"QueryInterface": true,
"QueryType": true
} }
} }
\ No newline at end of file
.gitignore
...@@ -2,21 +2,22 @@ test*.js ...@@ -2,21 +2,22 @@ test*.js
*.swp *.swp
.idea .idea
.DS_STORE .DS_STORE
node_modules
npm-debug.log npm-debug.log
*~ *~
test/binary/tmp/*
test/tmp/*
test/dialects/sqlite/test.sqlite test/dialects/sqlite/test.sqlite
test/sqlite/test.sqlite test/sqlite/test.sqlite
coverage-*
site
docs/api/tmp.md docs/api/tmp.md
ssce.js ssce.js
sscce.js sscce.js
coverage
.vscode/
*.sublime* *.sublime*
esdoc
package-lock.json package-lock.json
yarn.lock yarn.lock
coverage-*
coverage
test/tmp/*
test/binary/tmp/*
site
.vscode/
esdoc
node_modules
\ No newline at end of file
jsdoc.json 0 → 100644
{
"plugins": [
"plugins/markdown"
],
"markdown": {
"parser": "gfm"
},
"tags": {
"allowUnknownTags": false
},
"source": {
"include": [
"lib/",
"docs/index.md"
],
"excludePattern": "(node_modules)"
},
"opts": {
"template": "node_modules/docdash",
"encoding": "utf8",
"destination": "newdocs/",
"recurse": true,
"tutorials": "docs/"
},
"templates": {
"outputSourcePath": false,
"outputSourceFiles": false,
"includeDate": false,
"sort": false
}
}
\ No newline at end of file
lib/associations/base.js
...@@ -112,9 +112,10 @@ class Association { ...@@ -112,9 +112,10 @@ class Association {
/** /**
* Normalize input * Normalize input
* *
* @param input {Any}, it may be array or single obj, instance or primary key * @param {Array|string} input it may be array or single obj, instance or primary key
* *
* @returns <Array>, built objects * @private
* @returns {Array} built objects
*/ */
toInstanceArray(input) { toInstanceArray(input) {
if (!Array.isArray(input)) { if (!Array.isArray(input)) {
......
lib/associations/belongs-to-many.js
...@@ -357,12 +357,15 @@ class BelongsToMany extends Association { ...@@ -357,12 +357,15 @@ class BelongsToMany extends Association {
/** /**
* Get everything currently associated with this, using an optional where clause. * Get everything currently associated with this, using an optional where clause.
* *
* @param {Object} [options] * @see {@link Model.findAll} for a full explanation of options
*
* @param {<Model>} instance instance
* @param {Object} [options] find options
* @param {Object} [options.where] An optional where clause to limit the associated models * @param {Object} [options.where] An optional where clause to limit the associated models
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* @param {String} [options.schema] Apply a schema on the related model * @param {string} [options.schema] Apply a schema on the related model
* @see {@link Model.findAll} for a full explanation of options *
* @return {Promise<Array<Model>>} * @returns {Promise<Array<<Model>>>}
*/ */
get(instance, options) { get(instance, options) {
options = Utils.cloneDeep(options) || {}; options = Utils.cloneDeep(options) || {};
...@@ -426,10 +429,12 @@ class BelongsToMany extends Association { ...@@ -426,10 +429,12 @@ class BelongsToMany extends Association {
/** /**
* Count everything currently associated with this, using an optional where clause. * Count everything currently associated with this, using an optional where clause.
* *
* @param {Object} [options] * @param {<Model>} instance instance
* @param {Object} [options] find options
* @param {Object} [options.where] An optional where clause to limit the associated models * @param {Object} [options.where] An optional where clause to limit the associated models
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* @return {Promise<Integer>} *
* @returns {Promise<number>}
*/ */
count(instance, options) { count(instance, options) {
const association = this; const association = this;
...@@ -450,9 +455,11 @@ class BelongsToMany extends Association { ...@@ -450,9 +455,11 @@ class BelongsToMany extends Association {
/** /**
* Check if one or more instance(s) are associated with this. If a list of instances is passed, the function returns true if _all_ instances are associated * Check if one or more instance(s) are associated with this. If a list of instances is passed, the function returns true if _all_ instances are associated
* *
* @param {Model[]|Model|string[]|String|number[]|Number} [instance(s)] Can be an array of instances or their primary keys * @param {<Model>} sourceInstance source instance to associate new instances with
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [instances] Can be an array of instances or their primary keys
* @param {Object} [options] Options passed to getAssociations * @param {Object} [options] Options passed to getAssociations
* @return {Promise<boolean>} *
* @returns {Promise<boolean>}
*/ */
has(sourceInstance, instances, options) { has(sourceInstance, instances, options) {
const association = this; const association = this;
...@@ -489,13 +496,16 @@ class BelongsToMany extends Association { ...@@ -489,13 +496,16 @@ class BelongsToMany extends Association {
} }
/** /**
* Set the associated models by passing an array of instances or their primary keys. Everything that it not in the passed array will be un-associated. * Set the associated models by passing an array of instances or their primary keys.
* Everything that it not in the passed array will be un-associated.
* *
* @param {Array<Model|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations. * @param {<Model>} sourceInstance source instance to associate new instances with
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [newAssociatedObjects] A single instance or primary key, or a mixed array of persisted instances or primary keys
* @param {Object} [options] Options passed to `through.findAll`, `bulkCreate`, `update` and `destroy` * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate`, `update` and `destroy`
* @param {Object} [options.validate] Run validation for the join model * @param {Object} [options.validate] Run validation for the join model
* @param {Object} [options.through] Additional attributes for the join table. * @param {Object} [options.through] Additional attributes for the join table.
* @return {Promise} *
* @returns {Promise}
*/ */
set(sourceInstance, newAssociatedObjects, options) { set(sourceInstance, newAssociatedObjects, options) {
options = options || {}; options = options || {};
...@@ -590,13 +600,16 @@ class BelongsToMany extends Association { ...@@ -590,13 +600,16 @@ class BelongsToMany extends Association {
} }
/** /**
* Associate one ore several rows with `this`. * Associate one ore several rows with source instance. It will not un-associate any already assoicated instance
* that may be missing from `newInstances`.
* *
* @param {Model[]|Model|string[]|string|number[]|Number} [newAssociation(s)] A single instance or primary key, or a mixed array of persisted instances or primary keys * @param {<Model>} sourceInstance source instance to associate new instances with
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [newInstances] A single instance or primary key, or a mixed array of persisted instances or primary keys
* @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update` * @param {Object} [options] Options passed to `through.findAll`, `bulkCreate` and `update`
* @param {Object} [options.validate] Run validation for the join model. * @param {Object} [options.validate] Run validation for the join model.
* @param {Object} [options.through] Additional attributes for the join table. * @param {Object} [options.through] Additional attributes for the join table.
* @return {Promise} *
* @returns {Promise}
*/ */
add(sourceInstance, newInstances, options) { add(sourceInstance, newInstances, options) {
// If newInstances is null or undefined, no-op // If newInstances is null or undefined, no-op
...@@ -684,9 +697,11 @@ class BelongsToMany extends Association { ...@@ -684,9 +697,11 @@ class BelongsToMany extends Association {
/** /**
* Un-associate one or more instance(s). * Un-associate one or more instance(s).
* *
* @param {Model|String|Number} [oldAssociated] Can be an Instance or its primary key, or a mixed array of instances and primary keys * @param {<Model>} sourceInstance instance to un associate instances with
* @param {<Model>|<Model>[]|string|string[]|number|number[]} [oldAssociatedObjects] Can be an Instance or its primary key, or a mixed array of instances and primary keys
* @param {Object} [options] Options passed to `through.destroy` * @param {Object} [options] Options passed to `through.destroy`
* @return {Promise} *
* @returns {Promise}
*/ */
remove(sourceInstance, oldAssociatedObjects, options) { remove(sourceInstance, oldAssociatedObjects, options) {
const association = this; const association = this;
...@@ -705,10 +720,12 @@ class BelongsToMany extends Association { ...@@ -705,10 +720,12 @@ class BelongsToMany extends Association {
/** /**
* Create a new instance of the associated model and associate it with this. * Create a new instance of the associated model and associate it with this.
* *
* @param {Object} [values] * @param {<Model>} sourceInstance source instance
* @param {Object} [values] values for target model
* @param {Object} [options] Options passed to create and add * @param {Object} [options] Options passed to create and add
* @param {Object} [options.through] Additional attributes for the join table * @param {Object} [options.through] Additional attributes for the join table
* @return {Promise} *
* @returns {Promise}
*/ */
create(sourceInstance, values, options) { create(sourceInstance, values, options) {
const association = this; const association = this;
......
lib/associations/belongs-to.js
...@@ -113,13 +113,14 @@ class BelongsTo extends Association { ...@@ -113,13 +113,14 @@ class BelongsTo extends Association {
/** /**
* Get the associated instance. * Get the associated instance.
* *
* @param {Object} [options] * @param {<Model>|Array<Model>} instances source instances
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false. * @param {Object} [options] find options
* @param {String} [options.schema] Apply a schema on the related model * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false.
* @param {string} [options.schema] Apply a schema on the related model
* *
* @see {@link Model.findOne} for a full explanation of options * @see {@link Model.findOne} for a full explanation of options
* *
* @return {Promise<Model>} * @returns {Promise<<Model>>}
*/ */
get(instances, options) { get(instances, options) {
const where = {}; const where = {};
...@@ -183,11 +184,12 @@ class BelongsTo extends Association { ...@@ -183,11 +184,12 @@ class BelongsTo extends Association {
/** /**
* Set the associated model. * Set the associated model.
* *
* @param {Model|String|Number} [newAssociation] An persisted instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association. * @param {<Model>} sourceInstance the source instance
* @param {Object} [options] Options passed to `this.save` * @param {?<Model>|string|number} [associatedInstance] An persisted instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association.
* @param {Boolean} [options.save=true] Skip saving this after setting the foreign key if false. * @param {Object} [options={}] options passed to `this.save`
* @param {boolean} [options.save=true] Skip saving this after setting the foreign key if false.
* *
* @return {Promise} * @returns {Promise}
*/ */
set(sourceInstance, associatedInstance, options = {}) { set(sourceInstance, associatedInstance, options = {}) {
let value = associatedInstance; let value = associatedInstance;
...@@ -213,12 +215,13 @@ class BelongsTo extends Association { ...@@ -213,12 +215,13 @@ class BelongsTo extends Association {
/** /**
* Create a new instance of the associated model and associate it with this. * Create a new instance of the associated model and associate it with this.
* *
* @param {Object} [values] * @param {<Model>} sourceInstance the source instance
* @param {Object} [options] Options passed to `target.create` and setAssociation. * @param {Object} [values={}] values to create associated model instance with
* @param {Object} [options={}] Options passed to `target.create` and setAssociation.
* *
* @see {@link Model#create} for a full explanation of options * @see {@link Model#create} for a full explanation of options
* *
* @return {Promise} * @returns {Promise}
*/ */
create(sourceInstance, values, options) { create(sourceInstance, values, options) {
values = values || {}; values = values || {};
......
lib/associations/has-many.js
...@@ -157,12 +157,15 @@ class HasMany extends Association { ...@@ -157,12 +157,15 @@ class HasMany extends Association {
/** /**
* Get everything currently associated with this, using an optional where clause. * Get everything currently associated with this, using an optional where clause.
* *
* @param {Object} [options] * @param {<Model>|Array<Model>} instances source instances
* @param {Object} [options] find options
* @param {Object} [options.where] An optional where clause to limit the associated models * @param {Object} [options.where] An optional where clause to limit the associated models
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* @param {String} [options.schema] Apply a schema on the related model * @param {string} [options.schema] Apply a schema on the related model
*
* @see {@link Model.findAll} for a full explanation of options * @see {@link Model.findAll} for a full explanation of options
* @return {Promise<Array<Model>>} *
* @returns {Promise<Array<<Model>>>}
*/ */
get(instances, options = {}) { get(instances, options = {}) {
const where = {}; const where = {};
...@@ -238,11 +241,12 @@ class HasMany extends Association { ...@@ -238,11 +241,12 @@ class HasMany extends Association {
/** /**
* Count everything currently associated with this, using an optional where clause. * Count everything currently associated with this, using an optional where clause.
* *
* @param {Object} [options] * @param {<Model>} instance the source instance
* @param {Object} [options] find & count options
* @param {Object} [options.where] An optional where clause to limit the associated models * @param {Object} [options.where] An optional where clause to limit the associated models
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* *
* @return {Promise<Integer>} * @returns {Promise<number>}
*/ */
count(instance, options) { count(instance, options) {
options = Utils.cloneDeep(options); options = Utils.cloneDeep(options);
...@@ -265,10 +269,11 @@ class HasMany extends Association { ...@@ -265,10 +269,11 @@ class HasMany extends Association {
/** /**
* Check if one or more rows are associated with `this`. * Check if one or more rows are associated with `this`.
* *
* @param {Model[]|Model|string[]|String|number[]|Number} [instance(s)] * @param {<Model>} sourceInstance the source instance
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [targetInstances] Can be an array of instances or their primary keys
* @param {Object} [options] Options passed to getAssociations * @param {Object} [options] Options passed to getAssociations
* *
* @return {Promise} * @returns {Promise}
*/ */
has(sourceInstance, targetInstances, options) { has(sourceInstance, targetInstances, options) {
const where = {}; const where = {};
...@@ -305,10 +310,12 @@ class HasMany extends Association { ...@@ -305,10 +310,12 @@ class HasMany extends Association {
/** /**
* Set the associated models by passing an array of persisted instances or their primary keys. Everything that is not in the passed array will be un-associated * Set the associated models by passing an array of persisted instances or their primary keys. Everything that is not in the passed array will be un-associated
* *
* @param {Array<Model|String|Number>} [newAssociations] An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations. * @param {<Model>} sourceInstance source instance to associate new instances with
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [targetInstances] An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
* @param {Object} [options] Options passed to `target.findAll` and `update`. * @param {Object} [options] Options passed to `target.findAll` and `update`.
* @param {Object} [options.validate] Run validation for the join model * @param {Object} [options.validate] Run validation for the join model
* @return {Promise} *
* @returns {Promise}
*/ */
set(sourceInstance, targetInstances, options) { set(sourceInstance, targetInstances, options) {
if (targetInstances === null) { if (targetInstances === null) {
...@@ -377,9 +384,11 @@ class HasMany extends Association { ...@@ -377,9 +384,11 @@ class HasMany extends Association {
* Associate one or more target rows with `this`. This method accepts a Model / string / number to associate a single row, * Associate one or more target rows with `this`. This method accepts a Model / string / number to associate a single row,
* or a mixed array of Model / string / numbers to associate multiple rows. * or a mixed array of Model / string / numbers to associate multiple rows.
* *
* @param {Model[]|Model|string[]|string|number[]|number} [newAssociation(s)] * @param {<Model>} sourceInstance the source instance
* @param {<Model>|<Model>[]|string[]|string|number[]|number} [targetInstances] A single instance or primary key, or a mixed array of persisted instances or primary keys
* @param {Object} [options] Options passed to `target.update`. * @param {Object} [options] Options passed to `target.update`.
* @return {Promise} *
* @returns {Promise}
*/ */
add(sourceInstance, targetInstances, options = {}) { add(sourceInstance, targetInstances, options = {}) {
if (!targetInstances) return Utils.Promise.resolve(); if (!targetInstances) return Utils.Promise.resolve();
...@@ -402,9 +411,11 @@ class HasMany extends Association { ...@@ -402,9 +411,11 @@ class HasMany extends Association {
/** /**
* Un-associate one or several target rows. * Un-associate one or several target rows.
* *
* @param {Model[]|Model|String[]|string|Number[]|number} [oldAssociatedInstance(s)] * @param {<Model>} sourceInstance instance to un associate instances with
* @param {<Model>|<Model>[]|string|string[]|number|number[]} [targetInstances] Can be an Instance or its primary key, or a mixed array of instances and primary keys
* @param {Object} [options] Options passed to `target.update` * @param {Object} [options] Options passed to `target.update`
* @return {Promise} *
* @returns {Promise}
*/ */
remove(sourceInstance, targetInstances, options = {}) { remove(sourceInstance, targetInstances, options = {}) {
const update = {}; const update = {};
...@@ -425,9 +436,11 @@ class HasMany extends Association { ...@@ -425,9 +436,11 @@ class HasMany extends Association {
/** /**
* Create a new instance of the associated model and associate it with this. * Create a new instance of the associated model and associate it with this.
* *
* @param {Object} [values] * @param {<Model>} sourceInstance source instance
* @param {Object} [options] Options passed to `target.create`. * @param {Object} [values] values for target model instance
* @return {Promise} * @param {Object} [options] Options passed to `target.create`
*
* @returns {Promise}
*/ */
create(sourceInstance, values, options = {}) { create(sourceInstance, values, options = {}) {
if (Array.isArray(options)) { if (Array.isArray(options)) {
......
lib/associations/has-one.js
...@@ -112,11 +112,14 @@ class HasOne extends Association { ...@@ -112,11 +112,14 @@ class HasOne extends Association {
/** /**
* Get the associated instance. * Get the associated instance.
* *
* @param {Object} [options] * @param {<Model>|Array<Model>} instances source instances
* @param {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false * @param {Object} [options] find options
* @param {String} [options.schema] Apply a schema on the related model * @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* @param {string} [options.schema] Apply a schema on the related model
*
* @see {@link Model.findOne} for a full explanation of options * @see {@link Model.findOne} for a full explanation of options
* @return {Promise<Model>} *
* @returns {Promise<Model>}
*/ */
get(instances, options) { get(instances, options) {
const where = {}; const where = {};
...@@ -180,10 +183,11 @@ class HasOne extends Association { ...@@ -180,10 +183,11 @@ class HasOne extends Association {
/** /**
* Set the associated model. * Set the associated model.
* *
* @param {Model|String|Number} [associatedInstance] An persisted instance or the primary key of a persisted instance to associate with this. Pass `null` or `undefined` to remove the association. * @param {<Model>} sourceInstance the source instance
* @param {Object} [options] Options passed to getAssociation and `target.save` * @param {?<Model>|string|number} [associatedInstance] An persisted instance or the primary key of an instance to associate with this. Pass `null` or `undefined` to remove the association.
* @param {Object} [options] Options passed to getAssociation and `target.save`
* *
* @return {Promise} * @returns {Promise}
*/ */
set(sourceInstance, associatedInstance, options) { set(sourceInstance, associatedInstance, options) {
let alreadyAssociated; let alreadyAssociated;
...@@ -229,12 +233,13 @@ class HasOne extends Association { ...@@ -229,12 +233,13 @@ class HasOne extends Association {
/** /**
* Create a new instance of the associated model and associate it with this. * Create a new instance of the associated model and associate it with this.
* *
* @param {Object} [values] * @param {<Model>} sourceInstance the source instance
* @param {Object} [values={}] values to create associated model instance with
* @param {Object} [options] Options passed to `target.create` and setAssociation. * @param {Object} [options] Options passed to `target.create` and setAssociation.
* *
* @see {@link Model#create} for a full explanation of options * @see {@link Model#create} for a full explanation of options
* *
* @return {Promise} * @returns {Promise}
*/ */
create(sourceInstance, values, options) { create(sourceInstance, values, options) {
values = values || {}; values = values || {};
......
lib/associations/helpers.js
...@@ -45,10 +45,12 @@ exports.addForeignKeyConstraints = addForeignKeyConstraints; ...@@ -45,10 +45,12 @@ exports.addForeignKeyConstraints = addForeignKeyConstraints;
* Mixin (inject) association methods to model prototype * Mixin (inject) association methods to model prototype
* *
* @private * @private
* @param {Object} Association instance *
* @param {Object} Model prototype * @param {Object} association instance
* @param {Array} Method names to inject * @param {Object} obj Model prototype
* @param {Object} Mapping between model and association method names * @param {Array} methods Method names to inject
* @param {Object} aliases Mapping between model and association method names
*
*/ */
function mixinMethods(association, obj, methods, aliases) { function mixinMethods(association, obj, methods, aliases) {
aliases = aliases || {}; aliases = aliases || {};
......
lib/dialects/abstract/connection-manager.js
...@@ -62,7 +62,7 @@ class ConnectionManager { ...@@ -62,7 +62,7 @@ class ConnectionManager {
* Handler which executes on process exit or connection manager shutdown * Handler which executes on process exit or connection manager shutdown
* *
* @private * @private
* @return {Promise} * @returns {Promise}
*/ */
_onProcessExit() { _onProcessExit() {
if (!this.pool) { if (!this.pool) {
...@@ -78,7 +78,7 @@ class ConnectionManager { ...@@ -78,7 +78,7 @@ class ConnectionManager {
/** /**
* Drain the pool and close it permanently * Drain the pool and close it permanently
* *
* @return {Promise} * @returns {Promise}
*/ */
close() { close() {
// Mark close of pool // Mark close of pool
...@@ -234,10 +234,10 @@ class ConnectionManager { ...@@ -234,10 +234,10 @@ class ConnectionManager {
* *
* @param {Object} [options] Pool options * @param {Object} [options] Pool options
* @param {Integer} [options.priority] Set priority for this call. Read more at https://github.com/coopernurse/node-pool#priority-queueing * @param {Integer} [options.priority] Set priority for this call. Read more at https://github.com/coopernurse/node-pool#priority-queueing
* @param {String} [options.type] Set which replica to use. Available options are `read` and `write` * @param {string} [options.type] Set which replica to use. Available options are `read` and `write`
* @param {Boolean} [options.useMaster=false] Force master or write replica to get connection from * @param {boolean} [options.useMaster=false] Force master or write replica to get connection from
* *
* @return {Promise<Connection>} * @returns {Promise<Connection>}
*/ */
getConnection(options) { getConnection(options) {
options = options || {}; options = options || {};
...@@ -282,7 +282,7 @@ class ConnectionManager { ...@@ -282,7 +282,7 @@ class ConnectionManager {
* *
* @param {Connection} connection * @param {Connection} connection
* *
* @return {Promise} * @returns {Promise}
*/ */
releaseConnection(connection) { releaseConnection(connection) {
return this.pool.release(connection) return this.pool.release(connection)
...@@ -296,7 +296,7 @@ class ConnectionManager { ...@@ -296,7 +296,7 @@ class ConnectionManager {
* *
* @param {Object|Error} mayBeConnection Object which can be either connection or error * @param {Object|Error} mayBeConnection Object which can be either connection or error
* *
* @return {Promise<Connection>} * @returns {Promise<Connection>}
*/ */
_determineConnection(mayBeConnection) { _determineConnection(mayBeConnection) {
if (mayBeConnection instanceof Error) { if (mayBeConnection instanceof Error) {
...@@ -313,7 +313,7 @@ class ConnectionManager { ...@@ -313,7 +313,7 @@ class ConnectionManager {
* *
* @param {*} config Connection config * @param {*} config Connection config
* @private * @private
* @return {Promise<Connection>} * @returns {Promise<Connection>}
*/ */
_connect(config) { _connect(config) {
return this.sequelize.runHooks('beforeConnect', config) return this.sequelize.runHooks('beforeConnect', config)
...@@ -326,7 +326,7 @@ class ConnectionManager { ...@@ -326,7 +326,7 @@ class ConnectionManager {
* *
* @param {Connection} connection * @param {Connection} connection
* @private * @private
* @return {Promise} * @returns {Promise}
*/ */
_disconnect(connection) { _disconnect(connection) {
return this.dialect.connectionManager.disconnect(connection); return this.dialect.connectionManager.disconnect(connection);
...@@ -337,7 +337,7 @@ class ConnectionManager { ...@@ -337,7 +337,7 @@ class ConnectionManager {
* *
* @param {Connection} connection * @param {Connection} connection
* *
* @return {Boolean} * @returns {boolean}
*/ */
_validate(connection) { _validate(connection) {
if (!this.dialect.connectionManager.validate) { if (!this.dialect.connectionManager.validate) {
......
lib/dialects/abstract/query-generator.js
...@@ -95,7 +95,7 @@ class QueryGenerator { ...@@ -95,7 +95,7 @@ class QueryGenerator {
/** /**
* Returns an insert into command * Returns an insert into command
* *
* @param {String} table * @param {string} table
* @param {Object} valueHash attribute value pairs * @param {Object} valueHash attribute value pairs
* @param {Object} modelAttributes * @param {Object} modelAttributes
* @param {Object} [options] * @param {Object} [options]
...@@ -262,7 +262,7 @@ class QueryGenerator { ...@@ -262,7 +262,7 @@ class QueryGenerator {
/** /**
* Returns an insert into command for multiple values. * Returns an insert into command for multiple values.
* *
* @param {String} tableName * @param {string} tableName
* @param {Object} fieldValueHashes * @param {Object} fieldValueHashes
* @param {Object} options * @param {Object} options
* @param {Object} fieldMappedAttributes * @param {Object} fieldMappedAttributes
...@@ -330,7 +330,7 @@ class QueryGenerator { ...@@ -330,7 +330,7 @@ class QueryGenerator {
/** /**
* Returns an update query * Returns an update query
* *
* @param {String} tableName * @param {string} tableName
* @param {Object} attrValueHash * @param {Object} attrValueHash
* @param {Object} where A hash with conditions (e.g. {name: 'foo'}) OR an ID as integer * @param {Object} where A hash with conditions (e.g. {name: 'foo'}) OR an ID as integer
OR a string with conditions (e.g. 'name="foo"'). If you use a string, you have to escape it on your own. OR a string with conditions (e.g. 'name="foo"'). If you use a string, you have to escape it on your own.
...@@ -452,8 +452,8 @@ class QueryGenerator { ...@@ -452,8 +452,8 @@ class QueryGenerator {
/** /**
* Returns an update query using arithmetic operator * Returns an update query using arithmetic operator
* *
* @param {String} operator String with the arithmetic operator (e.g. '+' or '-') * @param {string} operator String with the arithmetic operator (e.g. '+' or '-')
* @param {String} tableName Name of the table * @param {string} tableName Name of the table
* @param {Object} attrValueHash A hash with attribute-value-pairs * @param {Object} attrValueHash A hash with attribute-value-pairs
* @param {Object} where A hash with conditions (e.g. {name: 'foo'}) OR an ID as integer * @param {Object} where A hash with conditions (e.g. {name: 'foo'}) OR an ID as integer
OR a string with conditions (e.g. 'name="foo"'). If you use a string, you have to escape it on your own. OR a string with conditions (e.g. 'name="foo"'). If you use a string, you have to escape it on your own.
...@@ -895,13 +895,13 @@ class QueryGenerator { ...@@ -895,13 +895,13 @@ class QueryGenerator {
/** /**
* Split a list of identifiers by "." and quote each part * Split a list of identifiers by "." and quote each part
* *
* @param {String} dialect Dialect name * @param {string} dialect Dialect name
* @param {String} identifiers * @param {string} identifiers
* @param {Object} [options] * @param {Object} [options]
* @param {Boolean} [options.force=false] * @param {boolean} [options.force=false]
* @param {Boolean} [options.quoteIdentifiers=true] * @param {boolean} [options.quoteIdentifiers=true]
* *
* @returns {String} * @returns {string}
*/ */
quoteIdentifier(identifier, force) { quoteIdentifier(identifier, force) {
return QuoteHelper.quoteIdentifier(this.dialect, identifier, { return QuoteHelper.quoteIdentifier(this.dialect, identifier, {
...@@ -929,7 +929,7 @@ class QueryGenerator { ...@@ -929,7 +929,7 @@ class QueryGenerator {
* @param {String|Object} param table string or object * @param {String|Object} param table string or object
* @param {String|Boolean} alias alias name * @param {String|Boolean} alias alias name
* *
* @returns {String} * @returns {string}
*/ */
quoteTable(param, alias) { quoteTable(param, alias) {
let table = ''; let table = '';
...@@ -1065,9 +1065,9 @@ class QueryGenerator { ...@@ -1065,9 +1065,9 @@ class QueryGenerator {
/** /**
* Generates an SQL query that extract JSON property of given path. * Generates an SQL query that extract JSON property of given path.
* *
* @param {String} column The JSON column * @param {string} column The JSON column
* @param {String|Array<String>} [path] The path to extract (optional) * @param {String|Array<String>} [path] The path to extract (optional)
* @returns {String} The generated sql query * @returns {string} The generated sql query
* @private * @private
*/ */
jsonPathExtractionQuery(column, path) { jsonPathExtractionQuery(column, path) {
...@@ -1946,7 +1946,7 @@ class QueryGenerator { ...@@ -1946,7 +1946,7 @@ class QueryGenerator {
* *
* @param {Object} options An object with selectQuery options. * @param {Object} options An object with selectQuery options.
* @param {Object} options The model passed to the selectQuery. * @param {Object} options The model passed to the selectQuery.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
addLimitAndOffset(options) { addLimitAndOffset(options) {
......
lib/dialects/abstract/query-generator/helpers/quote.js
...@@ -23,13 +23,13 @@ const postgresReservedWords = 'all,analyse,analyze,and,any,array,as,asc,asymmetr ...@@ -23,13 +23,13 @@ const postgresReservedWords = 'all,analyse,analyze,and,any,array,as,asc,asymmetr
/** /**
* *
* @param {String} dialect Dialect name * @param {string} dialect Dialect name
* @param {String} identifier Identifier to quote * @param {string} identifier Identifier to quote
* @param {Object} [options] * @param {Object} [options]
* @param {Boolean} [options.force=false] * @param {boolean} [options.force=false]
* @param {Boolean} [options.quoteIdentifiers=true] * @param {boolean} [options.quoteIdentifiers=true]
* *
* @returns {String} * @returns {string}
* @private * @private
*/ */
function quoteIdentifier(dialect, identifier, options) { function quoteIdentifier(dialect, identifier, options) {
...@@ -79,9 +79,9 @@ module.exports.quoteIdentifier = quoteIdentifier; ...@@ -79,9 +79,9 @@ module.exports.quoteIdentifier = quoteIdentifier;
/** /**
* Test if a give string is already quoted * Test if a give string is already quoted
* *
* @param {String} identifier * @param {string} identifier
* *
* @return Boolean * @returns Boolean
* @private * @private
*/ */
function isIdentifierQuoted(identifier) { function isIdentifierQuoted(identifier) {
......
lib/dialects/abstract/query-generator/transaction.js
...@@ -6,9 +6,9 @@ const TransactionQueries = { ...@@ -6,9 +6,9 @@ const TransactionQueries = {
/** /**
* Returns a query that starts a transaction. * Returns a query that starts a transaction.
* *
* @param {Boolean} value A boolean that states whether autocommit shall be done or not. * @param {boolean} value A boolean that states whether autocommit shall be done or not.
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
setAutocommitQuery(value, options) { setAutocommitQuery(value, options) {
...@@ -27,9 +27,9 @@ const TransactionQueries = { ...@@ -27,9 +27,9 @@ const TransactionQueries = {
/** /**
* Returns a query that sets the transaction isolation level. * Returns a query that sets the transaction isolation level.
* *
* @param {String} value The isolation level. * @param {string} value The isolation level.
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
setIsolationLevelQuery(value, options) { setIsolationLevelQuery(value, options) {
...@@ -49,7 +49,7 @@ const TransactionQueries = { ...@@ -49,7 +49,7 @@ const TransactionQueries = {
* *
* @param {Transaction} transaction * @param {Transaction} transaction
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
startTransactionQuery(transaction) { startTransactionQuery(transaction) {
...@@ -66,7 +66,7 @@ const TransactionQueries = { ...@@ -66,7 +66,7 @@ const TransactionQueries = {
* *
* @param {Transaction} transaction * @param {Transaction} transaction
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
deferConstraintsQuery() {}, deferConstraintsQuery() {},
...@@ -79,7 +79,7 @@ const TransactionQueries = { ...@@ -79,7 +79,7 @@ const TransactionQueries = {
* Returns a query that commits a transaction. * Returns a query that commits a transaction.
* *
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
commitTransactionQuery(transaction) { commitTransactionQuery(transaction) {
...@@ -95,7 +95,7 @@ const TransactionQueries = { ...@@ -95,7 +95,7 @@ const TransactionQueries = {
* *
* @param {Transaction} transaction * @param {Transaction} transaction
* @param {Object} options An object with options. * @param {Object} options An object with options.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
rollbackTransactionQuery(transaction) { rollbackTransactionQuery(transaction) {
......
lib/dialects/abstract/query.js
...@@ -95,7 +95,7 @@ class AbstractQuery { ...@@ -95,7 +95,7 @@ class AbstractQuery {
* *
* query.run('SELECT 1') * query.run('SELECT 1')
* *
* @param {String} sql - The SQL query which should be executed. * @param {string} sql - The SQL query which should be executed.
* @private * @private
*/ */
run() { run() {
...@@ -105,7 +105,7 @@ class AbstractQuery { ...@@ -105,7 +105,7 @@ class AbstractQuery {
/** /**
* Check the logging option of the instance and print deprecation warnings. * Check the logging option of the instance and print deprecation warnings.
* *
* @return {void} * @returns {void}
* @private * @private
*/ */
checkLoggingOption() { checkLoggingOption() {
...@@ -118,7 +118,7 @@ class AbstractQuery { ...@@ -118,7 +118,7 @@ class AbstractQuery {
/** /**
* Get the attributes of an insert query, which contains the just inserted id. * Get the attributes of an insert query, which contains the just inserted id.
* *
* @return {String} The field name. * @returns {string} The field name.
* @private * @private
*/ */
getInsertIdField() { getInsertIdField() {
......
lib/dialects/mssql/query-generator.js
...@@ -698,7 +698,7 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator { ...@@ -698,7 +698,7 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generate common SQL prefix for ForeignKeysQuery. * Generate common SQL prefix for ForeignKeysQuery.
* @returns {String} * @returns {string}
*/ */
_getForeignKeysQueryPrefix(catalogName) { _getForeignKeysQueryPrefix(catalogName) {
return 'SELECT ' + return 'SELECT ' +
...@@ -725,8 +725,8 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator { ...@@ -725,8 +725,8 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that returns all foreign keys details of a table. * Generates an SQL query that returns all foreign keys details of a table.
* @param {Stirng|Object} table * @param {Stirng|Object} table
* @param {String} catalogName database name * @param {string} catalogName database name
* @returns {String} * @returns {string}
*/ */
getForeignKeysQuery(table, catalogName) { getForeignKeysQuery(table, catalogName) {
const tableName = table.tableName || table; const tableName = table.tableName || table;
......
lib/dialects/mssql/query-interface.js
...@@ -11,14 +11,13 @@ ...@@ -11,14 +11,13 @@
/** /**
A wrapper that fixes MSSQL's inability to cleanly remove columns from existing tables if they have a default constraint. A wrapper that fixes MSSQL's inability to cleanly remove columns from existing tables if they have a default constraint.
@method removeColumn
@for QueryInterface
@param {String} tableName The name of the table. @param {string} tableName The name of the table.
@param {String} attributeName The name of the attribute that we want to remove. @param {string} attributeName The name of the attribute that we want to remove.
@param {Object} options @param {Object} options
@param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries @param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries
@private
@private
*/ */
const removeColumn = function(tableName, attributeName, options) { const removeColumn = function(tableName, attributeName, options) {
options = Object.assign({ raw: true }, options || {}); options = Object.assign({ raw: true }, options || {});
......
lib/dialects/mysql/connection-manager.js
...@@ -17,7 +17,7 @@ const parserStore = require('../parserStore')('mysql'); ...@@ -17,7 +17,7 @@ const parserStore = require('../parserStore')('mysql');
* Use https://github.com/sidorares/node-mysql2 to connect with MySQL server * Use https://github.com/sidorares/node-mysql2 to connect with MySQL server
* *
* @extends AbstractConnectionManager * @extends AbstractConnectionManager
* @return Class<ConnectionManager> * @returns Class<ConnectionManager>
* @private * @private
*/ */
...@@ -63,7 +63,7 @@ class ConnectionManager extends AbstractConnectionManager { ...@@ -63,7 +63,7 @@ class ConnectionManager extends AbstractConnectionManager {
* Set the pool handlers on connection.error * Set the pool handlers on connection.error
* Also set proper timezone once conection is connected * Also set proper timezone once conection is connected
* *
* @return Promise<Connection> * @returns Promise<Connection>
* @private * @private
*/ */
connect(config) { connect(config) {
......
lib/dialects/mysql/query-generator.js
...@@ -403,8 +403,8 @@ class MySQLQueryGenerator extends AbstractQueryGenerator { ...@@ -403,8 +403,8 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Check whether the statmement is json function or simple path * Check whether the statmement is json function or simple path
* *
* @param {String} stmt The statement to validate * @param {string} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function * @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token * @throws {Error} throw if the statement looks like json function but has invalid token
* @private * @private
*/ */
...@@ -469,7 +469,7 @@ class MySQLQueryGenerator extends AbstractQueryGenerator { ...@@ -469,7 +469,7 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates fields for getForeignKeysQuery * Generates fields for getForeignKeysQuery
* @returns {String} fields * @returns {string} fields
* @private * @private
*/ */
_getForeignKeysQueryFields() { _getForeignKeysQueryFields() {
...@@ -492,9 +492,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator { ...@@ -492,9 +492,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that returns all foreign keys of a table. * Generates an SQL query that returns all foreign keys of a table.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @param {String} schemaName The name of the schema. * @param {string} schemaName The name of the schema.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
getForeignKeysQuery(tableName, schemaName) { getForeignKeysQuery(tableName, schemaName) {
...@@ -505,9 +505,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator { ...@@ -505,9 +505,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that returns the foreign key constraint of a given column. * Generates an SQL query that returns the foreign key constraint of a given column.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @param {String} columnName The name of the column. * @param {string} columnName The name of the column.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
getForeignKeyQuery(table, columnName) { getForeignKeyQuery(table, columnName) {
...@@ -529,9 +529,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator { ...@@ -529,9 +529,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that removes a foreign key from a table. * Generates an SQL query that removes a foreign key from a table.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @param {String} foreignKey The name of the foreign key constraint. * @param {string} foreignKey The name of the foreign key constraint.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
dropForeignKeyQuery(tableName, foreignKey) { dropForeignKeyQuery(tableName, foreignKey) {
......
lib/dialects/mysql/query-interface.js
...@@ -14,13 +14,11 @@ const sequelizeErrors = require('../../errors'); ...@@ -14,13 +14,11 @@ const sequelizeErrors = require('../../errors');
/** /**
A wrapper that fixes MySQL's inability to cleanly remove columns from existing tables if they have a foreign key constraint. A wrapper that fixes MySQL's inability to cleanly remove columns from existing tables if they have a foreign key constraint.
@method removeColumn @param {string} tableName The name of the table.
@for QueryInterface @param {string} columnName The name of the attribute that we want to remove.
@param {String} tableName The name of the table.
@param {String} columnName The name of the attribute that we want to remove.
@param {Object} options @param {Object} options
@private
@private
*/ */
function removeColumn(tableName, columnName, options) { function removeColumn(tableName, columnName, options) {
options = options || {}; options = options || {};
......
lib/dialects/postgres/query-generator.js
...@@ -129,8 +129,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator { ...@@ -129,8 +129,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/** /**
* Check whether the statmement is json function or simple path * Check whether the statmement is json function or simple path
* *
* @param {String} stmt The statement to validate * @param {string} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function * @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token * @throws {Error} throw if the statement looks like json function but has invalid token
*/ */
_checkValidJsonStatement(stmt) { _checkValidJsonStatement(stmt) {
...@@ -841,8 +841,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator { ...@@ -841,8 +841,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that returns all foreign keys of a table. * Generates an SQL query that returns all foreign keys of a table.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
getForeignKeysQuery(tableName) { getForeignKeysQuery(tableName) {
...@@ -852,7 +852,7 @@ class PostgresQueryGenerator extends AbstractQueryGenerator { ...@@ -852,7 +852,7 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generate common SQL prefix for getForeignKeyReferencesQuery. * Generate common SQL prefix for getForeignKeyReferencesQuery.
* @returns {String} * @returns {string}
*/ */
_getForeignKeyReferencesQueryPrefix() { _getForeignKeyReferencesQueryPrefix() {
return 'SELECT ' + return 'SELECT ' +
...@@ -878,9 +878,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator { ...@@ -878,9 +878,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
* Generates an SQL query that returns all foreign keys details of a table. * Generates an SQL query that returns all foreign keys details of a table.
* *
* As for getForeignKeysQuery is not compatible with getForeignKeyReferencesQuery, so add a new function. * As for getForeignKeysQuery is not compatible with getForeignKeyReferencesQuery, so add a new function.
* @param {String} tableName * @param {string} tableName
* @param {String} catalogName * @param {string} catalogName
* @param {String} schemaName * @param {string} schemaName
*/ */
getForeignKeyReferencesQuery(tableName, catalogName, schemaName) { getForeignKeyReferencesQuery(tableName, catalogName, schemaName) {
return this._getForeignKeyReferencesQueryPrefix() + return this._getForeignKeyReferencesQueryPrefix() +
...@@ -900,9 +900,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator { ...@@ -900,9 +900,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/** /**
* Generates an SQL query that removes a foreign key from a table. * Generates an SQL query that removes a foreign key from a table.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @param {String} foreignKey The name of the foreign key constraint. * @param {string} foreignKey The name of the foreign key constraint.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
dropForeignKeyQuery(tableName, foreignKey) { dropForeignKeyQuery(tableName, foreignKey) {
......
lib/dialects/postgres/query-interface.js
...@@ -17,12 +17,12 @@ const _ = require('lodash'); ...@@ -17,12 +17,12 @@ const _ = require('lodash');
/** /**
* Ensure enum and their values * Ensure enum and their values
* *
* @param {String} tableName Name of table to create * @param {string} tableName Name of table to create
* @param {Object} attributes Object representing a list of normalized table attributes * @param {Object} attributes Object representing a list of normalized table attributes
* @param {Object} [attributes] * @param {Object} [attributes]
* @param {Model} [model] * @param {Model} [model]
* *
* @return {Promise} * @returns {Promise}
* @private * @private
*/ */
function ensureEnums(tableName, attributes, options, model) { function ensureEnums(tableName, attributes, options, model) {
......
lib/dialects/sqlite/query-generator.js
...@@ -78,8 +78,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator { ...@@ -78,8 +78,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator {
/** /**
* Check whether the statmement is json function or simple path * Check whether the statmement is json function or simple path
* *
* @param {String} stmt The statement to validate * @param {string} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function * @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token * @throws {Error} throw if the statement looks like json function but has invalid token
*/ */
_checkValidJsonStatement(stmt) { _checkValidJsonStatement(stmt) {
...@@ -490,8 +490,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator { ...@@ -490,8 +490,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator {
/** /**
* Generates an SQL query that returns all foreign keys of a table. * Generates an SQL query that returns all foreign keys of a table.
* *
* @param {String} tableName The name of the table. * @param {string} tableName The name of the table.
* @return {String} The generated sql query. * @returns {string} The generated sql query.
* @private * @private
*/ */
getForeignKeysQuery(tableName) { getForeignKeysQuery(tableName) {
......
lib/dialects/sqlite/query-interface.js
...@@ -18,11 +18,8 @@ const QueryTypes = require('../../query-types'); ...@@ -18,11 +18,8 @@ const QueryTypes = require('../../query-types');
It will create a backup of the table, drop the table afterwards and create a It will create a backup of the table, drop the table afterwards and create a
new table with the same name but without the obsolete column. new table with the same name but without the obsolete column.
@method removeColumn @param {string} tableName The name of the table.
@for QueryInterface @param {string} attributeName The name of the attribute that we want to remove.
@param {String} tableName The name of the table.
@param {String} attributeName The name of the attribute that we want to remove.
@param {Object} options @param {Object} options
@param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries @param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries
...@@ -48,10 +45,7 @@ exports.removeColumn = removeColumn; ...@@ -48,10 +45,7 @@ exports.removeColumn = removeColumn;
It will create a backup of the table, drop the table afterwards and create a It will create a backup of the table, drop the table afterwards and create a
new table with the same name but with a modified version of the respective column. new table with the same name but with a modified version of the respective column.
@method changeColumn @param {string} tableName The name of the table.
@for QueryInterface
@param {String} tableName The name of the table.
@param {Object} attributes An object with the attribute's name as key and its options as value object. @param {Object} attributes An object with the attribute's name as key and its options as value object.
@param {Object} options @param {Object} options
@param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries @param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries
...@@ -79,12 +73,9 @@ exports.changeColumn = changeColumn; ...@@ -79,12 +73,9 @@ exports.changeColumn = changeColumn;
It will create a backup of the table, drop the table afterwards and create a It will create a backup of the table, drop the table afterwards and create a
new table with the same name but with a renamed version of the respective column. new table with the same name but with a renamed version of the respective column.
@method renameColumn @param {string} tableName The name of the table.
@for QueryInterface @param {string} attrNameBefore The name of the attribute before it was renamed.
@param {string} attrNameAfter The name of the attribute after it was renamed.
@param {String} tableName The name of the table.
@param {String} attrNameBefore The name of the attribute before it was renamed.
@param {String} attrNameAfter The name of the attribute after it was renamed.
@param {Object} options @param {Object} options
@param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries @param {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries
...@@ -174,7 +165,7 @@ exports.addConstraint = addConstraint; ...@@ -174,7 +165,7 @@ exports.addConstraint = addConstraint;
/** /**
* *
* @param {String} tableName * @param {string} tableName
* @param {Object} options Query Options * @param {Object} options Query Options
* *
* @private * @private
......
lib/errors/index.js
...@@ -6,6 +6,8 @@ ...@@ -6,6 +6,8 @@
* *
* This means that errors can be accessed using `Sequelize.ValidationError` or `sequelize.ValidationError` * This means that errors can be accessed using `Sequelize.ValidationError` or `sequelize.ValidationError`
* The Base Error all Sequelize Errors inherit from. * The Base Error all Sequelize Errors inherit from.
*
* @extends Error
*/ */
class BaseError extends Error { class BaseError extends Error {
constructor(message) { constructor(message) {
...@@ -18,6 +20,8 @@ exports.BaseError = BaseError; ...@@ -18,6 +20,8 @@ exports.BaseError = BaseError;
/** /**
* Scope Error. Thrown when the sequelize cannot query the specified scope. * Scope Error. Thrown when the sequelize cannot query the specified scope.
*
* @extends BaseError
*/ */
class SequelizeScopeError extends BaseError { class SequelizeScopeError extends BaseError {
constructor(parent) { constructor(parent) {
...@@ -36,6 +40,8 @@ exports.SequelizeScopeError = SequelizeScopeError; ...@@ -36,6 +40,8 @@ exports.SequelizeScopeError = SequelizeScopeError;
* @param {Array} [errors] Array of ValidationErrorItem objects describing the validation errors * @param {Array} [errors] Array of ValidationErrorItem objects describing the validation errors
* *
* @property errors {ValidationErrorItems[]} * @property errors {ValidationErrorItems[]}
*
* @extends BaseError
*/ */
class ValidationError extends BaseError { class ValidationError extends BaseError {
constructor(message, errors) { constructor(message, errors) {
...@@ -63,7 +69,8 @@ class ValidationError extends BaseError { ...@@ -63,7 +69,8 @@ class ValidationError extends BaseError {
* Gets all validation error items for the path / field specified. * Gets all validation error items for the path / field specified.
* *
* @param {string} path The path to be checked for error items * @param {string} path The path to be checked for error items
* @returns {ValidationErrorItem[]} Validation error items for the specified path *
* @returns {Array<ValidationErrorItem>} Validation error items for the specified path
*/ */
get(path) { get(path) {
return this.errors.reduce((reduced, error) => { return this.errors.reduce((reduced, error) => {
...@@ -78,6 +85,8 @@ exports.ValidationError = ValidationError; ...@@ -78,6 +85,8 @@ exports.ValidationError = ValidationError;
/** /**
* Thrown when attempting to update a stale model instance * Thrown when attempting to update a stale model instance
*
* @extends BaseError
*/ */
class OptimisticLockError extends BaseError { class OptimisticLockError extends BaseError {
constructor(options) { constructor(options) {
...@@ -107,6 +116,8 @@ exports.OptimisticLockError = OptimisticLockError; ...@@ -107,6 +116,8 @@ exports.OptimisticLockError = OptimisticLockError;
/** /**
* A base class for all database related errors. * A base class for all database related errors.
*
* @extends BaseError
*/ */
class DatabaseError extends BaseError { class DatabaseError extends BaseError {
constructor(parent) { constructor(parent) {
...@@ -132,6 +143,8 @@ exports.DatabaseError = DatabaseError; ...@@ -132,6 +143,8 @@ exports.DatabaseError = DatabaseError;
/** /**
* Thrown when a database query times out because of a deadlock * Thrown when a database query times out because of a deadlock
*
* @extends DatabaseError
*/ */
class TimeoutError extends DatabaseError { class TimeoutError extends DatabaseError {
constructor(parent) { constructor(parent) {
...@@ -144,6 +157,8 @@ exports.TimeoutError = TimeoutError; ...@@ -144,6 +157,8 @@ exports.TimeoutError = TimeoutError;
/** /**
* Thrown when a unique constraint is violated in the database * Thrown when a unique constraint is violated in the database
*
* @extends ValidationError
*/ */
class UniqueConstraintError extends ValidationError { class UniqueConstraintError extends ValidationError {
constructor(options) { constructor(options) {
...@@ -166,6 +181,8 @@ exports.UniqueConstraintError = UniqueConstraintError; ...@@ -166,6 +181,8 @@ exports.UniqueConstraintError = UniqueConstraintError;
/** /**
* Thrown when a foreign key constraint is violated in the database * Thrown when a foreign key constraint is violated in the database
*
* @extends DatabaseError
*/ */
class ForeignKeyConstraintError extends DatabaseError { class ForeignKeyConstraintError extends DatabaseError {
constructor(options) { constructor(options) {
...@@ -188,6 +205,8 @@ exports.ForeignKeyConstraintError = ForeignKeyConstraintError; ...@@ -188,6 +205,8 @@ exports.ForeignKeyConstraintError = ForeignKeyConstraintError;
/** /**
* Thrown when an exclusion constraint is violated in the database * Thrown when an exclusion constraint is violated in the database
*
* @extends DatabaseError
*/ */
class ExclusionConstraintError extends DatabaseError { class ExclusionConstraintError extends DatabaseError {
constructor(options) { constructor(options) {
...@@ -208,6 +227,8 @@ exports.ExclusionConstraintError = ExclusionConstraintError; ...@@ -208,6 +227,8 @@ exports.ExclusionConstraintError = ExclusionConstraintError;
/** /**
* Thrown when constraint name is not found in the database * Thrown when constraint name is not found in the database
*
* @extends DatabaseError
*/ */
class UnknownConstraintError extends DatabaseError { class UnknownConstraintError extends DatabaseError {
constructor(options) { constructor(options) {
...@@ -229,43 +250,46 @@ exports.UnknownConstraintError = UnknownConstraintError; ...@@ -229,43 +250,46 @@ exports.UnknownConstraintError = UnknownConstraintError;
/** /**
* Validation Error Item * Validation Error Item
* Instances of this class are included in the `ValidationError.errors` property. * Instances of this class are included in the `ValidationError.errors` property.
*
* @param {String} message An error message
* @param {String} type The type/origin of the validation error
* @param {String} path The field that triggered the validation error
* @param {String} value The value that generated the error
* @param {Object} [inst] the DAO instance that caused the validation error
* @param {Object} [validatorKey] a validation "key", used for identification
* @param {String} [fnName] property name of the BUILT-IN validator function that caused the validation error (e.g. "in" or "len"), if applicable
* @param {String} [fnArgs] parameters used with the BUILT-IN validator function, if applicable
*/ */
class ValidationErrorItem { class ValidationErrorItem {
/**
* Creates new validation error item
*
* @param {string} message An error message
* @param {string} type The type/origin of the validation error
* @param {string} path The field that triggered the validation error
* @param {string} value The value that generated the error
* @param {Object} [inst] the DAO instance that caused the validation error
* @param {Object} [validatorKey] a validation "key", used for identification
* @param {string} [fnName] property name of the BUILT-IN validator function that caused the validation error (e.g. "in" or "len"), if applicable
* @param {string} [fnArgs] parameters used with the BUILT-IN validator function, if applicable
*/
constructor(message, type, path, value, inst, validatorKey, fnName, fnArgs) { constructor(message, type, path, value, inst, validatorKey, fnName, fnArgs) {
/** /**
* An error message * An error message
* *
* @type {String} message * @type {string} message
*/ */
this.message = message || ''; this.message = message || '';
/** /**
* The type/origin of the validation error * The type/origin of the validation error
* *
* @type {String} * @type {string}
*/ */
this.type = null; this.type = null;
/** /**
* The field that triggered the validation error * The field that triggered the validation error
* *
* @type {String} * @type {string}
*/ */
this.path = path || null; this.path = path || null;
/** /**
* The value that generated the error * The value that generated the error
* *
* @type {String} * @type {string}
*/ */
this.value = value !== undefined ? value : null; this.value = value !== undefined ? value : null;
...@@ -281,21 +305,21 @@ class ValidationErrorItem { ...@@ -281,21 +305,21 @@ class ValidationErrorItem {
/** /**
* A validation "key", used for identification * A validation "key", used for identification
* *
* @type {String} * @type {string}
*/ */
this.validatorKey = validatorKey || null; this.validatorKey = validatorKey || null;
/** /**
* Property name of the BUILT-IN validator function that caused the validation error (e.g. "in" or "len"), if applicable * Property name of the BUILT-IN validator function that caused the validation error (e.g. "in" or "len"), if applicable
* *
* @type {String} * @type {string}
*/ */
this.validatorName = fnName || null; this.validatorName = fnName || null;
/** /**
* Parameters used with the BUILT-IN validator function, if applicable * Parameters used with the BUILT-IN validator function, if applicable
* *
* @type {String} * @type {string}
*/ */
this.validatorArgs = fnArgs || []; this.validatorArgs = fnArgs || [];
...@@ -321,12 +345,12 @@ class ValidationErrorItem { ...@@ -321,12 +345,12 @@ class ValidationErrorItem {
* *
* Note: the string will be empty if the instance has neither a valid `validatorKey` property nor a valid `validatorName` property * Note: the string will be empty if the instance has neither a valid `validatorKey` property nor a valid `validatorName` property
* *
* @param {Boolean} [useTypeAsNS=true] controls whether the returned value is "namespace", * @param {boolean} [useTypeAsNS=true] controls whether the returned value is "namespace",
* this parameter is ignored if the validator's `type` is not one of ValidationErrorItem.Origins * this parameter is ignored if the validator's `type` is not one of ValidationErrorItem.Origins
* @param {String} [NSSeparator='.'] a separator string for concatenating the namespace, must be not be empty, * @param {string} [NSSeparator='.'] a separator string for concatenating the namespace, must be not be empty,
* defaults to "." (fullstop). only used and validated if useTypeAsNS is TRUE. * defaults to "." (fullstop). only used and validated if useTypeAsNS is TRUE.
* @throws {Error} thrown if NSSeparator is found to be invalid. * @throws {Error} thrown if NSSeparator is found to be invalid.
* @return {String} * @returns {string}
* *
* @private * @private
*/ */
...@@ -356,9 +380,9 @@ exports.ValidationErrorItem = ValidationErrorItem; ...@@ -356,9 +380,9 @@ exports.ValidationErrorItem = ValidationErrorItem;
* An enum that defines valid ValidationErrorItem `origin` values * An enum that defines valid ValidationErrorItem `origin` values
* *
* @type {Object} * @type {Object}
* @property CORE {String} specifies errors that originate from the sequelize "core" * @property CORE {string} specifies errors that originate from the sequelize "core"
* @property DB {String} specifies validation errors that originate from the storage engine * @property DB {string} specifies validation errors that originate from the storage engine
* @property FUNCTION {String} specifies validation errors that originate from validator functions (both built-in and custom) defined for a given attribute * @property FUNCTION {string} specifies validation errors that originate from validator functions (both built-in and custom) defined for a given attribute
*/ */
ValidationErrorItem.Origins = { ValidationErrorItem.Origins = {
CORE: 'CORE', CORE: 'CORE',
...@@ -382,6 +406,8 @@ ValidationErrorItem.TypeStringMap = { ...@@ -382,6 +406,8 @@ ValidationErrorItem.TypeStringMap = {
/** /**
* A base class for all connection related errors. * A base class for all connection related errors.
*
* @extends BaseError
*/ */
class ConnectionError extends BaseError { class ConnectionError extends BaseError {
constructor(parent) { constructor(parent) {
...@@ -400,6 +426,8 @@ exports.ConnectionError = ConnectionError; ...@@ -400,6 +426,8 @@ exports.ConnectionError = ConnectionError;
/** /**
* Thrown when a connection to a database is refused * Thrown when a connection to a database is refused
*
* @extends ConnectionError
*/ */
class ConnectionRefusedError extends ConnectionError { class ConnectionRefusedError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -412,6 +440,8 @@ exports.ConnectionRefusedError = ConnectionRefusedError; ...@@ -412,6 +440,8 @@ exports.ConnectionRefusedError = ConnectionRefusedError;
/** /**
* Thrown when a connection to a database is refused due to insufficient privileges * Thrown when a connection to a database is refused due to insufficient privileges
*
* @extends ConnectionError
*/ */
class AccessDeniedError extends ConnectionError { class AccessDeniedError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -424,6 +454,8 @@ exports.AccessDeniedError = AccessDeniedError; ...@@ -424,6 +454,8 @@ exports.AccessDeniedError = AccessDeniedError;
/** /**
* Thrown when a connection to a database has a hostname that was not found * Thrown when a connection to a database has a hostname that was not found
*
* @extends ConnectionError
*/ */
class HostNotFoundError extends ConnectionError { class HostNotFoundError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -436,6 +468,8 @@ exports.HostNotFoundError = HostNotFoundError; ...@@ -436,6 +468,8 @@ exports.HostNotFoundError = HostNotFoundError;
/** /**
* Thrown when a connection to a database has a hostname that was not reachable * Thrown when a connection to a database has a hostname that was not reachable
*
* @extends ConnectionError
*/ */
class HostNotReachableError extends ConnectionError { class HostNotReachableError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -448,6 +482,8 @@ exports.HostNotReachableError = HostNotReachableError; ...@@ -448,6 +482,8 @@ exports.HostNotReachableError = HostNotReachableError;
/** /**
* Thrown when a connection to a database has invalid values for any of the connection parameters * Thrown when a connection to a database has invalid values for any of the connection parameters
*
* @extends ConnectionError
*/ */
class InvalidConnectionError extends ConnectionError { class InvalidConnectionError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -460,6 +496,8 @@ exports.InvalidConnectionError = InvalidConnectionError; ...@@ -460,6 +496,8 @@ exports.InvalidConnectionError = InvalidConnectionError;
/** /**
* Thrown when a connection to a database times out * Thrown when a connection to a database times out
*
* @extends ConnectionError
*/ */
class ConnectionTimedOutError extends ConnectionError { class ConnectionTimedOutError extends ConnectionError {
constructor(parent) { constructor(parent) {
...@@ -472,6 +510,8 @@ exports.ConnectionTimedOutError = ConnectionTimedOutError; ...@@ -472,6 +510,8 @@ exports.ConnectionTimedOutError = ConnectionTimedOutError;
/** /**
* Thrown when a some problem occurred with Instance methods (see message for details) * Thrown when a some problem occurred with Instance methods (see message for details)
*
* @extends BaseError
*/ */
class InstanceError extends BaseError { class InstanceError extends BaseError {
constructor(message) { constructor(message) {
...@@ -484,6 +524,8 @@ exports.InstanceError = InstanceError; ...@@ -484,6 +524,8 @@ exports.InstanceError = InstanceError;
/** /**
* Thrown when a record was not found, Usually used with rejectOnEmpty mode (see message for details) * Thrown when a record was not found, Usually used with rejectOnEmpty mode (see message for details)
*
* @extends BaseError
*/ */
class EmptyResultError extends BaseError { class EmptyResultError extends BaseError {
constructor(message) { constructor(message) {
...@@ -496,6 +538,8 @@ exports.EmptyResultError = EmptyResultError; ...@@ -496,6 +538,8 @@ exports.EmptyResultError = EmptyResultError;
/** /**
* Thrown when an include statement is improperly constructed (see message for details) * Thrown when an include statement is improperly constructed (see message for details)
*
* @extends BaseError
*/ */
class EagerLoadingError extends BaseError { class EagerLoadingError extends BaseError {
constructor(message) { constructor(message) {
...@@ -508,6 +552,8 @@ exports.EagerLoadingError = EagerLoadingError; ...@@ -508,6 +552,8 @@ exports.EagerLoadingError = EagerLoadingError;
/** /**
* Thrown when an association is improperly constructed (see message for details) * Thrown when an association is improperly constructed (see message for details)
*
* @extends BaseError
*/ */
class AssociationError extends BaseError { class AssociationError extends BaseError {
constructor(message) { constructor(message) {
...@@ -519,6 +565,8 @@ class AssociationError extends BaseError { ...@@ -519,6 +565,8 @@ class AssociationError extends BaseError {
exports.AssociationError = AssociationError; exports.AssociationError = AssociationError;
/** /**
* Thrown when a query is passed invalid options (see message for details) * Thrown when a query is passed invalid options (see message for details)
*
* @extends BaseError
*/ */
class QueryError extends BaseError { class QueryError extends BaseError {
constructor(message) { constructor(message) {
...@@ -535,6 +583,8 @@ exports.QueryError = QueryError; ...@@ -535,6 +583,8 @@ exports.QueryError = QueryError;
* *
* @param {Error} error Error for a given record/instance * @param {Error} error Error for a given record/instance
* @param {Object} record DAO instance that error belongs to * @param {Object} record DAO instance that error belongs to
*
* @extends BaseError
*/ */
class BulkRecordError extends BaseError { class BulkRecordError extends BaseError {
constructor(error, record) { constructor(error, record) {
......
lib/instance-validator.js
'use strict'; 'use strict';
const validator = require('./utils/validator-extras').validator; const _ = require('lodash');
const extendModelValidations = require('./utils/validator-extras').extendModelValidations;
const Utils = require('./utils'); const Utils = require('./utils');
const sequelizeError = require('./errors'); const sequelizeError = require('./errors');
const Promise = require('./promise'); const Promise = require('./promise');
const DataTypes = require('./data-types'); const DataTypes = require('./data-types');
const BelongsTo = require('./associations/belongs-to'); const BelongsTo = require('./associations/belongs-to');
const _ = require('lodash'); const validator = require('./utils/validator-extras').validator;
const extendModelValidations = require('./utils/validator-extras').extendModelValidations;
/** /**
* The Main Instance Validator. * Instance Validator.
* *
* @param {Instance} modelInstance The model instance. * @param {Instance} modelInstance The model instance.
* @param {Object} options A dictionary with options. * @param {Object} options A dictionary with options.
* @constructor *
* @private * @private
*/ */
class InstanceValidator { class InstanceValidator {
...@@ -61,7 +61,7 @@ class InstanceValidator { ...@@ -61,7 +61,7 @@ class InstanceValidator {
/** /**
* The main entry point for the Validation module, invoke to start the dance. * The main entry point for the Validation module, invoke to start the dance.
* *
* @return {Promise} * @returns {Promise}
* @private * @private
*/ */
_validate() { _validate() {
...@@ -86,7 +86,7 @@ class InstanceValidator { ...@@ -86,7 +86,7 @@ class InstanceValidator {
* - On validation success: After Validation Model Hooks * - On validation success: After Validation Model Hooks
* - On validation failure: Validation Failed Model Hooks * - On validation failure: Validation Failed Model Hooks
* *
* @return {Promise} * @returns {Promise}
* @private * @private
*/ */
validate() { validate() {
...@@ -100,7 +100,7 @@ class InstanceValidator { ...@@ -100,7 +100,7 @@ class InstanceValidator {
* - On validation success: After Validation Model Hooks * - On validation success: After Validation Model Hooks
* - On validation failure: Validation Failed Model Hooks * - On validation failure: Validation Failed Model Hooks
* *
* @return {Promise} * @returns {Promise}
* @private * @private
*/ */
_validateAndRunHooks() { _validateAndRunHooks() {
...@@ -118,7 +118,7 @@ class InstanceValidator { ...@@ -118,7 +118,7 @@ class InstanceValidator {
/** /**
* Will run all the built-in validators. * Will run all the built-in validators.
* *
* @return {Promise(Array.<Promise.PromiseInspection>)} A promise from .reflect(). * @returns {Promise<Array.<Promise.PromiseInspection>>} A promise from .reflect().
* @private * @private
*/ */
_builtinValidators() { _builtinValidators() {
...@@ -152,7 +152,7 @@ class InstanceValidator { ...@@ -152,7 +152,7 @@ class InstanceValidator {
/** /**
* Will run all the custom validators. * Will run all the custom validators.
* *
* @return {Promise(Array.<Promise.PromiseInspection>)} A promise from .reflect(). * @returns {Promise<Array.<Promise.PromiseInspection>>} A promise from .reflect().
* @private * @private
*/ */
_customValidators() { _customValidators() {
...@@ -176,11 +176,12 @@ class InstanceValidator { ...@@ -176,11 +176,12 @@ class InstanceValidator {
/** /**
* Validate a single attribute with all the defined built-in validators. * Validate a single attribute with all the defined built-in validators.
* *
* @private
*
* @param {*} value Anything. * @param {*} value Anything.
* @param {string} field The field name. * @param {string} field The field name.
* @return {Promise} A promise, will always resolve, *
* auto populates error on this.error local object. * @returns {Promise} A promise, will always resolve, auto populates error on this.error local object.
* @private
*/ */
_builtinAttrValidate(value, field) { _builtinAttrValidate(value, field) {
// check if value is null (if null not allowed the Schema pass will capture it) // check if value is null (if null not allowed the Schema pass will capture it)
...@@ -222,12 +223,15 @@ class InstanceValidator { ...@@ -222,12 +223,15 @@ class InstanceValidator {
/** /**
* Prepare and invoke a custom validator. * Prepare and invoke a custom validator.
* *
* @private
*
* @param {Function} validator The custom validator. * @param {Function} validator The custom validator.
* @param {string} validatorType the custom validator type (name). * @param {string} validatorType the custom validator type (name).
* @param {boolean=} optAttrDefined Set to true if custom validator was defined * @param {boolean} optAttrDefined Set to true if custom validator was defined from the attribute
* from the Attribute * @param {*} optValue value for attribute
* @return {Promise} A promise. * @param {string} optField field for attribute
* @private *
* @returns {Promise} A promise.
*/ */
_invokeCustomValidator(validator, validatorType, optAttrDefined, optValue, optField) { _invokeCustomValidator(validator, validatorType, optAttrDefined, optValue, optField) {
let validatorFunction = null; // the validation function to call let validatorFunction = null; // the validation function to call
...@@ -265,12 +269,14 @@ class InstanceValidator { ...@@ -265,12 +269,14 @@ class InstanceValidator {
/** /**
* Prepare and invoke a build-in validator. * Prepare and invoke a build-in validator.
* *
* @private
*
* @param {*} value Anything. * @param {*} value Anything.
* @param {*} test The test case. * @param {*} test The test case.
* @param {string} validatorType One of known to Sequelize validators. * @param {string} validatorType One of known to Sequelize validators.
* @param {string} field The field that is being validated * @param {string} field The field that is being validated
* @return {Object} An object with specific keys to invoke the validator. *
* @private * @returns {Object} An object with specific keys to invoke the validator.
*/ */
_invokeBuiltinValidator(value, test, validatorType, field) { _invokeBuiltinValidator(value, test, validatorType, field) {
return Promise.try(() => { return Promise.try(() => {
...@@ -295,6 +301,7 @@ class InstanceValidator { ...@@ -295,6 +301,7 @@ class InstanceValidator {
* @param {*} test The test case. * @param {*} test The test case.
* @param {string} validatorType One of known to Sequelize validators. * @param {string} validatorType One of known to Sequelize validators.
* @param {string} field The field that is being validated. * @param {string} field The field that is being validated.
*
* @private * @private
*/ */
_extractValidatorArgs(test, validatorType, field) { _extractValidatorArgs(test, validatorType, field) {
...@@ -321,6 +328,7 @@ class InstanceValidator { ...@@ -321,6 +328,7 @@ class InstanceValidator {
* @param {Object} rawAttribute As defined in the Schema. * @param {Object} rawAttribute As defined in the Schema.
* @param {string} field The field name. * @param {string} field The field name.
* @param {*} value anything. * @param {*} value anything.
*
* @private * @private
*/ */
_validateSchema(rawAttribute, field, value) { _validateSchema(rawAttribute, field, value) {
...@@ -363,7 +371,8 @@ class InstanceValidator { ...@@ -363,7 +371,8 @@ class InstanceValidator {
* *
* @param {string} field The attribute name. * @param {string} field The attribute name.
* @param {string|number} value The data value. * @param {string|number} value The data value.
* @param {Array.<Promise.PromiseInspection>} Promise inspection objects. * @param {Array<Promise.PromiseInspection>} promiseInspections objects.
*
* @private * @private
*/ */
_handleReflectedResult(field, value, promiseInspections) { _handleReflectedResult(field, value, promiseInspections) {
...@@ -380,11 +389,11 @@ class InstanceValidator { ...@@ -380,11 +389,11 @@ class InstanceValidator {
/** /**
* Signs all errors retaining the original. * Signs all errors retaining the original.
* *
* @param {Boolean} isBuiltin - Determines if error is from builtin validator. * @param {boolean} isBuiltin - Determines if error is from builtin validator.
* @param {String} errorKey - name of invalid attribute. * @param {string} errorKey - name of invalid attribute.
* @param {Error|String} rawError - The original error. * @param {Error|string} rawError - The original error.
* @param {String|Number} value - The data that triggered the error. * @param {string|number} value - The data that triggered the error.
* @param {String} fnName - Name of the validator, if any * @param {string} fnName - Name of the validator, if any
* @param {Array} fnArgs - Arguments for the validator [function], if any * @param {Array} fnArgs - Arguments for the validator [function], if any
* *
* @private * @private
......
lib/model-manager.js
...@@ -37,9 +37,11 @@ class ModelManager { ...@@ -37,9 +37,11 @@ class ModelManager {
} }
/** /**
* Iterate over Models in an order suitable for e.g. creating tables. Will * Iterate over Models in an order suitable for e.g. creating tables.
* take foreign key constraints into account so that dependencies are visited * Will take foreign key constraints into account so that dependencies are visited before dependents.
* before dependents. *
* @param {Function} iterator method to execute on each model
* @param {Object} [options] iterator options
* @private * @private
*/ */
forEachModel(iterator, options) { forEachModel(iterator, options) {
......
lib/model.js
This diff could not be displayed because it is too large.
lib/transaction.js
...@@ -4,20 +4,23 @@ const _ = require('lodash'); ...@@ -4,20 +4,23 @@ const _ = require('lodash');
const Promise = require('./promise'); const Promise = require('./promise');
/** /**
* The transaction object is used to identify a running transaction. It is created by calling `Sequelize.transaction()`. * The transaction object is used to identify a running transaction.
* * It is created by calling `Sequelize.transaction()`.
* To run a query under a transaction, you should pass the transaction in the options object. * To run a query under a transaction, you should pass the transaction in the options object.
* *
* @class Transaction
* @see {@link Sequelize.transaction} * @see {@link Sequelize.transaction}
*/ */
class Transaction { class Transaction {
/** /**
* Creates a new transaction instance
*
* @param {Sequelize} sequelize A configured sequelize Instance * @param {Sequelize} sequelize A configured sequelize Instance
* @param {Object} options An object with options * @param {Object} options An object with options
* @param {Boolean} options.autocommit Sets the autocommit property of the transaction. * @param {boolean} options.autocommit Sets the autocommit property of the transaction.
* @param {String} options.type=true Sets the type of the transaction. * @param {string} options.type=true Sets the type of the transaction.
* @param {String} options.isolationLevel=true Sets the isolation level of the transaction. * @param {string} options.isolationLevel=true Sets the isolation level of the transaction.
* @param {String} options.deferrable Sets the constraints to be deferred or immediately checked. * @param {string} options.deferrable Sets the constraints to be deferred or immediately checked.
*/ */
constructor(sequelize, options) { constructor(sequelize, options) {
this.sequelize = sequelize; this.sequelize = sequelize;
...@@ -52,10 +55,9 @@ class Transaction { ...@@ -52,10 +55,9 @@ class Transaction {
/** /**
* Commit the transaction * Commit the transaction
* *
* @return {Promise} * @returns {Promise}
*/ */
commit() { commit() {
if (this.finished) { if (this.finished) {
return Promise.reject(new Error('Transaction cannot be committed because it has been finished with state: ' + this.finished)); return Promise.reject(new Error('Transaction cannot be committed because it has been finished with state: ' + this.finished));
} }
...@@ -82,10 +84,9 @@ class Transaction { ...@@ -82,10 +84,9 @@ class Transaction {
/** /**
* Rollback (abort) the transaction * Rollback (abort) the transaction
* *
* @return {Promise} * @returns {Promise}
*/ */
rollback() { rollback() {
if (this.finished) { if (this.finished) {
return Promise.reject(new Error('Transaction cannot be rolled back because it has been finished with state: ' + this.finished)); return Promise.reject(new Error('Transaction cannot be rolled back because it has been finished with state: ' + this.finished));
} }
...@@ -190,11 +191,12 @@ class Transaction { ...@@ -190,11 +191,12 @@ class Transaction {
} }
/** /**
* A hook that is run after a transaction is committed * A hook that is run after a transaction is committed
* @param {Function} fn A callback function that is called with the committed transaction *
* @name afterCommit * @param {Function} fn A callback function that is called with the committed transaction
* @memberOf Sequelize.Transaction * @name afterCommit
*/ * @memberof Sequelize.Transaction
*/
afterCommit(fn) { afterCommit(fn) {
if (!fn || typeof fn !== 'function') { if (!fn || typeof fn !== 'function') {
throw new Error('"fn" must be a function'); throw new Error('"fn" must be a function');
...@@ -209,17 +211,15 @@ class Transaction { ...@@ -209,17 +211,15 @@ class Transaction {
* *
* Pass in the desired level as the first argument: * Pass in the desired level as the first argument:
* *
* ```js * @example
* return sequelize.transaction({type: Sequelize.Transaction.TYPES.EXCLUSIVE}, transaction => { * return sequelize.transaction({type: Sequelize.Transaction.TYPES.EXCLUSIVE}, transaction => {
* * // your transactions
* // your transactions
*
* }).then(result => { * }).then(result => {
* // transaction has been committed. Do something after the commit if required. * // transaction has been committed. Do something after the commit if required.
* }).catch(err => { * }).catch(err => {
* // do something with the err. * // do something with the err.
* }); * });
* ``` *
* @property DEFERRED * @property DEFERRED
* @property IMMEDIATE * @property IMMEDIATE
* @property EXCLUSIVE * @property EXCLUSIVE
...@@ -233,22 +233,20 @@ class Transaction { ...@@ -233,22 +233,20 @@ class Transaction {
} }
/** /**
* Isolations levels can be set per-transaction by passing `options.isolationLevel` to `sequelize.transaction`. * Isolation levels can be set per-transaction by passing `options.isolationLevel` to `sequelize.transaction`.
* Default to `REPEATABLE_READ` but you can override the default isolation level by passing `options.isolationLevel` in `new Sequelize`. * Default to `REPEATABLE_READ` but you can override the default isolation level by passing `options.isolationLevel` in `new Sequelize`.
* *
* Pass in the desired level as the first argument: * Pass in the desired level as the first argument:
* *
* ```js * @example
* return sequelize.transaction({isolationLevel: Sequelize.Transaction.ISOLATION_LEVELS.SERIALIZABLE}, transaction => { * return sequelize.transaction({isolationLevel: Sequelize.Transaction.ISOLATION_LEVELS.SERIALIZABLE}, transaction => {
* * // your transactions
* // your transactions * }).then(result => {
* * // transaction has been committed. Do something after the commit if required.
* }).then(result => { * }).catch(err => {
* // transaction has been committed. Do something after the commit if required. * // do something with the err.
* }).catch(err => { * });
* // do something with the err. *
* });
* ```
* @property READ_UNCOMMITTED * @property READ_UNCOMMITTED
* @property READ_COMMITTED * @property READ_COMMITTED
* @property REPEATABLE_READ * @property REPEATABLE_READ
...@@ -267,17 +265,15 @@ class Transaction { ...@@ -267,17 +265,15 @@ class Transaction {
/** /**
* Possible options for row locking. Used in conjunction with `find` calls: * Possible options for row locking. Used in conjunction with `find` calls:
* *
* ```js * @example
* t1 // is a transaction * // t1 is a transaction
* Model.findAll({ * Model.findAll({
* where: ..., * where: ...,
* transaction: t1, * transaction: t1,
* lock: t1.LOCK... * lock: t1.LOCK...
* }); * });
* ```
* *
* Postgres also supports specific locks while eager loading by using OF: * @example <caption>Postgres also supports specific locks while eager loading by using OF:</caption>
* ```js
* UserModel.findAll({ * UserModel.findAll({
* where: ..., * where: ...,
* include: [TaskModel, ...], * include: [TaskModel, ...],
...@@ -287,23 +283,20 @@ class Transaction { ...@@ -287,23 +283,20 @@ class Transaction {
* of: UserModel * of: UserModel
* } * }
* }); * });
* ```
* UserModel will be locked but TaskModel won't!
* *
* You can also skip locked rows: * # UserModel will be locked but TaskModel won't!
* *
*```js * @example <caption>You can also skip locked rows:</caption>
* t1 // is a transaction * // t1 is a transaction
* Model.findAll({ * Model.findAll({
* where: ..., * where: ...,
* transaction: t1, * transaction: t1,
* lock: true, * lock: true,
* skipLocked: true * skipLocked: true
* }); * });
* ``` * # The query will now return any rows that aren't locked by another transaction
* The query will now return any rows that aren't locked by another transaction
* *
* @return {Object} * @returns {Object}
* @property UPDATE * @property UPDATE
* @property SHARE * @property SHARE
* @property KEY_SHARE Postgres 9.3+ only * @property KEY_SHARE Postgres 9.3+ only
...@@ -319,7 +312,7 @@ class Transaction { ...@@ -319,7 +312,7 @@ class Transaction {
} }
/** /**
* @see {@link Transaction.LOCK} * Please {@link Transaction.LOCK}
*/ */
get LOCK() { get LOCK() {
return Transaction.LOCK; return Transaction.LOCK;
......
lib/utils.js
...@@ -278,7 +278,7 @@ exports.toDefaultValue = toDefaultValue; ...@@ -278,7 +278,7 @@ exports.toDefaultValue = toDefaultValue;
* in a db schema using the DEFAULT directive. * in a db schema using the DEFAULT directive.
* *
* @param {*} value Any default value. * @param {*} value Any default value.
* @return {boolean} yes / no. * @returns {boolean} yes / no.
* @private * @private
*/ */
function defaultValueSchemable(value) { function defaultValueSchemable(value) {
...@@ -394,7 +394,7 @@ exports.removeTicks = removeTicks; ...@@ -394,7 +394,7 @@ exports.removeTicks = removeTicks;
* } * }
* *
* @param value, an Object * @param value, an Object
* @return Object, an flattened object * @returns Object, an flattened object
* @private * @private
*/ */
function flattenObjectDeep(value) { function flattenObjectDeep(value) {
...@@ -501,7 +501,7 @@ exports.Where = Where; ...@@ -501,7 +501,7 @@ exports.Where = Where;
/** /**
* getOperators * getOperators
* @param {Object} obj * @param {Object} obj
* @return {Array<Symbol>} All operators properties of obj * @returns {Array<Symbol>} All operators properties of obj
* @private * @private
*/ */
function getOperators(obj) { function getOperators(obj) {
...@@ -512,7 +512,7 @@ exports.getOperators = getOperators; ...@@ -512,7 +512,7 @@ exports.getOperators = getOperators;
/** /**
* getComplexKeys * getComplexKeys
* @param {Object} obj * @param {Object} obj
* @return {Array<String|Symbol>} All keys including operators * @returns {Array<String|Symbol>} All keys including operators
* @private * @private
*/ */
function getComplexKeys(obj) { function getComplexKeys(obj) {
...@@ -523,7 +523,7 @@ exports.getComplexKeys = getComplexKeys; ...@@ -523,7 +523,7 @@ exports.getComplexKeys = getComplexKeys;
/** /**
* getComplexSize * getComplexSize
* @param {Object|Array} obj * @param {Object|Array} obj
* @return {Integer} Length of object properties including operators if obj is array returns its length * @returns {Integer} Length of object properties including operators if obj is array returns its length
* @private * @private
*/ */
function getComplexSize(obj) { function getComplexSize(obj) {
...@@ -535,7 +535,7 @@ exports.getComplexSize = getComplexSize; ...@@ -535,7 +535,7 @@ exports.getComplexSize = getComplexSize;
* Returns true if a where clause is empty, even with Symbols * Returns true if a where clause is empty, even with Symbols
* *
* @param {Object} obj * @param {Object} obj
* @return {Boolean} * @returns {boolean}
* @private * @private
*/ */
function isWhereEmpty(obj) { function isWhereEmpty(obj) {
...@@ -546,9 +546,9 @@ exports.isWhereEmpty = isWhereEmpty; ...@@ -546,9 +546,9 @@ exports.isWhereEmpty = isWhereEmpty;
/** /**
* Returns ENUM name by joining table and column name * Returns ENUM name by joining table and column name
* *
* @param {String} tableName * @param {string} tableName
* @param {String} columnName * @param {string} columnName
* @return {String} * @returns {string}
* @private * @private
*/ */
function generateEnumName(tableName, columnName) { function generateEnumName(tableName, columnName) {
...@@ -559,7 +559,7 @@ exports.generateEnumName = generateEnumName; ...@@ -559,7 +559,7 @@ exports.generateEnumName = generateEnumName;
/** /**
* Returns an new Object which keys are camelized * Returns an new Object which keys are camelized
* @param {Object} obj * @param {Object} obj
* @return {String} * @returns {string}
* @private * @private
*/ */
function camelizeObjectKeys(obj) { function camelizeObjectKeys(obj) {
...@@ -624,7 +624,7 @@ exports.classToInvokable = classToInvokable; ...@@ -624,7 +624,7 @@ exports.classToInvokable = classToInvokable;
* *
* @param {Object} index * @param {Object} index
* @param {Array} index.fields * @param {Array} index.fields
* @param {String} [index.name] * @param {string} [index.name]
* @param {String|Object} tableName * @param {String|Object} tableName
* *
* @returns {Object} * @returns {Object}
......
lib/utils/inherits.js
...@@ -4,7 +4,12 @@ const util = require('util'); ...@@ -4,7 +4,12 @@ const util = require('util');
const _ = require('lodash'); const _ = require('lodash');
/** /**
* like util.inherits, but also copies over static properties * like util.inherits, but also copies over static properties. Inherit child constructor
* to have properties from super constructor
*
* @param {Function} constructor the child constructor
* @param {Function} superConstructor the super constructor
*
* @private * @private
*/ */
function inherits(constructor, superConstructor) { function inherits(constructor, superConstructor) {
......
package.json
...@@ -47,13 +47,16 @@ ...@@ -47,13 +47,16 @@
"continuation-local-storage": "^3.x", "continuation-local-storage": "^3.x",
"cross-env": "^5.2.0", "cross-env": "^5.2.0",
"cz-conventional-changelog": "^2.x", "cz-conventional-changelog": "^2.x",
"docdash": "^0.4.0",
"env-cmd": "^8.0.0", "env-cmd": "^8.0.0",
"esdoc": "^0.5.2", "esdoc": "^0.5.2",
"eslint": "^5.0.0", "eslint": "^5.0.0",
"eslint-plugin-jsdoc": "^3.7.1",
"eslint-plugin-mocha": "^5.0.0", "eslint-plugin-mocha": "^5.0.0",
"hints": "^1.x", "hints": "^1.x",
"husky": "^0.x", "husky": "^0.x",
"istanbul": "^0.x", "istanbul": "^0.x",
"jsdoc": "^3.5.5",
"lcov-result-merger": "^3.0.0", "lcov-result-merger": "^3.0.0",
"mocha": "^5.x", "mocha": "^5.x",
"mysql2": "^1.x", "mysql2": "^1.x",
...@@ -91,6 +94,7 @@ ...@@ -91,6 +94,7 @@
"test-docker-unit": "npm run test-unit", "test-docker-unit": "npm run test-unit",
"test-docker-integration": "env-cmd $npm_package_options_env_cmd npm run test-integration", "test-docker-integration": "env-cmd $npm_package_options_env_cmd npm run test-integration",
"docs": "esdoc && cp docs/ROUTER esdoc/ROUTER", "docs": "esdoc && cp docs/ROUTER esdoc/ROUTER",
"generate-jsdocs": "node_modules/.bin/jsdoc -c jsdoc.json",
"teaser": "node -e \"console.log('#'.repeat(process.env.DIALECT.length + 22) + '\\n# Running tests for ' + process.env.DIALECT + ' #\\n' + '#'.repeat(process.env.DIALECT.length + 22))\"", "teaser": "node -e \"console.log('#'.repeat(process.env.DIALECT.length + 22) + '\\n# Running tests for ' + process.env.DIALECT + ' #\\n' + '#'.repeat(process.env.DIALECT.length + 22))\"",
"test-unit": "mocha --require scripts/mocha-bootload --globals setImmediate,clearImmediate --ui tdd --exit --check-leaks --colors -t 30000 --reporter spec \"test/unit/**/*.js\"", "test-unit": "mocha --require scripts/mocha-bootload --globals setImmediate,clearImmediate --ui tdd --exit --check-leaks --colors -t 30000 --reporter spec \"test/unit/**/*.js\"",
"test-unit-mysql": "cross-env DIALECT=mysql npm run test-unit", "test-unit-mysql": "cross-env DIALECT=mysql npm run test-unit",
......
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!