A "thin ODM" which is less opinionated and tries to give you query flexibility whilst still providing helpful document handling.
Features:
- ES6-ready with Promises, no callbacks
- Allows you to handle connections yourself
- Add virtual fields to documents
- Fully pluggable - easy to add support for your DB of choice
- Listen to before and after events on internal asynchronous methods
- Schema validation (sjv).
Read the documentation for more.
Installation
This package requires Node 4 or above
$ npm install thinodium
This package provides the core infrastructure. To actually access a particular database you will need to additionally install one of the following adapters:
- thinodium-mongodb - MongoDB
- thinodium-rethinkdb - RethinkDB
- thinodium-knex - Knex (Postgres, Sqlite, etc)
NOTE: Please raise a PR if you want me to add your adapter to the above list.
Basic usage
Let's first create a database connection:
// thinodium instanceconst Thinodium = ; // create the connectionconst db = Thinodium;
Thinodium will try to load an NPM module called thinodium-rethinkdb
(which
is our intention in this example). If not
available it will try to load a module called rethinkdb
. Once loaded it will
instantiate a database connection through that module, passing in the second
parameter to connect()
.
If we wished to add a custom adapter but not as an NPM module we could simply
provide its path to connect()
:
// connect using custom adatperconst db = Thinodium;
Models
Once we have our database connection setup we can access models (i.e. tables) within the database:
// get the modelconst model = db; // insert a new userlet user = model; // change the nameusername = 'mark'; user; // load user with idlet user2 = model; console; /* mark */
Both get()
and insert()
return Thinodium.Document
instances.
These internally call through to the methods prefixed with raw
- methods
which you can also use directly if you do not wish to deal with Document
s.
These are documented in the API docs.
Document customization
Model documents (each representing a row in the table) can be customized. We can add virtual fields and additional methods:
// create the modelconst model = db; // insert a new userlet user = model; console; /* mark smith */ user; console; /* marktest smith */
Note that you can access the parent model for a document using getModel()
:
let user = model; console /* true */
Schema validation
Schema validation is performed by simple-nosql-schema, and is used if a schema is provided in the initial model config:
// create the modelconst model = db; // insert a new userlet user1 = model; /* throws Error since age is missing */ let user2 = model;user2age = 'test'; user2; /* throws Error since age must be a number */
Note that schema validation is partial. If the insert or update contains a key that is not mentioned within the schema then that key gets passed through without any checks. This allows for flexibility - you only need to vaildate the parts of a model's schema you're interested in.
API
Check out the API docs for information on supported methods.
Creating an Adapter
An adapter has to extend the base Database
and Model
classes and
override the necessary internal methods:
"use strict"; const Thinodium = ; Database { return { // do what's needed for connection here and save into "connection" var ; }; } { return { // disconnect connection ; }; } { return connection name config; } Model { // return object for doing raw querying } { return { // fetch doc with given id ; }; } { return { // fetch all docs ; }; } { return { // insert doc ; }; } { return { // update doc ; }; } { return { // remove doc with id ; }; } moduleexports = Database;
Building
To run the tests:
$ npm install
$ npm test
Contributing
Contributions are welcome! Please see CONTRIBUTING.md.
License
MIT - see LICENSE.md