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.
*
* @param {Function} ModelCtor The model constructor
* @private
*/
DataSource.prototype.mixin = function (ModelCtor) {
@ -719,12 +720,14 @@ DataSource.prototype.defineProperty = function (model, prop, params) {
/**
* 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 {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) {
this.freeze();
@ -741,7 +744,7 @@ DataSource.prototype.automigrate = function (models, cb) {
/**
* 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 {Function} [cb] The callback function
@ -765,10 +768,7 @@ DataSource.prototype.autoupdate = function (models, cb) {
*
* @param {Object} options The options
* @param {Function} Callback function. Optional.
* @options {Object} options Discovery options.
*
* Keys in options object:
*
* @options {Object} options Discovery options. See below.
* @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
@ -785,8 +785,12 @@ DataSource.prototype.discoverModelDefinitions = function (options, cb) {
};
/**
* The synchronous version of discoverModelDefinitions
* @param {Object} options The options
* The synchronous version of discoverModelDefinitions.
* @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 {*}
*/
DataSource.prototype.discoverModelDefinitionsSync = function (options) {
@ -800,24 +804,22 @@ DataSource.prototype.discoverModelDefinitionsSync = function (options) {
/**
* Discover properties for a given model.
*
* property description:
* Callback function return value is an object that can have the following properties:
*
*| Key | Type | Description |
*|-----|------|-------------|
*|owner | String | Database owner or schema|
*|tableName | String | Table/view name|
*|columnName | String | Column name|
*|dataType | String | Data type|
*|dataLength | Number | Data length|
*|dataPrecision | Number | Numeric data precision|
*|dataScale |Number | Numeric data scale|
*|nullable |Boolean | If true, then the data can be null|
*
* Options:
* - owner/schema The database owner/schema
*| Key | Type | Description |
*|-----|------|-------------|
*|owner | String | Database owner or schema|
*|tableName | String | Table/view name|
*|columnName | String | Column name|
*|dataType | String | Data type|
*|dataLength | Number | Data length|
*|dataPrecision | Number | Numeric data precision|
*|dataScale |Number | Numeric data scale|
*|nullable |Boolean | If true, then the data can be null|
*
* @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
*
*/
@ -846,22 +848,19 @@ DataSource.prototype.discoverModelPropertiesSync = function (modelName, options)
/**
* 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:
*
* - owner {String} => table schema (may be null)
* - tableName {String} => table 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).
* - pkName {String} => primary key name (may be null)
*
* The owner defaults to current user.
*
* Options:
* - owner/schema The database owner/schema
*| Key | Type | Description |
*|-----|------|-------------|
*| owner |String | Table schema or owner (may be null). Owner defaults to current user.
*| tableName |String| Table name
*| columnName |String| Column name
*| 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)
*
* @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
*/
DataSource.prototype.discoverPrimaryKeys = function (modelName, options, cb) {
@ -876,7 +875,8 @@ DataSource.prototype.discoverPrimaryKeys = function (modelName, options, cb) {
/**
* The synchronous version of discoverPrimaryKeys
* @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 {*}
*/
DataSource.prototype.discoverPrimaryKeysSync = function (modelName, options) {
@ -890,24 +890,23 @@ DataSource.prototype.discoverPrimaryKeysSync = function (modelName, options) {
/**
* 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)
* fkName String => foreign key name (may be null)
* fkTableName String => foreign key table 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).
* pkOwner String => primary key table schema being imported (may be null)
* pkName String => primary key name (may be null)
* pkTableName String => primary key table name being imported
* pkColumnName String => primary key column name being imported
*
* `options`
*
* owner/schema The database owner/schema
*| Key | Type | Description |
*|-----|------|-------------|
*|fkOwner |String | Foreign key table schema (may be null)
*|fkName |String | Foreign key name (may be null)
*|fkTableName |String | Foreign key table 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).
*|pkOwner |String | Primary key table schema being imported (may be null)
*|pkName |String | Primary key name (may be null)
*|pkTableName |String | Primary key table name being imported
*|pkColumnName |String | Primary key column name being imported
*
* @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
*
*/
@ -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).
* They are ordered by fkTableOwner, fkTableName, and keySeq.
* Retrieves a description of the foreign key columns that reference the given table's primary key columns
* (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`
*
* fkOwner {String} => foreign key table schema (may be null)
* fkName {String} => foreign key name (may be null)
* fkTableName {String} => foreign key table 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).
* pkOwner {String} => primary key table schema being imported (may be null)
* pkName {String} => primary key name (may be null)
* pkTableName {String} => primary key table name being imported
* pkColumnName {String} => primary key column name being imported
*
* `options`
*
* owner/schema The database owner/schema
*| Key | Type | Description |
*|-----|------|-------------|
*|fkOwner |String | Foreign key table schema (may be null)
*|fkName |String | Foreign key name (may be null)
*|fkTableName |String | Foreign key table 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).
*|pkOwner |String | Primary key table schema being imported (may be null)
*|pkName |String | Primary key name (may be null)
*|pkTableName |String | Primary key table name being imported
*|pkColumnName |String | Primary key column name being imported
*
* @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
*/
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`
*
* {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 {Object} [options] The options
* @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 {Function} [cb] The callback function
*/
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
*
* `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 {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) {
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`
*
* {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 {Object} [options] The options
* @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 {Function} [cb] The callback function
*/
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
*
* `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
* Discover and build models from the given owner/modelName synchronously.
*
* @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 {Object} [options] The options
*/
@ -1459,8 +1448,8 @@ DataSource.prototype.discoverAndBuildModelsSync = function (modelName, options)
/**
* Check whether migrations needed
* This method make sense only for sql connectors.
* @param {String[]} [models] A model name or an array of model names. If not present, apply to all models
* This method applies only to SQL connectors.
* @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) {
this.freeze();
@ -1516,8 +1505,8 @@ DataSource.prototype.tableName = function (modelName) {
/**
* Return column name for specified modelName and propertyName
* @param {String} modelName The model name
* @param propertyName The property name
* @returns {String} columnName
* @param {String} propertyName The property name
* @returns {String} columnName The column name.
*/
DataSource.prototype.columnName = function (modelName, 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
* @param {String} modelName The model name
* @param propertyName The property name
* @param {String} propertyName The property name
* @returns {Object} column metadata
*/
DataSource.prototype.columnMetadata = function (modelName, propertyName) {
@ -1625,7 +1614,7 @@ DataSource.prototype.defineForeignKey = function defineForeignKey(className, key
/**
* Close database connection
* @param {Function} cb The callback function. Optional.
* @param {Function} [cb] The callback function. Optional.
*/
DataSource.prototype.disconnect = function disconnect(cb) {
var self = this;
@ -1741,7 +1730,6 @@ DataSource.prototype.enableRemote = function (operation) {
* and disabled operations. To list the operations, call `dataSource.operations()`.
*
*```js
*
* var oracle = loopback.createDataSource({
* connector: require('loopback-connector-oracle'),
* host: '...',
@ -1752,8 +1740,8 @@ DataSource.prototype.enableRemote = function (operation) {
* **Notes:**
*
* - 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).
* - Data sources must enable / disable operations before attaching or creating 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.
* @param {String} operation The operation name
*/
@ -1831,11 +1819,11 @@ DataSource.prototype.isRelational = function () {
return this.connector && this.connector.relational;
};
/**
/*!
* Check if the data source is ready.
* Returns a Boolean value.
* @param obj {Object} ?
* @param args {Object} ?
* @param {Object} obj ?
* @param {Object} args ?
*/
DataSource.prototype.ready = function (obj, args) {
var self = this;