New API Docs
This commit is contained in:
Ritchie Martori
parent
d53b995241
commit
9b43b0bfee
291
README.md
291
README.md
|
|
@ -5,57 +5,278 @@ v0.0.1
|
|||
|
||||
slnode install asteroid -g
|
||||
|
||||
## API
|
||||
## Server APIs
|
||||
|
||||
### app
|
||||
- [App](#app)
|
||||
- [asteroid.Model](#model)
|
||||
- [asteroid.DataSource](#data-source)
|
||||
- [asteroid.RemoteObject](#data-source)
|
||||
- [asteroid.rest](#rest)
|
||||
|
||||
Create an asteroid app.
|
||||
## Client APIs
|
||||
|
||||
var asteroid = require('asteroid')
|
||||
, app = asteroid();
|
||||
|
||||
### app.dataSource()
|
||||
_TODO_
|
||||
|
||||
Attach a remote data source to your app.
|
||||
### App
|
||||
|
||||
app.dataSource('color-db', {
|
||||
adapter: 'oracle',
|
||||
host: 'localhost',
|
||||
port: 2345,
|
||||
user: 'test',
|
||||
password: 'test'
|
||||
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
|
||||
});
|
||||
|
||||
### app.define(name)
|
||||
### Model
|
||||
|
||||
Define a [Model](node_modules/model).
|
||||
An Asteroid `Model` is a vanilla JavaScript class constructor with an attached set of properties and settings.
|
||||
|
||||
var Color = app.define('color');
|
||||
**Properties**
|
||||
|
||||
### app.use(asteroid.rest);
|
||||
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()`.
|
||||
|
||||
Expose your models over a REST api.
|
||||
**Settings**
|
||||
|
||||
// node
|
||||
app.use(asteroid.rest);
|
||||
Some [DataSources](#data-source) may support additional `Model` settings.
|
||||
|
||||
Define an asteroid model.
|
||||
|
||||
var User = asteroid.createModel('user', {
|
||||
first: String,
|
||||
last: String,
|
||||
age: Number
|
||||
});
|
||||
|
||||
// http
|
||||
GET /colors
|
||||
#### 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);
|
||||
|
||||
200 OK
|
||||
[
|
||||
{name: 'red'},
|
||||
{name: 'blue'},
|
||||
{name: 'green'}
|
||||
]
|
||||
**Note:** until a model is attached to a data source it will only expose the API defined below.
|
||||
|
||||
## Asteroid Modules
|
||||
#### Static Methods
|
||||
|
||||
- [Asteroid Module Base Class](node_modules/asteroid-module)
|
||||
- [Route](node_modules/route)
|
||||
- [Model Route](node_modules/model-route)
|
||||
- [Model](node_modules/model)
|
||||
- [Data Source](node_modules/data-source)
|
||||
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);
|
||||
|
||||
next();
|
||||
});
|
||||
|
||||
Prevent the method from being called by proding an error.
|
||||
|
||||
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.
|
||||
|
||||
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({
|
||||
adapter: 'oracle',
|
||||
host: '111.22.333.44',
|
||||
database: 'MYDB',
|
||||
username: 'username',
|
||||
password: 'password'
|
||||
});
|
||||
|
||||
#### dataSource.createModel(name, options, settings)
|
||||
|
||||
Define a model and attach it to a `DataSource`.
|
||||
|
||||
var Color = oracle.createModel('color', {name: String});
|
||||
|
||||
#### dataSource.discoverSchemas(options, fn)
|
||||
|
||||
Discover an object containing properties and settings for an existing data source.
|
||||
|
||||
module.exports = oracle.discoverSchemasSync({table: 'PRODUCTS', owner: 'MYORG'});
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 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)
|
||||
|
||||
|
||||
other option
|
||||
|
||||
RentalLocation = asteroid.createModel('rental-location', {
|
||||
location: Location
|
||||
});
|
||||
|
||||
Location.distanceTo({lat: 22, long: 55}, fn);
|
||||
|
||||
Location.all({where: {geo: {near: {lat: 22, long: 55}}}, limit: 10, sort: 'distance DESC'}, fn)
|
||||
Loading…
Reference in New Issue