Merge pull request #1333 from strongloop/api-doc-refactor

Datasource documentation tune-up
This commit is contained in:
Loay 2017-04-25 16:28:54 -04:00 committed by GitHub
commit bf7ea4caed
1 changed files with 133 additions and 60 deletions

View File

@ -264,8 +264,12 @@ DataSource._resolveConnector = function(name, loader) {
};
/**
* Connect to the data source
* Connect to the data source.
* If no callback is provided, it will return a Promise.
* Emits the 'connect' event.
* @param callback
* @returns {Promise}
* @emits connected
*/
DataSource.prototype.connect = function(callback) {
callback = callback || utils.createPromiseCallback();
@ -439,9 +443,14 @@ function isModelDataSourceAttached(model) {
}
/*!
* Define scopes for the model class from the scopes object
* @param modelClass
* @param scopes
* Define scopes for the model class from the scopes object. See
* [scopes](./Model-definition-JSON-file.html#scopes) for more information on
* scopes and valid options objects.
* @param {Object} modelClass - The model class that corresponds to the model
* definition that will be enhanced by the provided scopes.
* @param {Object} scopes A key-value collection of names and their object
* definitions
* @property options The options defined on the scope object.
*/
DataSource.prototype.defineScopes = function(modelClass, scopes) {
if (scopes) {
@ -452,9 +461,12 @@ DataSource.prototype.defineScopes = function(modelClass, scopes) {
};
/*!
* Define relations for the model class from the relations object
* @param modelClass
* @param relations
* Define relations for the model class from the relations object. See
* [relations](./Model-definition-JSON-file.html#relations) for more information.
* @param {Object} modelClass - The model class that corresponds to the model
* definition that will be enhanced by the provided relations.
* @param {Object} relations A key-value collection of relation names and their
* object definitions.
*/
DataSource.prototype.defineRelations = function(modelClass, relations) {
var self = this;
@ -548,9 +560,11 @@ function isValidRelationName(relationName) {
}
/*!
* Set up the data access functions from the data source
* @param {Model} modelClass The model class
* @param {Object} settings The settings object
* Set up the data access functions from the data source. Each data source will
* expose a data access object (DAO), which will be mixed into the modelClass.
* @param {Model} modelClass The model class that will receive DAO mixins.
* @param {Object} settings The settings object; typically allows any settings
* that would be valid for a typical Model object.
*/
DataSource.prototype.setupDataAccess = function(modelClass, settings) {
if (this.connector) {
@ -643,7 +657,7 @@ DataSource.prototype.setupDataAccess = function(modelClass, settings) {
* @param {String} className Name of the model to create.
* @param {Object} properties Hash of model properties in format `{property: Type, property2: Type2, ...}` or `{property: {type: Type}, property2: {type: Type2}, ...}`
* @options {Object} properties Other configuration options. This corresponds to the options key in the config object.
*
* @param {Object} settings A settings object that would typically be used for Model objects.
*/
DataSource.prototype.createModel =
@ -731,23 +745,35 @@ DataSource.prototype.mixin = function(ModelCtor) {
};
/**
* See ModelBuilder.getModel
*
* FIXME: Deprecation notice for 4.x?
* See [ModelBuilder.getModel](http://apidocs.strongloop.com/loopback-datasource-juggler/#modelbuilder-prototype-getmodel)
* for details.
*/
DataSource.prototype.getModel = function(name, forceCreate) {
return this.modelBuilder.getModel(name, forceCreate);
};
/**
* // FIXME: Make this a link to ModelBuilder.getModelDefinition's docs!
* // FIXME: Deprecation notice for 4.x?
* See ModelBuilder.getModelDefinition
* See [ModelBuilder.getModelDefinition](http://apidocs.strongloop.com/loopback-datasource-juggler/#modelbuilder-prototype-getmodeldefinition)
* for details.
*/
DataSource.prototype.getModelDefinition = function(name) {
return this.modelBuilder.getModelDefinition(name);
};
/**
* Get the data source types
* @returns {String[]} The data source type, such as ['db', 'nosql', 'mongodb'],
* ['rest'], or ['db', 'rdbms', 'mysql']
* Get the data source types collection.
* @returns {String[]} The data source type array.
* For example, ['db', 'nosql', 'mongodb'] would be represent a datasource of
* type 'db', with a subtype of 'nosql', and would use the 'mongodb' connector.
*
* Alternatively, ['rest'] would be a different type altogether, and would have
* no subtype.
* FIXME: Deprecation notice for 4.x?
*/
DataSource.prototype.getTypes = function() {
var getTypes = this.connector && this.connector.getTypes;
@ -760,7 +786,7 @@ DataSource.prototype.getTypes = function() {
/**
* Check the data source supports the specified types.
* @param {String} types Type name or an array of type names. Can also be array of Strings.
* @param {String|String[]} types Type name or an array of type names.
* @returns {Boolean} true if all types are supported by the data source
*/
DataSource.prototype.supportTypes = function(types) {
@ -782,8 +808,12 @@ DataSource.prototype.supportTypes = function(types) {
/**
* Attach an existing model to a data source.
*
* @param {Function} modelClass The model constructor
* This will mixin all of the data access object functions (DAO) into your
* modelClass definition.
* @param {Function} modelClass The model constructor that will be enhanced by
* DAO mixins.
* FIXME: In future versions, this will not maintain a strict 1:1 relationship
* between datasources and model classes.
*/
DataSource.prototype.attach = function(modelClass) {
@ -808,11 +838,13 @@ DataSource.prototype.attach = function(modelClass) {
};
/**
* Define single property named `prop` on `model`
*
* Define a property with name `prop` on a target `model`. See
* [Properties](./Model-definition-JSON-file.html#properties) for more information
* regarding valid options for `params`.
* FIXME: Deprecate for 4.0?
* @param {String} model Name of model
* @param {String} prop Name of property
* @param {Object} params Property settings
* @param {Property} params Property settings
*/
DataSource.prototype.defineProperty = function(model, prop, params) {
this.modelBuilder.defineProperty(model, prop, params);
@ -824,15 +856,18 @@ DataSource.prototype.defineProperty = function(model, prop, params) {
};
/**
* Drop each model table and re-create.
* This method applies only to database connectors. For MongoDB, it drops and creates indexes.
* Drop schema objects such as tables, indexes, views, triggers, etc that correspond
* to model definitions attached to this DataSource instance, specified by the `models` parameter.
*
* **WARNING**: Calling this function deletes all data! Use `autoupdate()` to preserve data.
* **WARNING**: In many situations, this will destroy data! `autoupdate()` will attempt to preserve
* data while updating the schema on your target DataSource, but this is not guaranteed to be safe.
*
* @param {String} model Model to migrate. If not present, apply to all models. Can also be an array of Strings.
* Please check the documentation for your specific connector(s) for a detailed breakdown of
* behaviors for automigrate!
*
* @param {String|String[]} [models] Model(s) to migrate. If not present, apply to all models.
* @param {Function} [callback] Callback function. Optional.
*
*/
DataSource.prototype.automigrate = function(models, cb) {
this.freeze();
@ -886,7 +921,13 @@ DataSource.prototype.automigrate = function(models, cb) {
* Update existing database tables.
* 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.
* **WARNING**: `autoupdate()` will attempt to preserve data while updating the
* schema on your target DataSource, but this is not guaranteed to be safe.
*
* Please check the documentation for your specific connector(s) for a detailed breakdown of
* behaviors for automigrate!*
*
* @param {String|String[]} [models] Model(s) to migrate. If not present, apply to all models.
* @param {Function} [cb] The callback function
*/
DataSource.prototype.autoupdate = function(models, cb) {
@ -949,7 +990,7 @@ DataSource.prototype.autoupdate = function(models, cb) {
* @property {Boolean} views If true, include views; if false, only tables.
* @property {Number} limit Page size
* @property {Number} offset Starting index
*
* @returns {ModelDefinition[]}
*/
DataSource.prototype.discoverModelDefinitions = function(options, cb) {
this.freeze();
@ -970,13 +1011,14 @@ DataSource.prototype.discoverModelDefinitions = function(options, cb) {
};
/**
* FIXME Deprecate/remove this for LB 4.0?
* 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 {*}
* @returns {ModelDefinition[]}
*/
DataSource.prototype.discoverModelDefinitionsSync = function(options) {
this.freeze();
@ -1001,11 +1043,14 @@ DataSource.prototype.discoverModelDefinitionsSync = function(options) {
*|dataPrecision | Number | Numeric data precision|
*|dataScale |Number | Numeric data scale|
*|nullable |Boolean | If true, then the data can be null|
*
* See [Properties](./Model-definition-JSON-file.html#properties) for more
* details on the Property return type.
* @param {String} modelName The table/view name
* @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} cb Callback function. Optional
* @callback cb
* @returns {Promise} A promise that returns an array of Properties (Property[])
*
*/
DataSource.prototype.discoverModelProperties = function(modelName, options, cb) {
@ -1027,6 +1072,7 @@ DataSource.prototype.discoverModelProperties = function(modelName, options, cb)
};
/**
* FIXME: Deprecate this for LB 4.x?
* The synchronous version of discoverModelProperties
* @param {String} modelName The table/view name
* @param {Object} options The options
@ -1051,11 +1097,13 @@ DataSource.prototype.discoverModelPropertiesSync = function(modelName, options)
*| 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)
*
* See [ID Properties](./Model-definition-JSON-file.html#id-properties) for more
* information.
* @param {String} modelName The model name
* @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function
* @returns {Promise} A promise with an array of Primary Keys (Property[])
*/
DataSource.prototype.discoverPrimaryKeys = function(modelName, options, cb) {
this.freeze();
@ -1076,10 +1124,11 @@ DataSource.prototype.discoverPrimaryKeys = function(modelName, options, cb) {
};
/**
* FIXME: Obsolete?
* The synchronous version of discoverPrimaryKeys
* @param {String} modelName The model name
* @options {Object} options The options
* @property {String} owner|schema The database owner orschema
* @property {String} owner|schema The database owner or schema
* @returns {*}
*/
DataSource.prototype.discoverPrimaryKeysSync = function(modelName, options) {
@ -1106,11 +1155,13 @@ DataSource.prototype.discoverPrimaryKeysSync = function(modelName, options) {
*|pkName |String | Primary key name (may be null)
*|pkTableName |String | Primary key table name being imported
*|pkColumnName |String | Primary key column name being imported
*
* See [Relations](/Model-definition-JSON-file.html#relations) for more
* information.
* @param {String} modelName The model name
* @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function
* @returns {Promise} A Promise with an array of foreign key relations.
*
*/
DataSource.prototype.discoverForeignKeys = function(modelName, options, cb) {
@ -1132,6 +1183,7 @@ DataSource.prototype.discoverForeignKeys = function(modelName, options, cb) {
};
/**
* FIXME: Obsolete?
* The synchronous version of discoverForeignKeys
*
* @param {String} modelName The model name
@ -1163,11 +1215,14 @@ DataSource.prototype.discoverForeignKeysSync = function(modelName, options) {
*|pkName |String | Primary key name (may be null)
*|pkTableName |String | Primary key table name being imported
*|pkColumnName |String | Primary key column name being imported
* See [Relations](/Model-definition-JSON-file.html#relations) for more
* information.
*
* @param {String} modelName The model name
* @options {Object} options The options
* @property {String} owner|schema The database owner or schema
* @param {Function} [cb] The callback function
* @returns {Promise} A Promise with an array of exported foreign key relations.
*/
DataSource.prototype.discoverExportedForeignKeys = function(modelName, options, cb) {
this.freeze();
@ -1188,6 +1243,7 @@ DataSource.prototype.discoverExportedForeignKeys = function(modelName, options,
};
/**
* FIXME: Obsolete?
* The synchronous version of discoverExportedForeignKeys
* @param {String} modelName The model name
* @param {Object} options The options
@ -1275,11 +1331,13 @@ function fromDBName(dbName, camelCase) {
* }
* ```
*
* @param {String} modelName The model name
* @param {Object} [options] The options
* @param {String} tableName The name of the table to discover.
* @options {Object} [options] An options object typically used for Relations.
* See [Relations](./Model-definition-JSON-file.html#relations) for more information.
* @param {Function} [cb] The callback function
* @returns {Promise} A promise object that resolves to a single schema.
*/
DataSource.prototype.discoverSchema = function(modelName, options, cb) {
DataSource.prototype.discoverSchema = function(tableName, options, cb) {
options = options || {};
if (!cb && 'function' === typeof options) {
@ -1291,7 +1349,7 @@ DataSource.prototype.discoverSchema = function(modelName, options, cb) {
cb = cb || utils.createPromiseCallback();
this.discoverSchemas(modelName, options, function(err, schemas) {
this.discoverSchemas(tableName, options, function(err, schemas) {
if (err || !schemas) {
cb && cb(err, schemas);
return;
@ -1305,17 +1363,18 @@ DataSource.prototype.discoverSchema = function(modelName, options, cb) {
};
/**
* Discover schema from a given modelName/view.
* Discover schema from a given tableName/viewName.
*
* @param {String} modelName The model name.
* @param {String} tableName The table 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
* @returns {Promise} A promise object that resolves to an array of schemas.
*/
DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
DataSource.prototype.discoverSchemas = function(tableName, options, cb) {
options = options || {};
if (!cb && 'function' === typeof options) {
@ -1352,17 +1411,17 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
if (this.connector.discoverSchemas) {
// Delegate to the connector implementation
this.connector.discoverSchemas(modelName, options, cb);
this.connector.discoverSchemas(tableName, options, cb);
return cb.promise;
}
var tasks = [
this.discoverModelProperties.bind(this, modelName, options),
this.discoverPrimaryKeys.bind(this, modelName, options)];
this.discoverModelProperties.bind(this, tableName, options),
this.discoverPrimaryKeys.bind(this, tableName, options)];
var followingRelations = options.associations || options.relations;
if (followingRelations) {
tasks.push(this.discoverForeignKeys.bind(this, modelName, options));
tasks.push(this.discoverForeignKeys.bind(this, tableName, options));
}
async.parallel(tasks, function(err, results) {
@ -1373,7 +1432,7 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
var columns = results[0];
if (!columns || columns.length === 0) {
cb(new Error(g.f('Table \'%s\' does not exist.', modelName)));
cb(new Error(g.f('Table \'%s\' does not exist.', tableName)));
return cb.promise;
}
@ -1389,7 +1448,7 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
}
var schema = {
name: nameMapper('table', modelName),
name: nameMapper('table', tableName),
options: {
idInjection: false, // DO NOT add id property
},
@ -1398,7 +1457,7 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
schema.options[dbType] = {
schema: columns[0].owner,
table: modelName,
table: tableName,
};
columns.forEach(function(item) {
@ -1433,7 +1492,7 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
// Add current modelName to the visited tables
options.visited = options.visited || {};
var schemaKey = columns[0].owner + '.' + modelName;
var schemaKey = columns[0].owner + '.' + tableName;
if (!options.visited.hasOwnProperty(schemaKey)) {
if (self.settings.debug) {
debug('Adding schema for ' + schemaKey);
@ -1507,13 +1566,14 @@ DataSource.prototype.discoverSchemas = function(modelName, options, cb) {
/**
* Discover schema from a given table/view synchronously
*
* FIXME Obsolete?
* @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.
* @returns {Array<Object>} An array of schema definition objects.
*/
DataSource.prototype.discoverSchemasSync = function(modelName, options) {
var self = this;
@ -1660,6 +1720,8 @@ DataSource.prototype.discoverSchemasSync = function(modelName, options) {
* @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
* @returns {Promise} A Promise object that resolves with a map of model
* constructors, keyed by model name
*/
DataSource.prototype.discoverAndBuildModels = function(modelName, options, cb) {
var self = this;
@ -1689,7 +1751,7 @@ DataSource.prototype.discoverAndBuildModels = function(modelName, options, cb) {
/**
* Discover and build models from the given owner/modelName synchronously.
*
* FIXME: Obsolete?
* @param {String} modelName The model name.
* @options {Object} [options] Options; see below.
* @property {String} owner|schema Database owner or schema name.
@ -1699,6 +1761,7 @@ DataSource.prototype.discoverAndBuildModels = function(modelName, options, cb) {
* @param {String} modelName The model name
* @param {Object} [options] The options
* @returns {Object} A map of model constructors, keyed by model name
*/
DataSource.prototype.discoverAndBuildModelsSync = function(modelName, options) {
options = options || {};
@ -1725,7 +1788,7 @@ DataSource.prototype.discoverAndBuildModelsSync = function(modelName, options) {
* @param {String} name Name of the model
* @param {Object} json The json object representing a model instance
* @param {Object} options Options
* @returns {*}
* @returns {Model} A Model class
*/
DataSource.prototype.buildModelFromInstance = function(name, json, options) {
// Introspect the JSON document to generate a schema
@ -1736,9 +1799,11 @@ DataSource.prototype.buildModelFromInstance = function(name, json, options) {
};
/**
* Check whether migrations needed
* This method applies only to SQL connectors.
* Check whether or not migrations are required for the database schema to match
* the Model definitions attached to the DataSource.
* Note: 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.
* @returns {Boolean} Whether or not migrations are required.
*/
DataSource.prototype.isActual = function(models, cb) {
this.freeze();
@ -1759,7 +1824,7 @@ DataSource.prototype.isActual = function(models, cb) {
/**
* Log benchmarked message. Do not redefine this method, if you need to grab
* chema logs, use `dataSource.on('log', ...)` emitter event
* schema logs, use `dataSource.on('log', ...)` emitter event
*
* @private used by connectors
*/
@ -1770,6 +1835,9 @@ DataSource.prototype.log = function(sql, t) {
/**
* Freeze dataSource. Behavior depends on connector
* REVIEW: Raymond, can you give example of what behavior(s) are typically
* expected here? I understand that it's connector-specific, but surely there's
* a common goal here.
*/
DataSource.prototype.freeze = function freeze() {
if (!this.connector) {
@ -1784,8 +1852,9 @@ DataSource.prototype.freeze = function freeze() {
};
/**
* Return table name for specified `modelName`
* @param {String} modelName The model name
* Return table name for specified `modelName`.
* @param {String} modelName The model name.
* @returns {String} The table name.
*/
DataSource.prototype.tableName = function(modelName) {
return this.getModelDefinition(modelName).tableName(this.connector.name);
@ -1918,7 +1987,8 @@ DataSource.prototype.defineForeignKey = function defineForeignKey(className, key
};
/**
* Close database connection
* Close connection to the DataSource.
* REVIEW: Why is this not Promisified like the connect function?
* @param {Function} [cb] The callback function. Optional.
*/
DataSource.prototype.disconnect = function disconnect(cb) {
@ -1939,7 +2009,7 @@ DataSource.prototype.disconnect = function disconnect(cb) {
/**
* Copy the model from Master.
* @param {Function} Master The model constructor
* @returns {Function} The copy of the model constructor
* @returns {Model} A copy of the Model object constructor
*
* @private
*/
@ -1979,7 +2049,7 @@ DataSource.prototype.copyModel = function copyModel(Master) {
};
/**
*
* Run a transaction against the DataSource.
* @returns {EventEmitter}
* @private
*/
@ -2124,9 +2194,10 @@ DataSource.prototype.isRelational = function() {
return this.connector && this.connector.relational;
};
/*!
/**
* Check if the data source is ready.
* Returns a Boolean value.
* REVIEW: What is "obj" supposed to represent?
* @param {Object} obj ?
* @param {Object} args ?
*/
@ -2217,6 +2288,8 @@ DataSource.prototype.ping = function(cb) {
/**
* Define a hidden property
* REVIEW: Why is a hidden property not writable or enumerable? What
* purpose does it serve?
* @param {Object} obj The property owner
* @param {String} key The property name
* @param {Mixed} value The default value