Merge pull request #58 from strongloop/lb-1.2-project

1.2 app.boot()

docs/api.md

@@ -21,24 +21,158 @@ app.listen(3000);
 > - see [express docs](http://expressjs.com/api.html) for details
 > - supports [express / connect middleware](http://expressjs.com/api.html#middleware) 
 
-#### app.model(Model)
+#### app.boot([options])
 
-Expose a `Model` to remote clients.
+Initialize an application from an options object or a set of JSON and JavaScript files.
+
+**What happens during an app _boot_?**
+
+1. **DataSources** are created from an `options.dataSources` object or `datasources.json` in the current directory
+2. **Models** are created from an `options.models` object or `models.json` in the current directory
+3. Any JavaScript files in the `./models` directory are loaded with `require()`.
+
+**Options**
+
+ - `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files
+ - `models` - _optional_ - an object containing `Model` definitions
+ - `dataSources` - _optional_ - an object containing `DataSource` definitions
+
+> **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple files may result
+> in models being **undefined** due to race conditions. To avoid this when using `app.boot()`
+> make sure all models are passed as part of the `models` definition.
+
+<a name="model-definition"></a>
+**Model Definitions**
+
+The following is an example of an object containing two `Model` definitions: "location" and "inventory".
 
 ```js
-// create a testing data source
-var memory = loopback.memory();
-var Color = memory.createModel('color', {name: String});
+{
+  "dealership": {
+    // a reference, by name, to a dataSource definition
+    "dataSource": "my-db",
+    // the options passed to Model.extend(name, properties, options)
+    "options": {
+      "relationships": {
+        "cars": {
+          "type": "hasMany",
+          "model": "Car",
+          "foreignKey": "dealerId"  
+        }
+      },
+      "remoteMethods": {
+        "nearby": {
+          "description": "Find nearby locations around the geo point",
+          "accepts": [
+            {"arg": "here", "type": "GeoPoint", "required": true, "description": "geo location (lat & lng)"}
+          ],
+          "returns": {"arg": "locations", "root": true}
+        }
+      }
+    },
+    // the properties passed to Model.extend(name, properties, options)
+    "properties": {
+      "id": {"id": true},
+      "name": "String",
+      "zip": "Number",
+      "address": "String"
+    }
+  },
+  "car": {
+    "dataSource": "my-db"
+    "properties": {
+      "id": {
+        "type": "String",
+        "required": true,
+        "id": true
+      },
+      "make": {
+        "type": "String",
+        "required": true
+      },
+      "model": {
+        "type": "String",
+        "required": true
+      }
+    }
+  }
+}
+```
 
-app.model(Color);
-app.use(loopback.rest());
+**Model Definition Properties**
+
+ - `dataSource` - **required** - a string containing the name of the data source definition to attach the `Model` to
+ - `options` - _optional_ - an object containing `Model` options
+ - `properties` _optional_ - an object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language)
+
+**DataSource Definition Properties**
+ 
+ - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
+
+#### app.model(name, definition)
+
+Define a `Model` and export it for use by remote clients.
+
+```js
+// declare a DataSource
+app.boot({
+  dataSources: {
+    db: {
+      connector: 'mongodb',
+      url: 'mongodb://localhost:27015/my-database-name'
+    }
+  }
+});
+
+// describe a model
+var modelDefinition = {dataSource: 'db'};
+
+// create the model
+var Product = app.model('product', modelDefinition);
+
+// use the model api
+Product.create({name: 'pencil', price: 0.99}, console.log);
 ```
     
 > **Note** - this will expose all [shared methods](#shared-methods) on the model.
 
+You may also export an existing `Model` by calling `app.model(Model)` like the example below.
+
+#### app.models.MyModel
+
+All models are avaialbe from the `loopback.models` object. In the following 
+example the `Product` and `CustomerReceipt` models are accessed using
+the `models` object.
+
+> **NOTE:** you must call `app.boot()` in order to build the app.models object.
+
+```js
+var loopback = require('loopback');
+var app = loopback();
+app.boot({
+  dataSources: {
+    db: {connector: 'memory'}
+  }
+});
+app.model('product', {dataSource: 'db'});
+app.model('customer-receipt', {dataSource: 'db'});
+
+// available based on the given name
+var Product = app.models.Product;
+
+// also available as camelCase
+var product = app.models.product;
+
+// multi-word models are avaiable as pascal cased
+var CustomerReceipt = app.models.CustomerReceipt;
+
+// also available as camelCase
+var customerReceipt = app.models.customerReceipt;
+```
+
 #### app.models()
 
-Get the app's exposed models.
+Get the app's exported models. Only models defined using `app.model()` will show up in this list.
 
 ```js
 var models = app.models();

lib/application.js

@@ -5,8 +5,11 @@
 var DataSource = require('loopback-datasource-juggler').DataSource
   , ModelBuilder = require('loopback-datasource-juggler').ModelBuilder
   , assert = require('assert')
+  , fs = require('fs')
   , RemoteObjects = require('strong-remoting')
-  , swagger = require('strong-remoting/ext/swagger');
+  , swagger = require('strong-remoting/ext/swagger')
+  , stringUtils = require('underscore.string')
+  , path = require('path');
 
 /**
  * Export the app prototype.
@@ -52,12 +55,28 @@ app._models = [];
  * @param Model {Model}
  */
 
-app.model = function (Model) {
+app.model = function (Model, config) {
+  if(arguments.length === 1) {
+    assert(typeof Model === 'function', 'app.model(Model) => Model must be a function / constructor');
+    assert(Model.pluralModelName, 'Model must have a "pluralModelName" property');
     this.remotes().exports[Model.pluralModelName] = Model;
     this._models.push(Model);
     Model.shared = true;
     Model.app = this;
     Model.emit('attached', this);
+    return;
+  }
+  var modelName = Model;
+  assert(typeof modelName === 'string', 'app.model(name, config) => "name" name must be a string');
+
+  Model =
+  this.models[modelName] =
+  this.models[classify(modelName)] =
+  this.models[camelize(modelName)] = modelFromConfig(modelName, config, this);
+
+  this.model(Model);
+
+  return Model;
 }
 
 /**
@@ -68,6 +87,16 @@ app.models = function () {
   return this._models;
 }
 
+/**
+ * Define a DataSource.
+ */
+
+app.dataSource = function (name, config) {
+  this.dataSources[name] =
+  this.dataSources[classify(name)] =
+  this.dataSources[camelize(name)] = dataSourcesFromConfig(config);
+}
+
 /**
  * Get all remote objects.
  */
@@ -120,3 +149,204 @@ app.handler = function (type) {
   return handler;
 }
 
+/**
+ * An object to store dataSource instances.
+ */
+
+app.dataSources = app.datasources = {};
+
+/**
+ * Initialize the app using JSON and JavaScript files.
+ *
+ * @throws {Error} If config is not valid
+ * @throws {Error} If boot fails
+ */
+
+app.boot = function(options) {
+  options = options || {};
+
+  if(typeof options === 'string') {
+    options = {appRootDir: options};
+  }
+  var app = this;
+  var appRootDir = options.appRootDir = options.appRootDir || process.cwd();
+  var ctx = {};
+  var appConfig = options.app;
+  var modelConfig = options.models;
+  var dataSourceConfig = options.dataSources;
+
+  if(!appConfig) {
+    appConfig = tryReadConfig(appRootDir, 'app') || {};
+  }
+  if(!modelConfig) {
+    modelConfig = tryReadConfig(appRootDir, 'models') || {};
+  }
+  if(!dataSourceConfig) {
+    dataSourceConfig = tryReadConfig(appRootDir, 'datasources') || {};
+  }
+
+  assertIsValidConfig('app', appConfig);
+  assertIsValidConfig('model', modelConfig);
+  assertIsValidConfig('data source', dataSourceConfig);
+
+  if(appConfig.host !== undefined) {
+    assert(typeof appConfig.host === 'string', 'app.host must be a string');
+    app.set('host', appConfig.host);
+  }
+
+  if(appConfig.port !== undefined) {
+    var portType = typeof appConfig.port;
+    assert(portType === 'string' || portType === 'number', 'app.port must be a string or number');
+    app.set('port', appConfig.port);
+  }
+
+  // instantiate data sources
+  forEachKeyedObject(dataSourceConfig, function(key, obj) {
+    app.dataSource(key, obj);
+  });
+
+  // instantiate models
+  forEachKeyedObject(modelConfig, function(key, obj) {
+    app.model(key, obj);
+  });
+
+  // require directories
+  var requiredModels = requireDir(path.join(appRootDir, 'models'));
+}
+
+function assertIsValidConfig(name, config) {
+  if(config) {
+    assert(typeof config === 'object', name + ' config must be a valid JSON object');  
+  }
+}
+
+function forEachKeyedObject(obj, fn) {
+  if(typeof obj !== 'object') return;
+
+  Object.keys(obj).forEach(function(key) {
+    fn(key, obj[key]);
+  });
+}
+
+function classify(str) {
+  return stringUtils.classify(str);
+}
+
+function camelize(str) {
+  return stringUtils.camelize(str);
+}
+
+function dataSourcesFromConfig(config) {
+  var connectorPath;
+
+  assert(typeof config === 'object', 
+    'cannont create data source without config object');
+
+  if(typeof config.connector === 'string') {
+    connectorPath = path.join(__dirname, 'connectors', config.connector+'.js');
+
+    if(fs.existsSync(connectorPath)) {
+      config.connector = require(connectorPath);
+    }
+  }
+
+  return require('./loopback').createDataSource(config);
+}
+
+function modelFromConfig(name, config, app) {
+  var ModelCtor = require('./loopback').createModel(name, config.properties, config.options);
+  var dataSource = app.dataSources[config.dataSource];
+
+  assert(isDataSource(dataSource), name + ' is referencing a dataSource that does not exist: "'+ config.dataSource +'"');
+
+  ModelCtor.attachTo(dataSource);
+  return ModelCtor;
+}
+
+function requireDir(dir, basenames) {
+  assert(dir, 'cannot require directory contents without directory name');
+
+  var requires = {};
+
+  if (arguments.length === 2) {
+    // if basenames argument is passed, explicitly include those files
+    basenames.forEach(function (basename) {
+      var filepath = Path.resolve(Path.join(dir, basename));
+      requires[basename] = tryRequire(filepath);
+    });
+  } else if (arguments.length === 1) {
+    // if basenames arguments isn't passed, require all javascript
+    // files (except for those prefixed with _) and all directories
+
+    var files = tryReadDir(dir);
+
+    // sort files in lowercase alpha for linux
+    files.sort(function (a,b) {
+      a = a.toLowerCase();
+      b = b.toLowerCase();
+
+      if (a < b) {
+        return -1;
+      } else if (b < a) {
+        return 1;
+      } else {
+        return 0;
+      }
+    });
+
+    files.forEach(function (filename) {
+      // ignore index.js and files prefixed with underscore
+      if ((filename === 'index.js') || (filename[0] === '_')) { return; }
+
+      var filepath = path.resolve(path.join(dir, filename));
+      var ext = path.extname(filename);
+      var stats = fs.statSync(filepath);
+
+      // only require files supported by require.extensions (.txt .md etc.)
+      if (stats.isFile() && !(ext in require.extensions)) { return; }
+
+      var basename = path.basename(filename, ext);
+
+      requires[basename] = tryRequire(filepath);
+    });
+
+  }
+
+  return requires;
+};
+
+function tryRequire(modulePath) {
+  try {
+    return require.apply(this, arguments);
+  } catch(e) {
+    console.error('failed to require "%s"', modulePath);
+    throw e;
+  }
+}
+
+function tryReadDir() {
+  try {
+    return fs.readdirSync.apply(fs, arguments);
+  } catch(e) {
+    return [];
+  }
+}
+
+function isModelCtor(obj) {
+  return typeof obj === 'function' && obj.modelName && obj.name === 'ModelCtor';
+}
+
+function isDataSource(obj) {
+  return obj instanceof DataSource;
+}
+
+function tryReadConfig(cwd, fileName) {
+  try {
+    return require(path.join(cwd, fileName + '.json'));
+  } catch(e) {
+    if(e.code !== "MODULE_NOT_FOUND") {
+      throw e;
+    }
+  }
+}
+

package.json

@@ -1,7 +1,14 @@
 {
   "name": "loopback",
   "description": "LoopBack: Open Mobile Platform for Node.js",
-  "keywords": [ "StrongLoop", "LoopBack", "Mobile", "Backend", "Platform", "mBaaS" ],
+  "keywords": [
+    "StrongLoop",
+    "LoopBack",
+    "Mobile",
+    "Backend",
+    "Platform",
+    "mBaaS"
+  ],
   "version": "1.0.0",
   "scripts": {
     "test": "mocha -R spec",
@@ -20,7 +27,8 @@
     "passport-local": "~0.1.6",
     "nodemailer": "~0.4.4",
     "ejs": "~0.8.4",
-    "bcryptjs": "~0.7.10"
+    "bcryptjs": "~0.7.10",
+    "underscore.string": "~2.3.3"
   },
   "devDependencies": {
     "blanket": "~1.1.5",

test/app.test.js

@@ -2,6 +2,7 @@ describe('app', function() {
 
   describe('app.model(Model)', function() {
     it("Expose a `Model` to remote clients", function() {
+      var app = loopback();
       var memory = loopback.createDataSource({connector: loopback.Memory});
       var Color = memory.createModel('color', {name: String});
       app.model(Color);
@@ -9,13 +10,105 @@ describe('app', function() {
     });
   });
 
-  describe('app.models()', function() {
-    it("Get the app's exposed models", function() {
-      var Color = loopback.createModel('color', {name: String});
-      var models = app.models();
+  describe('app.model(name, properties, options)', function () {
+    it('Sugar for defining a fully built model', function () {
+      var app = loopback();
+      app.boot({
+        app: {port: 3000, host: '127.0.0.1'},
+        dataSources: {
+          db: {
+            connector: 'memory'
+          }
+        }
+      });
 
-      assert.equal(models.length, 1);
-      assert.equal(models[0].modelName, 'color');
+      app.model('foo', {
+        dataSource: 'db'
+      });
+
+      var Foo = app.models.foo;
+      var f = new Foo;
+
+      assert(f instanceof loopback.Model);
+    });
+  })
+
+  // describe('app.models()', function() {
+  //   it("Get the app's exposed models", function() {
+  //     var app = loopback();
+  //     var models = app.models();
+
+  //     models.forEach(function(m) {
+  //       console.log(m.modelName);
+  //     })
+      
+  //     assert.equal(models.length, 1);
+  //     assert.equal(models[0].modelName, 'color');
+  //   });
+  // });
+
+  describe('app.boot([options])', function () {
+    beforeEach(function () {
+      var app = this.app = loopback();
+
+      app.boot({
+        app: {
+          port: 3000, 
+          host: '127.0.0.1'
+        },
+        models: {
+          'foo-bar-bat-baz': {
+            options: {
+              plural: 'foo-bar-bat-bazzies'
+            },
+            dataSource: 'the-db'
+          }
+        },
+        dataSources: {
+          'the-db': {
+            connector: 'memory'
+          } 
+        }
+      });
+    });
+
+    it('Load configuration', function () {
+      assert.equal(this.app.get('port'), 3000);
+      assert.equal(this.app.get('host'), '127.0.0.1');
+    });
+
+    it('Instantiate models', function () {
+      assert(app.models);
+      assert(app.models.FooBarBatBaz);
+      assert(app.models.fooBarBatBaz);
+      assertValidDataSource(app.models.FooBarBatBaz.dataSource);
+      assert.isFunc(app.models.FooBarBatBaz, 'find');
+      assert.isFunc(app.models.FooBarBatBaz, 'create');
+    });
+
+    it('Attach models to data sources', function () {
+      assert.equal(app.models.FooBarBatBaz.dataSource, app.dataSources.theDb);
+    });
+
+    it('Instantiate data sources', function () {
+      assert(app.dataSources);
+      assert(app.dataSources.theDb);
+      assertValidDataSource(app.dataSources.theDb);
+      assert(app.dataSources.TheDb);
+    });
+  });
+
+  describe('app.boot(appRootDir)', function () {
+    it('Load config files', function () {
+      var app = loopback();
+
+      app.boot(require('path').join(__dirname, 'fixtures', 'simple-app'));
+
+      assert(app.models.foo);
+      assert(app.models.Foo);
+      assert(app.models.Foo.dataSource);
+      assert.isFunc(app.models.Foo, 'find');
+      assert.isFunc(app.models.Foo, 'create');
     });
   });
 });

test/fixtures/simple-app/app.json

@@ -0,0 +1,4 @@
+{
+  "port": 3000,
+  "host": "127.0.0.1"
+}

test/fixtures/simple-app/datasources.json

@@ -0,0 +1,5 @@
+{
+  "db": {
+    "connector": "memory"
+  }
+}

test/fixtures/simple-app/models.json

@@ -0,0 +1,5 @@
+{
+  "foo": {
+    "dataSource": "db"
+  }
+}