verdnatura-mirror
/
loopback-datasource-juggler
mirror of https://github.com/loopbackio/loopback-datasource-juggler
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More JSDoc cleanup

This commit is contained in:
crandmck 2014-06-10 14:27:58 -07:00
parent 04e1256b8b
commit c355c99cbd
1 changed files with 109 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
lib/datasource.js
View File

@ -587,6 +587,7 @@ DataSource.prototype.createModel = DataSource.prototype.define = function define
* Mixin DataAccessObject methods. * Mixin DataAccessObject methods.
* *
* @param {Function} ModelCtor The model constructor * @param {Function} ModelCtor The model constructor
* @private
*/ */
DataSource.prototype.mixin = function (ModelCtor) { DataSource.prototype.mixin = function (ModelCtor) {
@ -719,12 +720,14 @@ DataSource.prototype.defineProperty = function (model, prop, params) {
/** /**
* Drop each model table and re-create. * Drop each model table and re-create.
* This method applies only to SQL connectors. * This method applies only to database connectors. For MongoDB, it drops and creates indexes.
* *
* **WARNING**: Calling this function deletes all data! Use `autoupdate()` to preserve data.
*
* @param {String} model Model to migrate. If not present, apply to all models. Can also be an array of Strings. * @param {String} model Model to migrate. If not present, apply to all models. Can also be an array of Strings.
* @param {Function} cb Callback function. Optional. * @param {Function} [callback] Callback function. Optional.
* *
* WARNING: Calling this function will cause all data to be lost! Use autoupdate if you need to preserve data.
*/ */
DataSource.prototype.automigrate = function (models, cb) { DataSource.prototype.automigrate = function (models, cb) {
this.freeze(); this.freeze();
@ -741,7 +744,7 @@ DataSource.prototype.automigrate = function (models, cb) {
/** /**
* Update existing database tables. * Update existing database tables.
* This method make sense only for sql connectors. * This method applies only to database connectors.
* *
* @param {String} model Model to migrate. If not present, apply to all models. Can also be an array of Strings. * @param {String} model Model to migrate. If not present, apply to all models. Can also be an array of Strings.
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
@ -765,10 +768,7 @@ DataSource.prototype.autoupdate = function (models, cb) {
* *
* @param {Object} options The options * @param {Object} options The options
* @param {Function} Callback function. Optional. * @param {Function} Callback function. Optional.
* @options {Object} options Discovery options. * @options {Object} options Discovery options. See below.
*
* Keys in options object:
*
* @property {Boolean} all If true, discover all models; if false, discover only models owned by the current user. * @property {Boolean} all If true, discover all models; if false, discover only models owned by the current user.
* @property {Boolean} views If true, nclude views; if false, only tables. * @property {Boolean} views If true, nclude views; if false, only tables.
* @property {Number} limit Page size * @property {Number} limit Page size
@ -785,8 +785,12 @@ DataSource.prototype.discoverModelDefinitions = function (options, cb) {
}; };
/** /**
* The synchronous version of discoverModelDefinitions * The synchronous version of discoverModelDefinitions.
* @param {Object} options The options * @options {Object} options The options
* @property {Boolean} all If true, discover all models; if false, discover only models owned by the current user.
* @property {Boolean} views If true, nclude views; if false, only tables.
* @property {Number} limit Page size
* @property {Number} offset Starting index
* @returns {*} * @returns {*}
*/ */
DataSource.prototype.discoverModelDefinitionsSync = function (options) { DataSource.prototype.discoverModelDefinitionsSync = function (options) {
@ -800,24 +804,22 @@ DataSource.prototype.discoverModelDefinitionsSync = function (options) {
/** /**
* Discover properties for a given model. * Discover properties for a given model.
* *
* property description: * Callback function return value is an object that can have the following properties:
* *
*| Key | Type | Description | *| Key | Type | Description |
*|-----|------|-------------| *|-----|------|-------------|
*|owner | String | Database owner or schema| *|owner | String | Database owner or schema|
*|tableName | String | Table/view name| *|tableName | String | Table/view name|
*|columnName | String | Column name| *|columnName | String | Column name|
*|dataType | String | Data type| *|dataType | String | Data type|
*|dataLength | Number | Data length| *|dataLength | Number | Data length|
*|dataPrecision | Number | Numeric data precision| *|dataPrecision | Number | Numeric data precision|
*|dataScale |Number | Numeric data scale| *|dataScale |Number | Numeric data scale|
*|nullable |Boolean | If true, then the data can be null| *|nullable |Boolean | If true, then the data can be null|
*
* Options:
* - owner/schema The database owner/schema
* *
* @param {String} modelName The table/view name * @param {String} modelName The table/view name
* @param {Object} options The options * @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} cb Callback function. Optional * @param {Function} cb Callback function. Optional
* *
*/ */
@ -846,22 +848,19 @@ DataSource.prototype.discoverModelPropertiesSync = function (modelName, options)
/** /**
* Discover primary keys for a given owner/modelName. * Discover primary keys for a given owner/modelName.
* Callback function return value is an object that can have the following properties:
* *
* Each primary key column description has the following columns: *| Key | Type | Description |
* *|-----|------|-------------|
* - owner {String} => table schema (may be null) *| owner |String | Table schema or owner (may be null). Owner defaults to current user.
* - tableName {String} => table name *| tableName |String| Table name
* - columnName {String} => column name *| columnName |String| Column name
* - keySeq {Number} => sequence number within primary key( a value of 1 represents the first column of the primary key, a value of 2 would represent the second column within the primary key). *| keySeq |Number| Sequence number within primary key (1 indicates the first column in the primary key; 2 indicates the second column in the primary key).
* - pkName {String} => primary key name (may be null) *| pkName |String| Primary key name (may be null)
*
* The owner defaults to current user.
*
* Options:
* - owner/schema The database owner/schema
* *
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} options The options * @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
*/ */
DataSource.prototype.discoverPrimaryKeys = function (modelName, options, cb) { DataSource.prototype.discoverPrimaryKeys = function (modelName, options, cb) {
@ -876,7 +875,8 @@ DataSource.prototype.discoverPrimaryKeys = function (modelName, options, cb) {
/** /**
* The synchronous version of discoverPrimaryKeys * The synchronous version of discoverPrimaryKeys
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} options The options * @options {Object} options The options
* @property {String} owner|schema The database owner orschema
* @returns {*} * @returns {*}
*/ */
DataSource.prototype.discoverPrimaryKeysSync = function (modelName, options) { DataSource.prototype.discoverPrimaryKeysSync = function (modelName, options) {
@ -890,24 +890,23 @@ DataSource.prototype.discoverPrimaryKeysSync = function (modelName, options) {
/** /**
* Discover foreign keys for a given owner/modelName * Discover foreign keys for a given owner/modelName
* *
* `foreign key description` * Callback function return value is an object that can have the following properties:
* *
* fkOwner String => foreign key table schema (may be null) *| Key | Type | Description |
* fkName String => foreign key name (may be null) *|-----|------|-------------|
* fkTableName String => foreign key table name *|fkOwner |String | Foreign key table schema (may be null)
* fkColumnName String => foreign key column name *|fkName |String | Foreign key name (may be null)
* keySeq Number => sequence number within a foreign key( a value of 1 represents the first column of the foreign key, a value of 2 would represent the second column within the foreign key). *|fkTableName |String | Foreign key table name
* pkOwner String => primary key table schema being imported (may be null) *|fkColumnName |String | Foreign key column name
* pkName String => primary key name (may be null) *|keySeq |Number | Sequence number within a foreign key( a value of 1 represents the first column of the foreign key, a value of 2 would represent the second column within the foreign key).
* pkTableName String => primary key table name being imported *|pkOwner |String | Primary key table schema being imported (may be null)
* pkColumnName String => primary key column name being imported *|pkName |String | Primary key name (may be null)
* *|pkTableName |String | Primary key table name being imported
* `options` *|pkColumnName |String | Primary key column name being imported
*
* owner/schema The database owner/schema
* *
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} options The options * @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
* *
*/ */
@ -936,27 +935,26 @@ DataSource.prototype.discoverForeignKeysSync = function (modelName, options) {
}; };
/** /**
* Retrieves a description of the foreign key columns that reference the given table's primary key columns (the foreign keys exported by a table). * Retrieves a description of the foreign key columns that reference the given table's primary key columns
* They are ordered by fkTableOwner, fkTableName, and keySeq. * (the foreign keys exported by a table), ordered by fkTableOwner, fkTableName, and keySeq.
*
* Callback function return value is an object that can have the following properties:
* *
* `foreign key description` *| Key | Type | Description |
* *|-----|------|-------------|
* fkOwner {String} => foreign key table schema (may be null) *|fkOwner |String | Foreign key table schema (may be null)
* fkName {String} => foreign key name (may be null) *|fkName |String | Foreign key name (may be null)
* fkTableName {String} => foreign key table name *|fkTableName |String | Foreign key table name
* fkColumnName {String} => foreign key column name *|fkColumnName |String | Foreign key column name
* keySeq {Number} => sequence number within a foreign key( a value of 1 represents the first column of the foreign key, a value of 2 would represent the second column within the foreign key). *|keySeq |Number | Sequence number within a foreign key( a value of 1 represents the first column of the foreign key, a value of 2 would represent the second column within the foreign key).
* pkOwner {String} => primary key table schema being imported (may be null) *|pkOwner |String | Primary key table schema being imported (may be null)
* pkName {String} => primary key name (may be null) *|pkName |String | Primary key name (may be null)
* pkTableName {String} => primary key table name being imported *|pkTableName |String | Primary key table name being imported
* pkColumnName {String} => primary key column name being imported *|pkColumnName |String | Primary key column name being imported
*
* `options`
*
* owner/schema The database owner/schema
* *
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} options The options * @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
*/ */
DataSource.prototype.discoverExportedForeignKeys = function (modelName, options, cb) { DataSource.prototype.discoverExportedForeignKeys = function (modelName, options, cb) {
@ -1083,17 +1081,14 @@ DataSource.prototype.discoverSchema = function (modelName, options, cb) {
}; };
/** /**
* Discover schema from a given modelName/view * Discover schema from a given modelName/view.
* *
* `options` * @param {String} modelName The model name.
* * @options {Object} [options] Options; see below.
* {String} owner/schema - The database owner/schema name * @property {String} owner|schema Database owner or schema name.
* {Boolean} relations - If relations (primary key/foreign key) are navigated * @property {Boolean} relations True if relations (primary key/foreign key) are navigated; false otherwise.
* {Boolean} all - If all owners are included * @property {Boolean} all True if all owners are included; false otherwise.
* {Boolean} views - If views are included * @property {Boolean} views True if views are included; false otherwise.
*
* @param {String} modelName The model name
* @param {Object} [options] The options
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
*/ */
DataSource.prototype.discoverSchemas = function (modelName, options, cb) { DataSource.prototype.discoverSchemas = function (modelName, options, cb) {
@ -1255,15 +1250,12 @@ DataSource.prototype.discoverSchemas = function (modelName, options, cb) {
/** /**
* Discover schema from a given table/view synchronously * Discover schema from a given table/view synchronously
* *
* `options`
*
* {String} owner/schema - The database owner/schema name
* {Boolean} relations - If relations (primary key/foreign key) are navigated
* {Boolean} all - If all owners are included
* {Boolean} views - If views are included
*
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} [options] The options * @options {Object} [options] Options; see below.
* @property {String} owner|schema Database owner or schema name.
* @property {Boolean} relations True if relations (primary key/foreign key) are navigated; false otherwise.
* @property {Boolean} all True if all owners are included; false otherwise.
* @property {Boolean} views True if views are included; false otherwise.
*/ */
DataSource.prototype.discoverSchemasSync = function (modelName, options) { DataSource.prototype.discoverSchemasSync = function (modelName, options) {
var self = this; var self = this;
@ -1395,17 +1387,14 @@ DataSource.prototype.discoverSchemasSync = function (modelName, options) {
}; };
/** /**
* Discover and build models from the given owner/modelName * Discover and build models from the specified owner/modelName.
* *
* `options` * @param {String} modelName The model name.
* * @options {Object} [options] Options; see below.
* {String} owner/schema - The database owner/schema name * @property {String} owner|schema Database owner or schema name.
* {Boolean} relations - If relations (primary key/foreign key) are navigated * @property {Boolean} relations True if relations (primary key/foreign key) are navigated; false otherwise.
* {Boolean} all - If all owners are included * @property {Boolean} all True if all owners are included; false otherwise.
* {Boolean} views - If views are included * @property {Boolean} views True if views are included; false otherwise.
*
* @param {String} modelName The model name
* @param {Object} [options] The options
* @param {Function} [cb] The callback function * @param {Function} [cb] The callback function
*/ */
DataSource.prototype.discoverAndBuildModels = function (modelName, options, cb) { DataSource.prototype.discoverAndBuildModels = function (modelName, options, cb) {
@ -1432,15 +1421,15 @@ DataSource.prototype.discoverAndBuildModels = function (modelName, options, cb)
}; };
/** /**
* Discover and build models from the given owner/modelName synchronously * Discover and build models from the given owner/modelName synchronously.
*
* `options`
*
* {String} owner/schema - The database owner/schema name
* {Boolean} relations - If relations (primary key/foreign key) are navigated
* {Boolean} all - If all owners are included
* {Boolean} views - If views are included
* *
* @param {String} modelName The model name.
* @options {Object} [options] Options; see below.
* @property {String} owner|schema Database owner or schema name.
* @property {Boolean} relations True if relations (primary key/foreign key) are navigated; false otherwise.
* @property {Boolean} all True if all owners are included; false otherwise.
* @property {Boolean} views True if views are included; false otherwise.
* @param {String} modelName The model name * @param {String} modelName The model name
* @param {Object} [options] The options * @param {Object} [options] The options
*/ */
@ -1459,8 +1448,8 @@ DataSource.prototype.discoverAndBuildModelsSync = function (modelName, options)
/** /**
* Check whether migrations needed * Check whether migrations needed
* This method make sense only for sql connectors. * This method applies only to SQL connectors.
* @param {String[]} [models] A model name or an array of model names. If not present, apply to all models * @param {String|String[]} [models] A model name or an array of model names. If not present, apply to all models.
*/ */
DataSource.prototype.isActual = function (models, cb) { DataSource.prototype.isActual = function (models, cb) {
this.freeze(); this.freeze();
@ -1516,8 +1505,8 @@ DataSource.prototype.tableName = function (modelName) {
/** /**
* Return column name for specified modelName and propertyName * Return column name for specified modelName and propertyName
* @param {String} modelName The model name * @param {String} modelName The model name
* @param propertyName The property name * @param {String} propertyName The property name
* @returns {String} columnName * @returns {String} columnName The column name.
*/ */
DataSource.prototype.columnName = function (modelName, propertyName) { DataSource.prototype.columnName = function (modelName, propertyName) {
return this.getModelDefinition(modelName).columnName(this.connector.name, propertyName); return this.getModelDefinition(modelName).columnName(this.connector.name, propertyName);
@ -1526,7 +1515,7 @@ DataSource.prototype.columnName = function (modelName, propertyName) {
/** /**
* Return column metadata for specified modelName and propertyName * Return column metadata for specified modelName and propertyName
* @param {String} modelName The model name * @param {String} modelName The model name
* @param propertyName The property name * @param {String} propertyName The property name
* @returns {Object} column metadata * @returns {Object} column metadata
*/ */
DataSource.prototype.columnMetadata = function (modelName, propertyName) { DataSource.prototype.columnMetadata = function (modelName, propertyName) {
@ -1625,7 +1614,7 @@ DataSource.prototype.defineForeignKey = function defineForeignKey(className, key
/** /**
* Close database connection * Close database connection
* @param {Function} cb The callback function. Optional. * @param {Function} [cb] The callback function. Optional.
*/ */
DataSource.prototype.disconnect = function disconnect(cb) { DataSource.prototype.disconnect = function disconnect(cb) {
var self = this; var self = this;
@ -1741,7 +1730,6 @@ DataSource.prototype.enableRemote = function (operation) {
* and disabled operations. To list the operations, call `dataSource.operations()`. * and disabled operations. To list the operations, call `dataSource.operations()`.
* *
*```js *```js
*
* var oracle = loopback.createDataSource({ * var oracle = loopback.createDataSource({
* connector: require('loopback-connector-oracle'), * connector: require('loopback-connector-oracle'),
* host: '...', * host: '...',
@ -1752,8 +1740,8 @@ DataSource.prototype.enableRemote = function (operation) {
* **Notes:** * **Notes:**
* *
* - Disabled operations will not be added to attached models. * - Disabled operations will not be added to attached models.
* - Disabling the remoting for a method only affects client access (it will still be available from server models). * - Disabling the remoting for a method only affects client access (it will still be available from server models).
* - Data sources must enable / disable operations before attaching or creating models. * - Data sources must enable / disable operations before attaching or creating models.
* @param {String} operation The operation name * @param {String} operation The operation name
*/ */
@ -1831,11 +1819,11 @@ DataSource.prototype.isRelational = function () {
return this.connector && this.connector.relational; return this.connector && this.connector.relational;
}; };
/** /*!
* Check if the data source is ready. * Check if the data source is ready.
* Returns a Boolean value. * Returns a Boolean value.
* @param obj {Object} ? * @param {Object} obj ?
* @param args {Object} ? * @param {Object} args ?
*/ */
DataSource.prototype.ready = function (obj, args) { DataSource.prototype.ready = function (obj, args) {
var self = this; var self = this;