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 425 additions and 268 deletions
.eslintrc.json
......@@ -3,6 +3,22 @@
"mocha/no-exclusive-tests": "error",
"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",
"comma-spacing": "error",
"key-spacing": "error",
......@@ -90,11 +106,25 @@
"sourceType": "script"
},
"plugins": [
"mocha"
"mocha",
"jsdoc"
],
"env": {
"node": true,
"mocha": 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
*.swp
.idea
.DS_STORE
node_modules
npm-debug.log
*~
test/binary/tmp/*
test/tmp/*
test/dialects/sqlite/test.sqlite
test/sqlite/test.sqlite
coverage-*
site
docs/api/tmp.md
ssce.js
sscce.js
coverage
.vscode/
*.sublime*
esdoc
package-lock.json
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 {
/**
* 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) {
if (!Array.isArray(input)) {
......
lib/associations/belongs-to-many.js
......@@ -357,12 +357,15 @@ class BelongsToMany extends Association {
/**
* Get everything currently associated with this, using an optional where clause.
*
* @param {Object} [options]
* @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} [options.schema] Apply a schema on the related model
* @see {@link Model.findAll} for a full explanation of options
* @return {Promise<Array<Model>>}
*
* @param {<Model>} instance instance
* @param {Object} [options] find options
* @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} [options.schema] Apply a schema on the related model
*
* @returns {Promise<Array<<Model>>>}
*/
get(instance, options) {
options = Utils.cloneDeep(options) || {};
......@@ -426,10 +429,12 @@ class BelongsToMany extends Association {
/**
* 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 {String|Boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
* @return {Promise<Integer>}
* @param {string|boolean} [options.scope] Apply a scope on the related model, or remove its default scope by passing false
*
* @returns {Promise<number>}
*/
count(instance, options) {
const association = this;
......@@ -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
*
* @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
* @return {Promise<boolean>}
*
* @returns {Promise<boolean>}
*/
has(sourceInstance, instances, options) {
const association = this;
......@@ -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.validate] Run validation for the join model
* @param {Object} [options.through] Additional attributes for the join table.
* @return {Promise}
*
* @returns {Promise}
*/
set(sourceInstance, newAssociatedObjects, options) {
options = options || {};
......@@ -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.validate] Run validation for the join model.
* @param {Object} [options.through] Additional attributes for the join table.
* @return {Promise}
*
* @returns {Promise}
*/
add(sourceInstance, newInstances, options) {
// If newInstances is null or undefined, no-op
......@@ -684,9 +697,11 @@ class BelongsToMany extends Association {
/**
* 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`
* @return {Promise}
*
* @returns {Promise}
*/
remove(sourceInstance, oldAssociatedObjects, options) {
const association = this;
......@@ -705,10 +720,12 @@ class BelongsToMany extends Association {
/**
* 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.through] Additional attributes for the join table
* @return {Promise}
*
* @returns {Promise}
*/
create(sourceInstance, values, options) {
const association = this;
......
lib/associations/belongs-to.js
......@@ -113,13 +113,14 @@ class BelongsTo extends Association {
/**
* Get the associated instance.
*
* @param {Object} [options]
* @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 {<Model>|Array<Model>} instances source instances
* @param {Object} [options] find options
* @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
*
* @return {Promise<Model>}
* @returns {Promise<<Model>>}
*/
get(instances, options) {
const where = {};
......@@ -183,11 +184,12 @@ class BelongsTo extends Association {
/**
* 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 {Object} [options] Options passed to `this.save`
* @param {Boolean} [options.save=true] Skip saving this after setting the foreign key if false.
* @param {<Model>} sourceInstance the source instance
* @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 `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 = {}) {
let value = associatedInstance;
......@@ -213,12 +215,13 @@ class BelongsTo extends Association {
/**
* Create a new instance of the associated model and associate it with this.
*
* @param {Object} [values]
* @param {Object} [options] Options passed to `target.create` and setAssociation.
* @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.
*
* @see {@link Model#create} for a full explanation of options
*
* @return {Promise}
* @returns {Promise}
*/
create(sourceInstance, values, options) {
values = values || {};
......
lib/associations/has-many.js
......@@ -157,12 +157,15 @@ class HasMany extends Association {
/**
* 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 {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|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.findAll} for a full explanation of options
* @return {Promise<Array<Model>>}
*
* @returns {Promise<Array<<Model>>>}
*/
get(instances, options = {}) {
const where = {};
......@@ -238,11 +241,12 @@ class HasMany extends Association {
/**
* 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 {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) {
options = Utils.cloneDeep(options);
......@@ -265,10 +269,11 @@ class HasMany extends Association {
/**
* 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
*
* @return {Promise}
* @returns {Promise}
*/
has(sourceInstance, targetInstances, options) {
const where = {};
......@@ -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
*
* @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.validate] Run validation for the join model
* @return {Promise}
*
* @returns {Promise}
*/
set(sourceInstance, targetInstances, options) {
if (targetInstances === null) {
......@@ -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,
* 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`.
* @return {Promise}
*
* @returns {Promise}
*/
add(sourceInstance, targetInstances, options = {}) {
if (!targetInstances) return Utils.Promise.resolve();
......@@ -402,9 +411,11 @@ class HasMany extends Association {
/**
* 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`
* @return {Promise}
*
* @returns {Promise}
*/
remove(sourceInstance, targetInstances, options = {}) {
const update = {};
......@@ -425,9 +436,11 @@ class HasMany extends Association {
/**
* Create a new instance of the associated model and associate it with this.
*
* @param {Object} [values]
* @param {Object} [options] Options passed to `target.create`.
* @return {Promise}
* @param {<Model>} sourceInstance source instance
* @param {Object} [values] values for target model instance
* @param {Object} [options] Options passed to `target.create`
*
* @returns {Promise}
*/
create(sourceInstance, values, options = {}) {
if (Array.isArray(options)) {
......
lib/associations/has-one.js
......@@ -112,11 +112,14 @@ class HasOne extends Association {
/**
* Get the associated instance.
*
* @param {Object} [options]
* @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 {<Model>|Array<Model>} instances source instances
* @param {Object} [options] find options
* @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
* @return {Promise<Model>}
*
* @returns {Promise<Model>}
*/
get(instances, options) {
const where = {};
......@@ -180,10 +183,11 @@ class HasOne extends Association {
/**
* 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 {?<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) {
let alreadyAssociated;
......@@ -229,12 +233,13 @@ class HasOne extends Association {
/**
* 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.
*
* @see {@link Model#create} for a full explanation of options
*
* @return {Promise}
* @returns {Promise}
*/
create(sourceInstance, values, options) {
values = values || {};
......
lib/associations/helpers.js
......@@ -45,10 +45,12 @@ exports.addForeignKeyConstraints = addForeignKeyConstraints;
* Mixin (inject) association methods to model prototype
*
* @private
* @param {Object} Association instance
* @param {Object} Model prototype
* @param {Array} Method names to inject
* @param {Object} Mapping between model and association method names
*
* @param {Object} association instance
* @param {Object} obj Model prototype
* @param {Array} methods Method names to inject
* @param {Object} aliases Mapping between model and association method names
*
*/
function mixinMethods(association, obj, methods, aliases) {
aliases = aliases || {};
......
lib/dialects/abstract/connection-manager.js
......@@ -62,7 +62,7 @@ class ConnectionManager {
* Handler which executes on process exit or connection manager shutdown
*
* @private
* @return {Promise}
* @returns {Promise}
*/
_onProcessExit() {
if (!this.pool) {
......@@ -78,7 +78,7 @@ class ConnectionManager {
/**
* Drain the pool and close it permanently
*
* @return {Promise}
* @returns {Promise}
*/
close() {
// Mark close of pool
......@@ -234,10 +234,10 @@ class ConnectionManager {
*
* @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 {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 {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
*
* @return {Promise<Connection>}
* @returns {Promise<Connection>}
*/
getConnection(options) {
options = options || {};
......@@ -282,7 +282,7 @@ class ConnectionManager {
*
* @param {Connection} connection
*
* @return {Promise}
* @returns {Promise}
*/
releaseConnection(connection) {
return this.pool.release(connection)
......@@ -296,7 +296,7 @@ class ConnectionManager {
*
* @param {Object|Error} mayBeConnection Object which can be either connection or error
*
* @return {Promise<Connection>}
* @returns {Promise<Connection>}
*/
_determineConnection(mayBeConnection) {
if (mayBeConnection instanceof Error) {
......@@ -313,7 +313,7 @@ class ConnectionManager {
*
* @param {*} config Connection config
* @private
* @return {Promise<Connection>}
* @returns {Promise<Connection>}
*/
_connect(config) {
return this.sequelize.runHooks('beforeConnect', config)
......@@ -326,7 +326,7 @@ class ConnectionManager {
*
* @param {Connection} connection
* @private
* @return {Promise}
* @returns {Promise}
*/
_disconnect(connection) {
return this.dialect.connectionManager.disconnect(connection);
......@@ -337,7 +337,7 @@ class ConnectionManager {
*
* @param {Connection} connection
*
* @return {Boolean}
* @returns {boolean}
*/
_validate(connection) {
if (!this.dialect.connectionManager.validate) {
......
lib/dialects/abstract/query-generator.js
......@@ -95,7 +95,7 @@ class QueryGenerator {
/**
* Returns an insert into command
*
* @param {String} table
* @param {string} table
* @param {Object} valueHash attribute value pairs
* @param {Object} modelAttributes
* @param {Object} [options]
......@@ -262,7 +262,7 @@ class QueryGenerator {
/**
* Returns an insert into command for multiple values.
*
* @param {String} tableName
* @param {string} tableName
* @param {Object} fieldValueHashes
* @param {Object} options
* @param {Object} fieldMappedAttributes
......@@ -330,7 +330,7 @@ class QueryGenerator {
/**
* Returns an update query
*
* @param {String} tableName
* @param {string} tableName
* @param {Object} attrValueHash
* @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.
......@@ -452,8 +452,8 @@ class QueryGenerator {
/**
* Returns an update query using arithmetic operator
*
* @param {String} operator String with the arithmetic operator (e.g. '+' or '-')
* @param {String} tableName Name of the table
* @param {string} operator String with the arithmetic operator (e.g. '+' or '-')
* @param {string} tableName Name of the table
* @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
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 {
/**
* Split a list of identifiers by "." and quote each part
*
* @param {String} dialect Dialect name
* @param {String} identifiers
* @param {string} dialect Dialect name
* @param {string} identifiers
* @param {Object} [options]
* @param {Boolean} [options.force=false]
* @param {Boolean} [options.quoteIdentifiers=true]
* @param {boolean} [options.force=false]
* @param {boolean} [options.quoteIdentifiers=true]
*
* @returns {String}
* @returns {string}
*/
quoteIdentifier(identifier, force) {
return QuoteHelper.quoteIdentifier(this.dialect, identifier, {
......@@ -929,7 +929,7 @@ class QueryGenerator {
* @param {String|Object} param table string or object
* @param {String|Boolean} alias alias name
*
* @returns {String}
* @returns {string}
*/
quoteTable(param, alias) {
let table = '';
......@@ -1065,9 +1065,9 @@ class QueryGenerator {
/**
* 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)
* @returns {String} The generated sql query
* @returns {string} The generated sql query
* @private
*/
jsonPathExtractionQuery(column, path) {
......@@ -1946,7 +1946,7 @@ class QueryGenerator {
*
* @param {Object} options An object with selectQuery options.
* @param {Object} options The model passed to the selectQuery.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
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
/**
*
* @param {String} dialect Dialect name
* @param {String} identifier Identifier to quote
* @param {string} dialect Dialect name
* @param {string} identifier Identifier to quote
* @param {Object} [options]
* @param {Boolean} [options.force=false]
* @param {Boolean} [options.quoteIdentifiers=true]
* @param {boolean} [options.force=false]
* @param {boolean} [options.quoteIdentifiers=true]
*
* @returns {String}
* @returns {string}
* @private
*/
function quoteIdentifier(dialect, identifier, options) {
......@@ -79,9 +79,9 @@ module.exports.quoteIdentifier = quoteIdentifier;
/**
* Test if a give string is already quoted
*
* @param {String} identifier
* @param {string} identifier
*
* @return Boolean
* @returns Boolean
* @private
*/
function isIdentifierQuoted(identifier) {
......
lib/dialects/abstract/query-generator/transaction.js
......@@ -6,9 +6,9 @@ const TransactionQueries = {
/**
* 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.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
setAutocommitQuery(value, options) {
......@@ -27,9 +27,9 @@ const TransactionQueries = {
/**
* 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.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
setIsolationLevelQuery(value, options) {
......@@ -49,7 +49,7 @@ const TransactionQueries = {
*
* @param {Transaction} transaction
* @param {Object} options An object with options.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
startTransactionQuery(transaction) {
......@@ -66,7 +66,7 @@ const TransactionQueries = {
*
* @param {Transaction} transaction
* @param {Object} options An object with options.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
deferConstraintsQuery() {},
......@@ -79,7 +79,7 @@ const TransactionQueries = {
* Returns a query that commits a transaction.
*
* @param {Object} options An object with options.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
commitTransactionQuery(transaction) {
......@@ -95,7 +95,7 @@ const TransactionQueries = {
*
* @param {Transaction} transaction
* @param {Object} options An object with options.
* @return {String} The generated sql query.
* @returns {string} The generated sql query.
* @private
*/
rollbackTransactionQuery(transaction) {
......
lib/dialects/abstract/query.js
......@@ -95,7 +95,7 @@ class AbstractQuery {
*
* 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
*/
run() {
......@@ -105,7 +105,7 @@ class AbstractQuery {
/**
* Check the logging option of the instance and print deprecation warnings.
*
* @return {void}
* @returns {void}
* @private
*/
checkLoggingOption() {
......@@ -118,7 +118,7 @@ class AbstractQuery {
/**
* Get the attributes of an insert query, which contains the just inserted id.
*
* @return {String} The field name.
* @returns {string} The field name.
* @private
*/
getInsertIdField() {
......
lib/dialects/mssql/query-generator.js
......@@ -698,7 +698,7 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generate common SQL prefix for ForeignKeysQuery.
* @returns {String}
* @returns {string}
*/
_getForeignKeysQueryPrefix(catalogName) {
return 'SELECT ' +
......@@ -725,8 +725,8 @@ class MSSQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that returns all foreign keys details of a table.
* @param {Stirng|Object} table
* @param {String} catalogName database name
* @returns {String}
* @param {string} catalogName database name
* @returns {string}
*/
getForeignKeysQuery(table, catalogName) {
const tableName = table.tableName || table;
......
lib/dialects/mssql/query-interface.js
......@@ -11,13 +11,12 @@
/**
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} 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 {Boolean|Function} [options.logging] A function that logs the sql queries, or false for explicitly not logging these queries
@private
*/
const removeColumn = function(tableName, attributeName, options) {
......
lib/dialects/mysql/connection-manager.js
......@@ -17,7 +17,7 @@ const parserStore = require('../parserStore')('mysql');
* Use https://github.com/sidorares/node-mysql2 to connect with MySQL server
*
* @extends AbstractConnectionManager
* @return Class<ConnectionManager>
* @returns Class<ConnectionManager>
* @private
*/
......@@ -63,7 +63,7 @@ class ConnectionManager extends AbstractConnectionManager {
* Set the pool handlers on connection.error
* Also set proper timezone once conection is connected
*
* @return Promise<Connection>
* @returns Promise<Connection>
* @private
*/
connect(config) {
......
lib/dialects/mysql/query-generator.js
......@@ -403,8 +403,8 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/**
* Check whether the statmement is json function or simple path
*
* @param {String} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function
* @param {string} stmt The statement to validate
* @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token
* @private
*/
......@@ -469,7 +469,7 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generates fields for getForeignKeysQuery
* @returns {String} fields
* @returns {string} fields
* @private
*/
_getForeignKeysQueryFields() {
......@@ -492,9 +492,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that returns all foreign keys of a table.
*
* @param {String} tableName The name of the table.
* @param {String} schemaName The name of the schema.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @param {string} schemaName The name of the schema.
* @returns {string} The generated sql query.
* @private
*/
getForeignKeysQuery(tableName, schemaName) {
......@@ -505,9 +505,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that returns the foreign key constraint of a given column.
*
* @param {String} tableName The name of the table.
* @param {String} columnName The name of the column.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @param {string} columnName The name of the column.
* @returns {string} The generated sql query.
* @private
*/
getForeignKeyQuery(table, columnName) {
......@@ -529,9 +529,9 @@ class MySQLQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that removes a foreign key from a table.
*
* @param {String} tableName The name of the table.
* @param {String} foreignKey The name of the foreign key constraint.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @param {string} foreignKey The name of the foreign key constraint.
* @returns {string} The generated sql query.
* @private
*/
dropForeignKeyQuery(tableName, foreignKey) {
......
lib/dialects/mysql/query-interface.js
......@@ -14,12 +14,10 @@ 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.
@method removeColumn
@for QueryInterface
@param {String} tableName The name of the table.
@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
@private
*/
function removeColumn(tableName, columnName, options) {
......
lib/dialects/postgres/query-generator.js
......@@ -129,8 +129,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/**
* Check whether the statmement is json function or simple path
*
* @param {String} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function
* @param {string} stmt The statement to validate
* @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token
*/
_checkValidJsonStatement(stmt) {
......@@ -841,8 +841,8 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that returns all foreign keys of a table.
*
* @param {String} tableName The name of the table.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @returns {string} The generated sql query.
* @private
*/
getForeignKeysQuery(tableName) {
......@@ -852,7 +852,7 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/**
* Generate common SQL prefix for getForeignKeyReferencesQuery.
* @returns {String}
* @returns {string}
*/
_getForeignKeyReferencesQueryPrefix() {
return 'SELECT ' +
......@@ -878,9 +878,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
* 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.
* @param {String} tableName
* @param {String} catalogName
* @param {String} schemaName
* @param {string} tableName
* @param {string} catalogName
* @param {string} schemaName
*/
getForeignKeyReferencesQuery(tableName, catalogName, schemaName) {
return this._getForeignKeyReferencesQueryPrefix() +
......@@ -900,9 +900,9 @@ class PostgresQueryGenerator extends AbstractQueryGenerator {
/**
* Generates an SQL query that removes a foreign key from a table.
*
* @param {String} tableName The name of the table.
* @param {String} foreignKey The name of the foreign key constraint.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @param {string} foreignKey The name of the foreign key constraint.
* @returns {string} The generated sql query.
* @private
*/
dropForeignKeyQuery(tableName, foreignKey) {
......
lib/dialects/postgres/query-interface.js
......@@ -17,12 +17,12 @@ const _ = require('lodash');
/**
* 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]
* @param {Model} [model]
*
* @return {Promise}
* @returns {Promise}
* @private
*/
function ensureEnums(tableName, attributes, options, model) {
......
lib/dialects/sqlite/query-generator.js
......@@ -78,8 +78,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator {
/**
* Check whether the statmement is json function or simple path
*
* @param {String} stmt The statement to validate
* @returns {Boolean} true if the given statement is json function
* @param {string} stmt The statement to validate
* @returns {boolean} true if the given statement is json function
* @throws {Error} throw if the statement looks like json function but has invalid token
*/
_checkValidJsonStatement(stmt) {
......@@ -490,8 +490,8 @@ class SQLiteQueryGenerator extends MySqlQueryGenerator {
/**
* Generates an SQL query that returns all foreign keys of a table.
*
* @param {String} tableName The name of the table.
* @return {String} The generated sql query.
* @param {string} tableName The name of the table.
* @returns {string} The generated sql query.
* @private
*/
getForeignKeysQuery(tableName) {
......
lib/dialects/sqlite/query-interface.js
......@@ -18,11 +18,8 @@ const QueryTypes = require('../../query-types');
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.
@method removeColumn
@for QueryInterface
@param {String} tableName The name of the table.
@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 {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;
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.
@method changeColumn
@for QueryInterface
@param {String} tableName The name of the table.
@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} options
@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;
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.
@method renameColumn
@for QueryInterface
@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 {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 {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;
/**
*
* @param {String} tableName
* @param {string} tableName
* @param {Object} options Query Options
*
* @private
......
lib/errors/index.js
......@@ -6,6 +6,8 @@
*
* This means that errors can be accessed using `Sequelize.ValidationError` or `sequelize.ValidationError`
* The Base Error all Sequelize Errors inherit from.
*
* @extends Error
*/
class BaseError extends Error {
constructor(message) {
......@@ -18,6 +20,8 @@ exports.BaseError = BaseError;
/**
* Scope Error. Thrown when the sequelize cannot query the specified scope.
*
* @extends BaseError
*/
class SequelizeScopeError extends BaseError {
constructor(parent) {
......@@ -36,6 +40,8 @@ exports.SequelizeScopeError = SequelizeScopeError;
* @param {Array} [errors] Array of ValidationErrorItem objects describing the validation errors
*
* @property errors {ValidationErrorItems[]}
*
* @extends BaseError
*/
class ValidationError extends BaseError {
constructor(message, errors) {
......@@ -63,7 +69,8 @@ class ValidationError extends BaseError {
* Gets all validation error items for the path / field specified.
*
* @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) {
return this.errors.reduce((reduced, error) => {
......@@ -78,6 +85,8 @@ exports.ValidationError = ValidationError;
/**
* Thrown when attempting to update a stale model instance
*
* @extends BaseError
*/
class OptimisticLockError extends BaseError {
constructor(options) {
......@@ -107,6 +116,8 @@ exports.OptimisticLockError = OptimisticLockError;
/**
* A base class for all database related errors.
*
* @extends BaseError
*/
class DatabaseError extends BaseError {
constructor(parent) {
......@@ -132,6 +143,8 @@ exports.DatabaseError = DatabaseError;
/**
* Thrown when a database query times out because of a deadlock
*
* @extends DatabaseError
*/
class TimeoutError extends DatabaseError {
constructor(parent) {
......@@ -144,6 +157,8 @@ exports.TimeoutError = TimeoutError;
/**
* Thrown when a unique constraint is violated in the database
*
* @extends ValidationError
*/
class UniqueConstraintError extends ValidationError {
constructor(options) {
......@@ -166,6 +181,8 @@ exports.UniqueConstraintError = UniqueConstraintError;
/**
* Thrown when a foreign key constraint is violated in the database
*
* @extends DatabaseError
*/
class ForeignKeyConstraintError extends DatabaseError {
constructor(options) {
......@@ -188,6 +205,8 @@ exports.ForeignKeyConstraintError = ForeignKeyConstraintError;
/**
* Thrown when an exclusion constraint is violated in the database
*
* @extends DatabaseError
*/
class ExclusionConstraintError extends DatabaseError {
constructor(options) {
......@@ -208,6 +227,8 @@ exports.ExclusionConstraintError = ExclusionConstraintError;
/**
* Thrown when constraint name is not found in the database
*
* @extends DatabaseError
*/
class UnknownConstraintError extends DatabaseError {
constructor(options) {
......@@ -229,43 +250,46 @@ exports.UnknownConstraintError = UnknownConstraintError;
/**
* Validation Error Item
* Instances of this class are included in the `ValidationError.errors` property.
*/
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 {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
* @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 {
constructor(message, type, path, value, inst, validatorKey, fnName, fnArgs) {
/**
* An error message
*
* @type {String} message
* @type {string} message
*/
this.message = message || '';
/**
* The type/origin of the validation error
*
* @type {String}
* @type {string}
*/
this.type = null;
/**
* The field that triggered the validation error
*
* @type {String}
* @type {string}
*/
this.path = path || null;
/**
* The value that generated the error
*
* @type {String}
* @type {string}
*/
this.value = value !== undefined ? value : null;
......@@ -281,21 +305,21 @@ class ValidationErrorItem {
/**
* A validation "key", used for identification
*
* @type {String}
* @type {string}
*/
this.validatorKey = validatorKey || null;
/**
* 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;
/**
* Parameters used with the BUILT-IN validator function, if applicable
*
* @type {String}
* @type {string}
*/
this.validatorArgs = fnArgs || [];
......@@ -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
*
* @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
* @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.
* @throws {Error} thrown if NSSeparator is found to be invalid.
* @return {String}
* @returns {string}
*
* @private
*/
......@@ -356,9 +380,9 @@ exports.ValidationErrorItem = ValidationErrorItem;
* An enum that defines valid ValidationErrorItem `origin` values
*
* @type {Object}
* @property CORE {String} specifies errors that originate from the sequelize "core"
* @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 CORE {string} specifies errors that originate from the sequelize "core"
* @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
*/
ValidationErrorItem.Origins = {
CORE: 'CORE',
......@@ -382,6 +406,8 @@ ValidationErrorItem.TypeStringMap = {
/**
* A base class for all connection related errors.
*
* @extends BaseError
*/
class ConnectionError extends BaseError {
constructor(parent) {
......@@ -400,6 +426,8 @@ exports.ConnectionError = ConnectionError;
/**
* Thrown when a connection to a database is refused
*
* @extends ConnectionError
*/
class ConnectionRefusedError extends ConnectionError {
constructor(parent) {
......@@ -412,6 +440,8 @@ exports.ConnectionRefusedError = ConnectionRefusedError;
/**
* Thrown when a connection to a database is refused due to insufficient privileges
*
* @extends ConnectionError
*/
class AccessDeniedError extends ConnectionError {
constructor(parent) {
......@@ -424,6 +454,8 @@ exports.AccessDeniedError = AccessDeniedError;
/**
* Thrown when a connection to a database has a hostname that was not found
*
* @extends ConnectionError
*/
class HostNotFoundError extends ConnectionError {
constructor(parent) {
......@@ -436,6 +468,8 @@ exports.HostNotFoundError = HostNotFoundError;
/**
* Thrown when a connection to a database has a hostname that was not reachable
*
* @extends ConnectionError
*/
class HostNotReachableError extends ConnectionError {
constructor(parent) {
......@@ -448,6 +482,8 @@ exports.HostNotReachableError = HostNotReachableError;
/**
* Thrown when a connection to a database has invalid values for any of the connection parameters
*
* @extends ConnectionError
*/
class InvalidConnectionError extends ConnectionError {
constructor(parent) {
......@@ -460,6 +496,8 @@ exports.InvalidConnectionError = InvalidConnectionError;
/**
* Thrown when a connection to a database times out
*
* @extends ConnectionError
*/
class ConnectionTimedOutError extends ConnectionError {
constructor(parent) {
......@@ -472,6 +510,8 @@ exports.ConnectionTimedOutError = ConnectionTimedOutError;
/**
* Thrown when a some problem occurred with Instance methods (see message for details)
*
* @extends BaseError
*/
class InstanceError extends BaseError {
constructor(message) {
......@@ -484,6 +524,8 @@ exports.InstanceError = InstanceError;
/**
* Thrown when a record was not found, Usually used with rejectOnEmpty mode (see message for details)
*
* @extends BaseError
*/
class EmptyResultError extends BaseError {
constructor(message) {
......@@ -496,6 +538,8 @@ exports.EmptyResultError = EmptyResultError;
/**
* Thrown when an include statement is improperly constructed (see message for details)
*
* @extends BaseError
*/
class EagerLoadingError extends BaseError {
constructor(message) {
......@@ -508,6 +552,8 @@ exports.EagerLoadingError = EagerLoadingError;
/**
* Thrown when an association is improperly constructed (see message for details)
*
* @extends BaseError
*/
class AssociationError extends BaseError {
constructor(message) {
......@@ -519,6 +565,8 @@ class AssociationError extends BaseError {
exports.AssociationError = AssociationError;
/**
* Thrown when a query is passed invalid options (see message for details)
*
* @extends BaseError
*/
class QueryError extends BaseError {
constructor(message) {
......@@ -535,6 +583,8 @@ exports.QueryError = QueryError;
*
* @param {Error} error Error for a given record/instance
* @param {Object} record DAO instance that error belongs to
*
* @extends BaseError
*/
class BulkRecordError extends BaseError {
constructor(error, record) {
......
lib/instance-validator.js
'use strict';
const validator = require('./utils/validator-extras').validator;
const extendModelValidations = require('./utils/validator-extras').extendModelValidations;
const _ = require('lodash');
const Utils = require('./utils');
const sequelizeError = require('./errors');
const Promise = require('./promise');
const DataTypes = require('./data-types');
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 {Object} options A dictionary with options.
* @constructor
*
* @private
*/
class InstanceValidator {
......@@ -61,7 +61,7 @@ class InstanceValidator {
/**
* The main entry point for the Validation module, invoke to start the dance.
*
* @return {Promise}
* @returns {Promise}
* @private
*/
_validate() {
......@@ -86,7 +86,7 @@ class InstanceValidator {
* - On validation success: After Validation Model Hooks
* - On validation failure: Validation Failed Model Hooks
*
* @return {Promise}
* @returns {Promise}
* @private
*/
validate() {
......@@ -100,7 +100,7 @@ class InstanceValidator {
* - On validation success: After Validation Model Hooks
* - On validation failure: Validation Failed Model Hooks
*
* @return {Promise}
* @returns {Promise}
* @private
*/
_validateAndRunHooks() {
......@@ -118,7 +118,7 @@ class InstanceValidator {
/**
* 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
*/
_builtinValidators() {
......@@ -152,7 +152,7 @@ class InstanceValidator {
/**
* 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
*/
_customValidators() {
......@@ -176,11 +176,12 @@ class InstanceValidator {
/**
* Validate a single attribute with all the defined built-in validators.
*
* @private
*
* @param {*} value Anything.
* @param {string} field The field name.
* @return {Promise} A promise, will always resolve,
* auto populates error on this.error local object.
* @private
*
* @returns {Promise} A promise, will always resolve, auto populates error on this.error local object.
*/
_builtinAttrValidate(value, field) {
// check if value is null (if null not allowed the Schema pass will capture it)
......@@ -222,12 +223,15 @@ class InstanceValidator {
/**
* Prepare and invoke a custom validator.
*
* @private
*
* @param {Function} validator The custom validator.
* @param {string} validatorType the custom validator type (name).
* @param {boolean=} optAttrDefined Set to true if custom validator was defined
* from the Attribute
* @return {Promise} A promise.
* @private
* @param {boolean} optAttrDefined Set to true if custom validator was defined from the attribute
* @param {*} optValue value for attribute
* @param {string} optField field for attribute
*
* @returns {Promise} A promise.
*/
_invokeCustomValidator(validator, validatorType, optAttrDefined, optValue, optField) {
let validatorFunction = null; // the validation function to call
......@@ -265,12 +269,14 @@ class InstanceValidator {
/**
* Prepare and invoke a build-in validator.
*
* @private
*
* @param {*} value Anything.
* @param {*} test The test case.
* @param {string} validatorType One of known to Sequelize validators.
* @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) {
return Promise.try(() => {
......@@ -295,6 +301,7 @@ class InstanceValidator {
* @param {*} test The test case.
* @param {string} validatorType One of known to Sequelize validators.
* @param {string} field The field that is being validated.
*
* @private
*/
_extractValidatorArgs(test, validatorType, field) {
......@@ -321,6 +328,7 @@ class InstanceValidator {
* @param {Object} rawAttribute As defined in the Schema.
* @param {string} field The field name.
* @param {*} value anything.
*
* @private
*/
_validateSchema(rawAttribute, field, value) {
......@@ -363,7 +371,8 @@ class InstanceValidator {
*
* @param {string} field The attribute name.
* @param {string|number} value The data value.
* @param {Array.<Promise.PromiseInspection>} Promise inspection objects.
* @param {Array<Promise.PromiseInspection>} promiseInspections objects.
*
* @private
*/
_handleReflectedResult(field, value, promiseInspections) {
......@@ -380,11 +389,11 @@ class InstanceValidator {
/**
* Signs all errors retaining the original.
*
* @param {Boolean} isBuiltin - Determines if error is from builtin validator.
* @param {String} errorKey - name of invalid attribute.
* @param {Error|String} rawError - The original error.
* @param {String|Number} value - The data that triggered the error.
* @param {String} fnName - Name of the validator, if any
* @param {boolean} isBuiltin - Determines if error is from builtin validator.
* @param {string} errorKey - name of invalid attribute.
* @param {Error|string} rawError - The original error.
* @param {string|number} value - The data that triggered the error.
* @param {string} fnName - Name of the validator, if any
* @param {Array} fnArgs - Arguments for the validator [function], if any
*
* @private
......
lib/model-manager.js
......@@ -37,9 +37,11 @@ class ModelManager {
}
/**
* Iterate over Models in an order suitable for e.g. creating tables. Will
* take foreign key constraints into account so that dependencies are visited
* before dependents.
* Iterate over Models in an order suitable for e.g. creating tables.
* Will take foreign key constraints into account so that dependencies are visited before dependents.
*
* @param {Function} iterator method to execute on each model
* @param {Object} [options] iterator options
* @private
*/
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');
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.
*
* @class Transaction
* @see {@link Sequelize.transaction}
*/
class Transaction {
/**
* Creates a new transaction instance
*
* @param {Sequelize} sequelize A configured sequelize Instance
* @param {Object} options An object with options
* @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.isolationLevel=true Sets the isolation level of the transaction.
* @param {String} options.deferrable Sets the constraints to be deferred or immediately checked.
* @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.isolationLevel=true Sets the isolation level of the transaction.
* @param {string} options.deferrable Sets the constraints to be deferred or immediately checked.
*/
constructor(sequelize, options) {
this.sequelize = sequelize;
......@@ -52,10 +55,9 @@ class Transaction {
/**
* Commit the transaction
*
* @return {Promise}
* @returns {Promise}
*/
commit() {
if (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 {
/**
* Rollback (abort) the transaction
*
* @return {Promise}
* @returns {Promise}
*/
rollback() {
if (this.finished) {
return Promise.reject(new Error('Transaction cannot be rolled back because it has been finished with state: ' + this.finished));
}
......@@ -191,9 +192,10 @@ class Transaction {
/**
* 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
* @memberOf Sequelize.Transaction
* @memberof Sequelize.Transaction
*/
afterCommit(fn) {
if (!fn || typeof fn !== 'function') {
......@@ -209,17 +211,15 @@ class Transaction {
*
* Pass in the desired level as the first argument:
*
* ```js
* @example
* return sequelize.transaction({type: Sequelize.Transaction.TYPES.EXCLUSIVE}, transaction => {
*
* // your transactions
*
* }).then(result => {
* // transaction has been committed. Do something after the commit if required.
* }).catch(err => {
* // do something with the err.
* });
* ```
*
* @property DEFERRED
* @property IMMEDIATE
* @property EXCLUSIVE
......@@ -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`.
*
* Pass in the desired level as the first argument:
*
* ```js
* @example
* return sequelize.transaction({isolationLevel: Sequelize.Transaction.ISOLATION_LEVELS.SERIALIZABLE}, transaction => {
*
* // your transactions
*
* }).then(result => {
* // transaction has been committed. Do something after the commit if required.
* }).catch(err => {
* // do something with the err.
* });
* ```
*
* @property READ_UNCOMMITTED
* @property READ_COMMITTED
* @property REPEATABLE_READ
......@@ -267,17 +265,15 @@ class Transaction {
/**
* Possible options for row locking. Used in conjunction with `find` calls:
*
* ```js
* t1 // is a transaction
* @example
* // t1 is a transaction
* Model.findAll({
* where: ...,
* transaction: t1,
* lock: t1.LOCK...
* });
* ```
*
* Postgres also supports specific locks while eager loading by using OF:
* ```js
* @example <caption>Postgres also supports specific locks while eager loading by using OF:</caption>
* UserModel.findAll({
* where: ...,
* include: [TaskModel, ...],
......@@ -287,23 +283,20 @@ class Transaction {
* 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
* t1 // is a transaction
* @example <caption>You can also skip locked rows:</caption>
* // t1 is a transaction
* Model.findAll({
* where: ...,
* transaction: t1,
* lock: 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 SHARE
* @property KEY_SHARE Postgres 9.3+ only
......@@ -319,7 +312,7 @@ class Transaction {
}
/**
* @see {@link Transaction.LOCK}
* Please {@link Transaction.LOCK}
*/
get LOCK() {
return Transaction.LOCK;
......
lib/utils.js
......@@ -278,7 +278,7 @@ exports.toDefaultValue = toDefaultValue;
* in a db schema using the DEFAULT directive.
*
* @param {*} value Any default value.
* @return {boolean} yes / no.
* @returns {boolean} yes / no.
* @private
*/
function defaultValueSchemable(value) {
......@@ -394,7 +394,7 @@ exports.removeTicks = removeTicks;
* }
*
* @param value, an Object
* @return Object, an flattened object
* @returns Object, an flattened object
* @private
*/
function flattenObjectDeep(value) {
......@@ -501,7 +501,7 @@ exports.Where = Where;
/**
* getOperators
* @param {Object} obj
* @return {Array<Symbol>} All operators properties of obj
* @returns {Array<Symbol>} All operators properties of obj
* @private
*/
function getOperators(obj) {
......@@ -512,7 +512,7 @@ exports.getOperators = getOperators;
/**
* getComplexKeys
* @param {Object} obj
* @return {Array<String|Symbol>} All keys including operators
* @returns {Array<String|Symbol>} All keys including operators
* @private
*/
function getComplexKeys(obj) {
......@@ -523,7 +523,7 @@ exports.getComplexKeys = getComplexKeys;
/**
* getComplexSize
* @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
*/
function getComplexSize(obj) {
......@@ -535,7 +535,7 @@ exports.getComplexSize = getComplexSize;
* Returns true if a where clause is empty, even with Symbols
*
* @param {Object} obj
* @return {Boolean}
* @returns {boolean}
* @private
*/
function isWhereEmpty(obj) {
......@@ -546,9 +546,9 @@ exports.isWhereEmpty = isWhereEmpty;
/**
* Returns ENUM name by joining table and column name
*
* @param {String} tableName
* @param {String} columnName
* @return {String}
* @param {string} tableName
* @param {string} columnName
* @returns {string}
* @private
*/
function generateEnumName(tableName, columnName) {
......@@ -559,7 +559,7 @@ exports.generateEnumName = generateEnumName;
/**
* Returns an new Object which keys are camelized
* @param {Object} obj
* @return {String}
* @returns {string}
* @private
*/
function camelizeObjectKeys(obj) {
......@@ -624,7 +624,7 @@ exports.classToInvokable = classToInvokable;
*
* @param {Object} index
* @param {Array} index.fields
* @param {String} [index.name]
* @param {string} [index.name]
* @param {String|Object} tableName
*
* @returns {Object}
......
lib/utils/inherits.js
......@@ -4,7 +4,12 @@ const util = require('util');
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
*/
function inherits(constructor, superConstructor) {
......
package.json
......@@ -47,13 +47,16 @@
"continuation-local-storage": "^3.x",
"cross-env": "^5.2.0",
"cz-conventional-changelog": "^2.x",
"docdash": "^0.4.0",
"env-cmd": "^8.0.0",
"esdoc": "^0.5.2",
"eslint": "^5.0.0",
"eslint-plugin-jsdoc": "^3.7.1",
"eslint-plugin-mocha": "^5.0.0",
"hints": "^1.x",
"husky": "^0.x",
"istanbul": "^0.x",
"jsdoc": "^3.5.5",
"lcov-result-merger": "^3.0.0",
"mocha": "^5.x",
"mysql2": "^1.x",
......@@ -91,6 +94,7 @@
"test-docker-unit": "npm run test-unit",
"test-docker-integration": "env-cmd $npm_package_options_env_cmd npm run test-integration",
"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))\"",
"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",
......
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!