Update docs for loopback-data

docs/connector.md

@@ -1,5 +1,134 @@
-# loopback-connector
+# loopback-data-connector
+
+Loopback connectors provide access to backend systems including databases, REST APIs
+and other services. Connectors are not used directly by application code. We create
+a DataSource to interact with the connector.
+
+For example,
+
+    var DataSource = require('loopback-data').DataSource;
+    var oracleConnector = require('loopback-connector-oracle');
+
+    var ds = new DataSource(oracleConnector, {
+        host : '166.78.158.45',
+        database : 'XE',
+        username : 'strongloop',
+        password : 'str0ng100pjs',
+        debug : true
+    });
+
+The connector argument passed the DataSource constructor can be one of the following:
+
+* The connector module from `require(connectorName)`
+* The full name of the connector module, such as 'loopback-connector-oracle'
+* The short name of the connector module, such as 'oracle', which will be converted to 'loopback-connector-<shortName>'
+* A local module under ./connectors/<connectorName> folder
+
+## Generic connector implmentations
+
+A connector module can implement the following methods to interact with the datasource.
+
+    exports.initialize = function (dataSource, postInit) {
+
+        var settings = dataSource.settings || {}; // The settings is passed in from the dataSource
+
+        var connector = new MyConnector(settings); // Construct the connector instance
+        dataSource.connector = connector; // Attach connector to dataSource
+        connector.dataSource = dataSource; // Hold a reference to dataSource
+
+        /**
+         * Connector instance can have an optional property named as DataAccessObject that provides
+         * static and prototype methods to be mixed into the model constructor. The property can be defined
+         * on the prototype.
+         */
+        connector.DataAccessObject = function {};
+
+        /**
+         * Connector instance can have an optional function to be called to handle data model definitions.
+         * The function can be defined on the prototype too.
+         * @param model The name of the model
+         * @param properties An object for property definitions keyed by propery names
+         * @param settings An object for the model settings
+         */
+        connector.define = function(model, properties, settings) {
+            ...
+        };
+
+        connector.connect(..., postInit); // Run some async code for initialization
+        // process.nextTick(postInit);
+    }
+
+Another way is to directly export the connection function which takes a settings object.
+
+    module.exports = function(settings) {
+        ...
+    }
+
+## CRUD connector implmentations
+
+To support CRUD operations for a model class that is attached to the dataSource/connector, the connector needs to provide
+the following functions:
+
+    /**
+     * Create a new model instance
+     */
+    CRUDConnector.prototype.create = function (model, data, callback) {
+    };
+
+    /**
+     * Save a model instance
+     */
+    CRUDConnector.prototype.save = function (model, data, callback) {
+    };
+
+    /**
+     * Check if a model instance exists by id
+     */
+    CRUDConnector.prototype.exists = function (model, id, callback) {
+    };
+
+    /**
+     * Find a model instance by id
+     */
+    CRUDConnector.prototype.find = function find(model, id, callback) {
+    };
+
+    /**
+     * Update a model instance or create a new model instance if it doesn't exist
+     */
+    CRUDConnector.prototype.updateOrCreate = function updateOrCreate(model, data, callback) {
+    };
+
+    /**
+     * Delete a model instance by id
+     */
+    CRUDConnector.prototype.destroy = function destroy(model, id, callback) {
+    };
+
+    /**
+     * Query model instances by the filter
+     */
+    CRUDConnector.prototype.all = function all(model, filter, callback) {
+    };
+
+    /**
+     * Delete all model instances
+     */
+    CRUDConnector.prototype.destroyAll = function destroyAll(model, callback) {
+    };
+
+    /**
+     * Count the model instances by the where criteria
+     */
+    CRUDConnector.prototype.count = function count(model, callback, where) {
+    };
+
+    /**
+     * Update the attributes for a model instance by id
+     */
+    CRUDConnector.prototype.updateAttributes = function updateAttrs(model, id, data, callback) {
+    };
+
+
 
-Loopback data sources are backed by connectors that communicates with backend systems including databases, REST APIs
-and other services.
 

docs/data-source.md

@@ -1,42 +1,43 @@
-loopback-connector-schema(3) - Everything about schema, data types and model definition.
-====================
+# loopback-data-datasource
+
+Everything about datasource, data types and model definition.
 
 ## DESCRIPTION
 
-Schema is a factory for classes. Schema connected with specific database using
-adapter. 
+DataSource is a factory for model classes. DataSource connected with specific database or other
+backend system using connector.
 
-All classes within single schema shares same adapter type and one database
-connection. But it's possible to use more than one schema to connect with
+All model classes within single datasource shares same connector type and one database
+connection. But it's possible to use more than one datasource to connect with
 different databases.
 
 ## EVENTS
 
-Instances of Schema are event emitters, events supported by default:
+Instances of DataSource are event emitters, events supported by default:
 
 * `.on('connected', function() {})`:
   Fired when db connection established. Params: none.
 * `.on('log', function(msg, duration) {})`:
-  Fired when adapter logged line. Params: String message, Number duration
+  Fired when connector logged line. Params: String message, Number duration
 
 ## USAGE
 
-### Creating schema
+### Creating dataSource
 
-`Schema` constructor available on `loopback-data` module:
+`DataSource` constructor available on `loopback-data` module:
 
-    var Schema = require('loopback-data').Schema;
+    var DataSource = require('loopback-data').DataSource;
 
-Schema constructor accepts two arguments. First argument is adapter. It could be
-adapter name or adapter package:
+DataSource constructor accepts two arguments. First argument is connector. It could be
+connector name or connector package:
 
-    var schemaByAdapterName = new Schema('memory');
-    var schemaByAdapterPackage = new Schema(require('redis'));
+    var dataSourceByConnectorName = new DataSource('memory');
+    var dataSourceByConnectorModule = new DataSource(require('redis'));
 
 ### Settings
 
 Second argument is optional settings. Settings object format and defaults
-depends on specific adapter, but common fields are:
+depends on specific connector, but common fields are:
 
 * `host`:
 Database host
@@ -51,21 +52,21 @@ Database name
 * `debug`:
 Turn on verbose mode to debug db queries and lifecycle
 
-For adapter-specific settings refer to adapter's readme file.
+For connector-specific settings refer to connector's readme file.
 
 ### Connecting to database
 
-Schema connecting to database automatically. Once connection established schema
+DataSource connecting to database automatically. Once connection established dataSource
 object emit 'connected' event, and set `connected` flag to true, but it is not
 necessary to wait for 'connected' event because all queries cached and executed
-when schema emit 'connected' event.
+when dataSource emit 'connected' event.
 
-To disconnect from database server call `schema.disconnect` method. This call
-forwarded to adapter if adapter have ability to connect/disconnect.
+To disconnect from database server call `dataSource.disconnect` method. This call
+forwarded to connector if connector have ability to connect/disconnect.
 
 ### Model definition
 
-To define model schema have single method `schema.define`. It accepts three
+To define model dataSource have single method `dataSource.define`. It accepts three
 argumets:
 
 * **model name**:
@@ -81,14 +82,14 @@ argumets:
 
 Examples of model definition:
 
-    var User = schema.define('User', {
+    var User = dataSource.define('User', {
         email: String,
         password: String,
         birthDate: Date,
         activated: Boolean
     });
 
-    var User = schema.define('User', {
+    var User = dataSource.define('User', {
         email: { type: String, limit: 150, index: true },
         password: { type: String, limit: 50 },
         birthDate: Date,
@@ -103,7 +104,7 @@ Examples of model definition:
 
 ### DB structure syncronization
 
-Schema instance have two methods for updating db structure: automigrate and
+DataSource instance have two methods for updating db structure: automigrate and
 autoupdate.
 
 The `automigrate` method drop table (if exists) and create it again,
@@ -112,15 +113,15 @@ called when migration/update done.
 
 To check if any db changes required use `isActual` method. It accepts single
 `callback` argument, which receive boolean value depending on db state: false if
-db structure outdated, true when schema and db is in sync:
+db structure outdated, true when dataSource and db is in sync:
 
-    schema.isActual(function(err, actual) {
+    dataSource.isActual(function(err, actual) {
         if (!actual) {
-            schema.autoupdate();
+            dataSource.autoupdate();
         }
     });
 
 ## SEE ALSO
 
-loopback-connector-model(3)
-loopback-connector-adapter(3)
+loopback-data-model
+loopback-data-connector

docs/hooks.md

@@ -1,5 +1,6 @@
-loopback-connector-hooks(3) - Hooks and object lifecycle.
-===================
+# loopback-data-hooks
+
+Hooks and object lifecycle.
 
 ## DESCRIPTION
 
@@ -130,5 +131,5 @@ loopback-connector-validations(3) man section.
 
 ## SEE ALSO
 
-loopback-connector-model(3)
-loopback-connector-validations(3)
+loopback-data-model
+loopback-data-validations

docs/index.txt

@@ -1,6 +0,0 @@
-# adapters github
-loopback-connector-mongodb         https://github.com/strongloop/loopback-connector-mongodb
-loopback-connector-oracle         https://github.com/strongloop/loopback-connector-oracle
-loopback-connector-mysql           https://github.com/strongloop/loopback-connector-mysql
-
-# external resources

docs/loopback-data.md

@@ -4,4 +4,4 @@ Loopback-data provides ORM and data connectivity for Node.js. It was initially f
 
 ## SEE ALSO
 
-loopback-connector
+loopback-data-connector

docs/model.md

@@ -1,5 +1,6 @@
-loopback-connector-model(3) - Model methods, features and internals
-===================
+# loopback-data-model
+
+Model methods, features and internals
 
 ## DESCRIPTION
 
@@ -185,7 +186,7 @@ TODO: document
 
 ## SEE ALSO
 
-loopback-connector-schema(3)
-loopback-connector-validations(3)
-loopback-connector-hooks(3)
-loopback-connector-adapter(3)
+loopback-data-datasource
+loopback-data-validations
+loopback-data-hooks
+loopback-data-connector

docs/validations.md

@@ -1,2 +1,18 @@
-loopback-connector-validations(3) - Built-in validators, creating custom validations, syncronous and asyncronous object validation.
-========================
+# loopback-data-validations
+
+Built-in validators, creating custom validations, syncronous and asyncronous object validation.
+
+    // Setup validations
+    User.validatesPresenceOf('name', 'email')
+    User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
+    User.validatesInclusionOf('gender', {in: ['male', 'female']});
+    User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
+    User.validatesNumericalityOf('age', {int: true});
+    User.validatesUniquenessOf('email', {message: 'email is not unique'});
+
+    user.isValid(function (valid) {
+        if (!valid) {
+            user.errors // hash of errors {attr: [errmessage, errmessage, ...], attr: ...}
+        }
+    })
+