Update docs and add asteroid.memory() sugar api

- added asteroid.memory()
 - added default session and email models to user model

README.md

@@ -12,9 +12,13 @@ v0.9.0
  - [Model](#model)
  - [DataSource](#data-source)
  - [Connectors](#connectors)
- - [GeoPoint](#geo-point)
  - [Asteroid Types](#asteroid-types)
+  - [GeoPoint](#geo-point)  
  - [REST Router](#rest-router)
+ - [Bundled Models](#bundled-models)
+  - [User](#user-model)
+  - [Session](#session-model) 
+  - [Email](#email-model)
 
 ## Client API
 
@@ -43,8 +47,10 @@ Create an asteroid application.
 
 Expose a `Model` to remote clients.
 
-    var memory = asteroid.createDataSource({connector: asteroid.Memory});
+    // create a testing data source
+    var memory = asteroid.memory();
     var Color = memory.createModel('color', {name: String});
+    Color.attachTo(memory);
 
     app.model(Color);
     app.use(asteroid.rest());
@@ -794,13 +800,13 @@ Various APIs in Asteroid accept type descriptions (eg. [remote methods](#remote-
  - `Buffer` - a node.js Buffer object
  - [GeoPoint](#geopoint) - an asteroid GeoPoint object. TODO
 
-#### Bundled Models
+## Bundled Models
 
 The Asteroid library is unopinioned in the way you define your app's data and logic. Asteroid also bundles useful pre-built models for common use cases.
 
- - User - _TODO_ register and authenticate users of your app locally or against 3rd party services.
+ - User - register and authenticate users of your app locally or against 3rd party services.
  - Notification - _TODO_ create, store, schedule and send push notifications to your app users.
- - Email - _TODO_ schedule and send emails to your app users using smtp or 3rd party services.
+ - Email - send emails to your app users using smtp or 3rd party services.
  - Job - _TODO_ schedule arbitrary code to run at a given time.
 
 Defining a model with `asteroid.createModel()` is really just extending the base `asteroid.Model` type using `asteroid.Model.extend()`. The bundled models extend from the base `asteroid.Model` allowing you to extend them arbitrarily.
@@ -813,15 +819,38 @@ Register and authenticate users of your app locally or against 3rd party service
 
 Extend a vanilla Asteroid model using the built in User model.
 
+    // create a data source
+    var memory = asteroid.memory();
+ 
     // define a User model
     var User = asteroid.User.extend('user');
   
     // attach to the memory connector
     User.attachTo(memory);
     
+    // also attach the session model to a data source
+    User.session.attachTo(memory);
+    
     // expose over the app's api
     app.model(User);
     
+**Note:** By default the `asteroid.User` model uses the `asteroid.Session` model to persist sessions. You can change this by setting the `session` property.
+
+**Note:** You must attach both the `User` and `User.session` model's to a data source!
+
+    // define a custom session model    
+    var MySession = asteroid.Session.extend('my-session');
+    
+    // define a custom User model
+    var User = asteroid.User.extend('user');
+    
+    // use the custom session model
+    User.session = MySession;
+    
+    // attaching to 
+    
+    
+    
 #### User Creation
 
 Create a user like any other model.
@@ -943,6 +972,24 @@ Confirm the password reset.
       console.log(err || 'your password was reset');
     });
 
+
+### Session Model
+
+Identify users by creating sessions when they connect to your asteroid app. By default the `asteroid.User` model uses the `asteroid.Session` model to persist sessions. You can change this by setting the `session` property.
+
+    // define a custom session model    
+    var MySession = asteroid.Session.extend('my-session');
+    
+    // define a custom User model
+    var User = asteroid.User.extend('user');
+    
+    // use the custom session model
+    User.session = MySession;
+    
+    // attach both Session and User to a data source
+    User.attachTo(asteroid.memory());
+    MySession.attachTo(asteroid.memory());
+    
 ### Email Model
 
 Send emails from your asteroid app.

lib/asteroid.js

@@ -274,6 +274,28 @@ asteroid.template = function (file) {
   return ejs.compile(str);
 }
 
+/**
+ * Get an in-memory data source. Use one if it already exists.
+ * 
+ * @param {String} [name] The name of the data source. If not provided, the `'default'` is used.
+ */
+
+asteroid.memory = function (name) {
+  name = name || 'default';
+  var memory = (
+    this._memoryDataSources
+    || (this._memoryDataSources = {})
+  )[name];
+  
+  if(!memory) {
+    memory = this._memoryDataSources[name] = asteroid.createDataSource({
+      connector: asteroid.Memory
+    });
+  }
+  
+  return memory;
+}
+
 /*
  * Built in models / services
  */

lib/models/user.js

@@ -82,7 +82,7 @@ User.login = function (credentials, fn) {
   });
   
   function createSession(user, fn) {
-    var Session = UserCtor.settings.session || asteroid.Session;
+    var Session = UserCtor.session;
     
     Session.create({uid: user.id}, function (err, session) {
       if(err) {
@@ -170,7 +170,7 @@ User.prototype.verify = function (options, fn) {
 
   
   // Email model
-  var Email = options.mailer || this.constructor.settings.email || asteroid.Email;
+  var Email = options.mailer || this.constructor.email || asteroid.Email;
   
   crypto.randomBytes(64, function(err, buf) {
     if(err) {
@@ -234,7 +234,7 @@ User.confirm = function (uid, token, redirect, fn) {
 }
 
 /**
- * Override the extend method to setup any extended user models.
+ * Setup an extended user model.
  */
 
 User.setup = function () {
@@ -283,6 +283,10 @@ User.setup = function () {
     });
   });
   
+  // default models
+  UserModel.email = require('./email');
+  UserModel.session = require('./session');
+  
   return UserModel;
 }
 

test/asteroid.test.js

@@ -31,4 +31,18 @@ describe('asteroid', function() {
       assert.equal(Product.stats.shared, true);
     });
   });
+  
+  describe('asteroid.memory([name])', function(){
+    it('Get an in-memory data source. Use one if it already exists.', function() {
+      var memory = asteroid.memory();
+      assertValidDataSource(memory);
+      var m1 = asteroid.memory();
+      var m2 = asteroid.memory('m2');
+      var alsoM2 = asteroid.memory('m2');
+      
+      assert(m1 === memory);
+      assert(m1 !== m2);
+      assert(alsoM2 === m2);
+    });
+  });
 });

test/data-source.test.js

@@ -5,6 +5,8 @@ describe('DataSource', function() {
     memory = asteroid.createDataSource({
       connector: asteroid.Memory
     });
+    
+    assertValidDataSource(memory);
   });
 
   describe('dataSource.createModel(name, properties, settings)', function() {

test/support.js

@@ -19,8 +19,8 @@ assertValidDataSource = function (dataSource) {
   assert.isFunc(dataSource, 'createModel');
   assert.isFunc(dataSource, 'discoverModelDefinitions');
   assert.isFunc(dataSource, 'discoverSchema');
-  assert.isFunc(dataSource, 'enable');
-  assert.isFunc(dataSource, 'disable');
+  assert.isFunc(dataSource, 'enableRemote');
+  assert.isFunc(dataSource, 'disableRemote');
   assert.isFunc(dataSource, 'defineOperation');
   assert.isFunc(dataSource, 'operations');
 }

test/user.test.js

@@ -6,8 +6,8 @@ var userMemory = asteroid.createDataSource({
   connector: asteroid.Memory
 });
 asteroid.User.attachTo(userMemory);
-asteroid.Session.attachTo(userMemory);
-asteroid.Email.setup({transports: [{type: 'STUB'}]});
+asteroid.User.session.attachTo(userMemory);
+asteroid.User.email.setup({transports: [{type: 'STUB'}]});
 
 describe('User', function(){