loopback/README.md

282 lines
6.4 KiB
Markdown
Raw Normal View History

2013-04-09 16:02:36 +00:00
# asteroid
v0.0.1
## Install
2013-04-09 18:33:29 +00:00
slnode install asteroid -g
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
## Server APIs
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
- [App](#app)
- [asteroid.Model](#model)
- [asteroid.DataSource](#data-source)
- [asteroid.RemoteObject](#data-source)
- [asteroid.rest](#rest)
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
## Client APIs
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
_TODO_
### App
Create an asteroid application.
var asteroid = require('asteroid');
var app = asteroid();
app.get('/', function(req, res){
res.send('hello world');
});
app.listen(3000);
**Notes:**
- extends [express](http://expressjs.com/api.html#express)
- see [express docs](http://expressjs.com/api.html) for details
- supports [express / connect middleware](http://expressjs.com/api.html#middleware)
#### app.model(Model)
Expose a `Model` to remote clients.
var memory = asteroid.createDataSource({adapter: 'memory'});
var Color = memory.defineModel({name: String});
app.model(Color);
app.use(asteroid.rest());
**Note:** this will expose all [shared methods](#shared-methods) on the model.
#### app.models()
Get the app's exposed models.
var models = app.models();
models.forEach(function (Model) {
console.log(Model.name); // color
});
### Model
An Asteroid `Model` is a vanilla JavaScript class constructor with an attached set of properties and settings.
**Properties**
A model defines a list of property names, types and other validation metadata. A [DataSource](#data-source) uses this definition to validate a `Model` during operations such as `save()`.
**Settings**
Some [DataSources](#data-source) may support additional `Model` settings.
Define an asteroid model.
var User = asteroid.createModel('user', {
first: String,
last: String,
age: Number
});
#### Model.attachTo(dataSource)
Attach a model to a [DataSource](#data-source). Attaching a [DataSource](#data-source) updates the model with additional methods and behaviors.
var oracle = asteroid.createDataSource({
adapter: 'oracle',
host: '111.22.333.44',
database: 'MYDB',
username: 'username',
password: 'password'
});
User.attachTo(oracle);
**Note:** until a model is attached to a data source it will only expose the API defined below.
#### Static Methods
Define a static model method.
User.login = function (username, password, fn) {
var passwordHash = hashPassword(password);
this.findOne({username: username}, function (err, user) {
var failErr = new Error('login failed');
if(err) {
fn(err);
} else if(!user) {
fn(failErr);
} else if(user.password === passwordHash) {
MySessionModel.create({userId: user.id}, function (err, session) {
fn(null, session.id);
});
} else {
fn(failErr);
}
});
}
Expose the static model method to clients using remoting.
User.login.shared = true;
User.login.accepts = [
{arg: 'username', type: 'string', required: true},
{arg: 'password', type: 'string', required: true}
];
User.login.returns = {arg: 'sessionId', type: 'any'};
#### Instance Methods
Define an instance method
User.prototype.logout = function (fn) {
MySessionModel.destroyAll({userId: this.id}, fn);
}
Expose the model instance method to clients using remoting.
User.prototype.logout.shared = true;
#### Hooks
Run a function before or after a model method is called.
User.before('save', function(user, next) {
console.log('about to save', user);
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
next();
});
Prevent the method from being called by proding an error.
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
User.before('delete', function(user, next) {
// prevent all delete calls
next(new Error('deleting is disabled'));
});
#### Remote Hooks
Run a function before or after a method is called remotely by a client.
User.beforeRemote('save', function(ctx, user, next) {
if(ctx.user.id === user.id) {
next();
} else {
next(new Error('must be logged in to update'))
}
});
#### Model.availableHooks()
Return a list of available hooks.
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
console.log(User.availableHooks()); // ['save', ...]
#### Shared Methods
Any static or instance method can be decorated as `shared`. These methods are exposed over the provided transport (eg. [asteroid.rest](#rest)).
#### Model.availableMethods()
Returns the currently available api of a model as well as descriptions of any modified behavior or methods from attached data sources.
User.attachTo(oracle);
console.log(User.availableMethods());
Output:
{
'User.all': {
accepts: [{arg: 'filter', type: 'object', description: '...'}],
returns: [{arg: 'users', type: ['User']}]
},
'User.find': {
accepts: [{arg: 'id', type: 'any'}],
returns: [{arg: 'items', type: 'User'}]
},
...
}
### Data Source
An Asteroid `DataSource` provides [Models](#model) with the ability to manipulate data.
Define a data source for persisting models.
var oracle = asteroid.createDataSource({
2013-04-26 18:44:19 +00:00
adapter: 'oracle',
2013-06-05 14:38:04 +00:00
host: '111.22.333.44',
database: 'MYDB',
username: 'username',
password: 'password'
2013-04-26 18:44:19 +00:00
});
2013-06-05 14:38:04 +00:00
#### dataSource.createModel(name, options, settings)
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
Define a model and attach it to a `DataSource`.
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
var Color = oracle.createModel('color', {name: String});
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
#### dataSource.discoverSchemas(options, fn)
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
Discover an object containing properties and settings for an existing data source.
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
module.exports = oracle.discoverSchemasSync({table: 'PRODUCTS', owner: 'MYORG'});
2013-04-26 18:44:19 +00:00
2013-06-05 14:38:04 +00:00
#### dataSource.discoverSchemaSync(options)
A synchronous version of the above.
var desc = oracle.discoverSchemaSync({table: 'PRODUCTS'});
**Note:** Not available for all adapters.
#### dataSource.discoverModel(options, fn)
Discover schema and create model.
#### dataSource.discoverModelSync(options, fn)
Sync discover schema and create model.
#### dataSource.discoverModels(options, fn)
TODO define.
#### dataSource.discoverModelSync(options)
#### dataSource.createLocation(name, options, settings)
2013-04-09 16:02:36 +00:00
2013-06-05 14:38:04 +00:00
other option
2013-05-20 21:31:04 +00:00
2013-06-05 14:38:04 +00:00
RentalLocation = asteroid.createModel('rental-location', {
location: Location
});
2013-05-20 21:31:04 +00:00
2013-06-05 14:38:04 +00:00
Location.distanceTo({lat: 22, long: 55}, fn);
2013-05-20 21:31:04 +00:00
2013-06-05 14:38:04 +00:00
Location.all({where: {geo: {near: {lat: 22, long: 55}}}, limit: 10, sort: 'distance DESC'}, fn)