rethink
rethinkdb ODM. It's conventions and api highly resemble but are not limited to mongoose
ODM for mongodb.
Architecture
Rethink
Main module Rethink
is responsible for initalisation of schema
, models
and database connection. To simplify the API rethink will queue all db operations until connection is established.
var r = ; var schema = r; var User = r; User; r;
Schema
Module Schema
has a few thin, but capacitive api layers:
validation
validation is powered by node-veee
, check https://github.com/node-veee/veee for details
before hooks
validate
will be fired before object is validated. It will be invoked asynchronously:
schema;
create
will be fired after validation. It will be invoked asynchronously:
schema;
update
will be fired after validation. It will be invoked asynchronously:
schema;
save
will be fired after create
or update
, but before object is saved to db. It will be invoked asynchronously:
schema;
remove
hook is fired before object removal. It will be invoked asynchronously:
schema;
query
hook is fired before results are retrieved from database. It will be invoked asynchronously:
schema;
after hooks
validate
will be fired after object is validated. It will be invoked asynchronously:
schema;
save
will be fired before create
or update
, but after object is saved to db. It will be invoked synchronously:
schema;
create
will be invoked synchronously:
schema;
update
will be invoked synchronously:
schema;
remove
hook is fired after object removal and will be invoked synchronously:
schema;
query
hook is fired after results have been retrieved from database and it will be invoked asynchronously:
schema;
hook error handling
All asynchronous callbacks, eg. done
, will accept an optional error argument that will stop execution chain.
schema;
plugins
schema plugins use node-style .use
pattern
schema ;
model prototype extension
its possible to extend default model api with static methods from schema.
schemastatics { console;} var Person = r; Person; // will log 'hello'
By design schema should not be altered after it's built, eg.:
var Post = r; schemastatics {...} Post; // won't work
example
var schema = r; schema; schema; schemastatics { this;} schema;
Table
Module Table
is used (internally) to automatically create a backing table, manage table indexes and wait (lock) until rethinkdb builds them. Table name is lower-cased pluralised version of a model name, eg. model: 'Person', table: 'people'.
Model
Model
provides a node callback-style api to manipulate records in a single rethinkdb table. Model api could be extended, using schema.statics
object.
var Person = r; Person;Person;Person;Person;Person;
API
Rethink
constructor([{Object} options]):Rethink
Initialize a new instance of Rethink
(with options hash)
var r = ;
schema({Object} definition[, {Object} options]):Schema
Create a new schema, using definition and optionally pass options to it
var schema = r;
model({String} name, {Schema} schema):Model
Create a new model using singular case-sensitive name and a schema
var User = r;
connect({String} dbUrl[, {Object} options])
Connect to rethinkdb instance using database url (e.g. 'host:port') and options
r;
before({String} hook, {Function} fn({Rethink} rethink)):Rethink
Create a before hook for one of the actions. Only used to attach to buildSchema
hook.
rethink;
use({Function} plugin({Rethink} rethink[, {Object} options])[, {Object} options])):Rethink
Attach a plugin to rethink. Mainly used for attaching a plugin to an internal before:buildSchema
hook.
r; { rethinkSchemaprototype { console; } // will fire everytime before schema build // equivalent of attaching a plugin to every schema rethink;} { schema; schema;};
types
Access to node-veee
validation types
rethinktypes;
Schema
Access to schema class
rethinkSchemaprototype { return 'world';}
Static Properties
Types
— access to node-veee
validation types
RethinkTypes;
Schema
— access to schema class
var schema = new Rethink.Schema({ name: Rethink.Types.string().min(3)});
Plugins
— access to built-in plugins
var rethink = ; rethink ;
Schema
constructor({Object} params):Schema
{Object} type
: node-veee
validator for a given type
var schema = startsAt: type: RethinkTypes ; // shorthandvar schema = startsAt: RethinkTypes;
{Boolean|Object} index
: used by Table
to make sure rethink indexes a given field
var postSchema = authorId: index: true ; var markerSchema = position: index: geo: true ;
{*} default
: set default value to field if fnot specified. Default also has support for sync functions with length 1 and async with length 2.
// primitivesvar postSchema = title: default: 'Untitled Post' ; // syncvar postSchema = createdAt: { return ; } ; // asyncvar ticker = price: { ; } ;
before({String} action, {Function} hook({Object|Array} data, {Function} done({Error} err))):Schema
Create a before hook for one of the actions
schema;
after({String} action, {Function} hook({Object|Array} data, {Function} done({Error} err))):Schema
Create an after hook for one of the actions
schema;
statics
Define a static model method
schemastatic { this;} var User = r; User;
use({Function} plugin({Schema} schema[, {Object} options])[, {Object} options]):Schema
Attach a plugin to schema
var { schema; schema;} schema;
Instance Properties
types
— Access to node-veee
validation types
schematypes;
Model
create({Object} object, {Function} callback(err, object))
Create an object
User;
update({Object} object, {Function} callback(err, object))
Update an object
User;
remove({String} id, {Function} callback(err, id))
Remove an object using an id
User;
find({Object} query[, {Object} options], {Function} callback(err, records))
Find model records using a query and options
User;
findOne({Object} query[, {Object} options], {Function} callback(err, record))
Find one model record using a query and options
User;
Plugins
Architecture
Rethink is made to be pluggable, in fact, most of rethink functionality could be (and is) implemented as plugins.
Plugin is just a function that takes rethink
and options
as arguments and is able to plug into Schema
, Model
and Rethink
prototypes and hooks.
// plugins/safe-delete.js { schema_fieldsdeletedAt = type: schematypes default: '' schema; schemastatics { this; }} // expose rethink pluginexports = module { rethink;} // expose schema pluginexports { ;} // app.js // use safe delete plugin on all schemavar safeDelete = ;rethink; // use safe delete plugin only on one schema var safeDelete = safeDelete;schema;
Populate
Populate plugin introduces application-side deep table joins to rethink.
// inject schema instance methodsrethink; var User = rethink; var Company = rethink; User; User
Advanced
var schema = rethink; // shorthands, do same above// !!!note: refField is required to be specified for `hasMany` relationshipsschema; schema; var Reference = rethink; Reference;
Query time population
to make use of advanced population you could define population options in query
// get all references of this userReference;
Timestamps
Timestamps plugin adds createdAt
and updatedAt
ISO 8601 dates to schema and helps to manage them accordingly
rethink; var User = rethink; User; ... User;
Installation
$ npm install rethink --save
Usage
// requirevar Rethink = ; // initializevar r = ; // connect to databaser; // define schemavar companySchema = r; var userSchema = r; // use hooksuserSchema; userSchema; // use pluginsuserSchema; // define static (helper) methodsuserSchemastatics { return this;} // create model (table)var User = r;var Company = r; // create recordsCompany; // search recordsUser;
Roadmap
- live query support
- make use of rethinkdb indexes
- rethink options
- spec tests
- 100% coverage
- opensource?
- move all rethinkdb calls out into an engine
- implement es-index as a plugin
- parallel index creation, table creation (speedup startup time)
- rethink eventmietter api
- model eventemitter api
Development
$ git clone git@github.com:seedalpha/rethink.git
$ cd rethink
$ npm install
$ npm test
$ npm run coverage
Author
Vladimir Popov vlad@seedalpha.net
License
©2015 SeedAlpha