Simple model part for custom mvc over express/connect routes.
npm install modellingSimple model part for custom mvc over express/connect routes.
The idea is quite simple.
This is the model part, your express route functions are the controllers, and your html is the view part.
It's just a wrapper over Waterline, to make it really easy to use with your express route middleware.
Why do this when you have great mvc frameworks like Sails?
The answer is simple, sometimes you don't need a framework. For example, if you are not creating an app, but a library, where you need to control part of the model, but you don't really know the whole model, a framework can be very annoying.
Install via npm:
npm install modelling
To use it inside your project:
``
var orm = new modelling(options);
and then, for example, with express:
`
app.get('/route/:id', orm.use('mymodel'), function(req, res, next) {
//all waterline collections are placed in req.model
req.model.mymodel.findOne({id: req.params.id}).exec(...);
});
* __collections__
synonym for _"models"_.
* __adapters__
Waterline adapters definition. For example:
` `
var options = {
adapters: {
disk: require('sails-disk')
}
};
new modelling(options);
* __connections__
Waterline adapters definition. For example:
`
var options = {
connections: {
conn1: {
adapter: 'disk'
}
}
};
new modelling(options);
* __policies__
Policies to be applied to models. You write them in the form of express/connect middleware. They can be applied before or after retrieving the model.
For example:
`
var options = {
policies: {
loggedIn: function(req, res, next) {
if(req.session.userId) {
next();
} else {
res.redirect('/login');
}
},
isAdmin: {
fn: function(req, res, next) {
(!req.model || !req.model.user) && return next('user model needed');
req.model.user.findOne({id: req.session.userId}, function(err, user) {
if(!err && user && user.isAdmin) {
next();
} else {
next(err||'You are not Admin');
}
});
},
after: true
}
}
};
new modelling(options);
Notice in this example that we have 2 policies defined, _"loggedIn"_ to ensure user is logged in, and _"isAdmin"_ to check if user has admin rights.
Because we need user data to check admin rights, we set _"after"_ property to true;
* __models__
Waterline models definition, but with an __optional__ extra parameter. The extra parameter is _"policies"_, and is a string, or array of strings where you define the name of default policies to apply to model.
Models __must__ comply with waterline model definition. For example:
`
var options = {
models: {
user: {
identity: 'user',
connection: 'conn1',
schema: true,
policies: 'loggedIn',
attributes: {
name: {type: 'string', required: true},
pass: {type: 'string', required: true},
isAdmin: 'boolean'
}
}
}
};
##API
###Adapters
* setAdapter([add,] [name,] adapter)
Returns modelling instance for chaining purposes.
* __add__ Boolean. If _true_, the adapter definition will be added to the rest. Otherwise adapters definition will be replaced. Defaults _false_.
* __name__ String. The name of the adapter definition. If ommited, _adapter_ definition must include the name as first property.
* __adapter__ Object. The definition of the adapter. If _name_ parameter was ommited _adapter_ definition must include the name as first property.
The following are equivalent:
`
instance.setAdapter('pg', require('sails-postgres'));
instance.setAdapter({pg: require('sails-postgres'});
If the adapter definition was already present, it will be overwritten.
After all changes are made to adapters, _done_ function must be called to be applied in waterline.
* adapters([name])
Returns adapters definition. If _name_ is present, will return the definition of the specified adapter.
* remAdapter([name])
Returns modelling instance for chaining purposes.
Deletes all adapters definition. If name is present, will only delete the definition for the specified adapter.
After all changes are made to adapters, _done_ function must be called to be applied in waterline.
###Connections
* setConnection([add,] [name,] connection)
Returns modelling instance for chaining purposes.
* __add__ Boolean. If _true_, the connection definition will be added to the rest. Otherwise connections definition will be replaced. Defaults _false_.
* __name__ String. The name of the connection definition. If ommited, _connection_ definition must include the name as first property.
* __connection__ Object. The definition of the connection. If _name_ parameter was ommited _connection_ definition must include the name as first property.
The following are equivalent:
`
instance.setConnection('localhost', {adapter: 'disk'});
instance.setConnection({localhost: {adapter: 'disk'}});
If the connection definition was already present, it will be overwritten.
After all changes are made to connections, _done_ function must be called to be applied in waterline.
* connections([name])
Returns connections definition. If _name_ is present, will return the definition of the specified connection.
* remConnection([name])
Returns modelling instance for chaining purposes.
Deletes all connections definition. If name is present, will only delete the definition for the specified connection.
After all changes are made to connections, _done_ function must be called to be applied in waterline.
###Models
* setModel([add,] [name,] model)
Returns modelling instance for chaining purposes.
* __add__ Boolean. If _true_, the model definition will be added to the rest. Otherwise models definition will be replaced. Defaults _false_.
* __name__ String. The name of the model definition. If ommited, _model_ definition must include the name as first property.
* __model__ Object. The definition of the model. If _name_ parameter was ommited _model_ definition must include the name as first property.
The following are equivalent:
`
instance.setModel('localhost', {adapter: 'disk'});
instance.setModel({localhost: {adapter: 'disk'}});
If the model definition was already present, it will be overwritten.
After all changes are made to models, _done_ function must be called to be applied in waterline.
* models([name])
Returns models definition. If _name_ is present, will return the definition of the specified model.
* remModel([name])
Returns modelling instance for chaining purposes.
Deletes all models definition. If name is present, will only delete the definition for the specified model.
After all changes are made to models, _done_ function must be called to be applied in waterline.
###Policies
* setPolicy([add,] [name,] policy)
Returns modelling instance for chaining purposes.
* __add__ Boolean. If _true_, the policy definition will be added to the rest. Otherwise policies definition will be replaced. Defaults _false_.
* __name__ String. The name of the policy definition. If ommited, _policy_ definition must include the name as first property.
* __policy__ Object. The definition of the policy. If _name_ parameter was ommited _policy_ definition must include the name as first property.
The following are equivalent:
`
instance.setPolicy('pg', require('sails-postgres'));
instance.setPolicy({pg: require('sails-postgres'});
If the policy definition was already present, it will be overwritten.
As policies are not a part of waterline, is not necesary to call _done_ function when you only change policies.
* policies([name])
Returns policies definition. If _name_ is present, will return the definition of the specified policy.
* remPolicy([name])
Returns modelling instance for chaining purposes.
Deletes all policies definition. If name is present, will only delete the definition for the specified policy.
As policies are not a part of waterline, is not necesary to call _done_ function when you only change policies.
###General
* done()
Returns void.
This function is called when you want to apply changes in models, adapters or connections.
* use(options)
Returns a function that can be placed as express/connect middleware. If all policies comply, it places all models specified in req.model.false
__options__ can be a _string_, an _array_ of strings or an _object_.
* If it's a __string__ it will be interpreted as the name of the model you want to access. Default policies of the model will be applied.
* If it's an __array__ it will be interpreted as an array of names of the models you want to access. Default policies of all models will be applied.
* If it's an __object__, it must contain a _models_ property, and optionally can contain a _policies_ property.
* _models_: Has to be of type _string_ or _array_ of strings.
* _policies_: Here you can define custom policies to implement in a particular route. You can also override default policies of models. If you redefine a policy to , it will not be applied this time.`
For example:
app.get('/user/docs', orm.use('user'), function(req, res, next) {
//"user" waterline's model definition is placed in req.model.user
req.model.user.findOne({id: req.session.userId}).populate('docs').exec(...);
});
Get the _user_ model in this route. Notice you can _populate_ other models;
app.post('/user/docs', orm.use(['user', 'docs']), function(req, res, next) {
req.model.user.findOne({id: req.session.userId}, function(err, user){
if(!err && user) {
req.model.docs.find().exec(function(err, docs){
//do something
});
}
});
});
This is an inefficient clone of the example above, but good for showing how to get both _user_ and _docs_ models in this route.
Now, for the next example, we get a little more complicated.
Suppose we are making _"The John's Club"_ application, and there is a form where users register themselves.
Suppose there are two basic rules:
* Your name must be 'John'.
* There cannot be two Johns with the same lastname.
Here is what we could do:
app.post('/johns', orm.use({
policies: {
loggedIn: false,
hasJohnName: function(req, res, next) {
//ensure username is John
if(req.body.name == 'John') {
next();
} else {
next("You'r not a John");
}
},
uniqueLastname: {
fn: function(req, res, next) {
req.model.user.findOne({lastname: req.body.lastname}, function(err, user) {
if(err) return next(err);
if(user) return next('There is an other John with your lastname');
next();
}
},
after: true
}
},
models: 'user'
}), function(req, res, next) {
//create john user
});
As you see, we've got 3 policies.
* The first one actually overrides the loggedIn policy of user model. As this is the result of a post from an auto register form, we know the user won't be logged in. So we take this policy out.
* The second policy applies before we retrieve the model. It ensures that the name of the user is actually 'John'.
* The third rule applies after we retrieve the model. It ensures there is no other John with your lastname.
Any suggestions, bug reports, bug fixes, Pull Requests, etc, are very wellcome (here).
Thanks for reading!.