Reasoning behind creating a promise based version
Dealing with database is always an asynchronous task by nature. You query something, the database needs to process your command, and then send you the results. Node is built around callbacks and events, and to tame it to avoid callback hell and unmaintainable code, promises were created.
This version is the dual API, along with the original callback based, it's promise based version of Jugglindb, and will be maintained to be kept up-to-date with the original. All adapters should work with this version out-of-the-box.
See API differences below.
- Every function that would return a value now return a promise
- Validation is async only
- Since everything is made properly asynchronous now,
process.nextTickandsetImmediatewere removed from the code - Functions that would act as getter and setters now return the object itself when acting as a setter
About
JugglingDB(3) is cross-db ORM for nodejs, providing common interface to access most popular database formats. Currently supported are: mysql, sqlite3, postgres, couchdb, mongodb, redis, neo4j and js-memory-storage (yep, self-written engine for test-usage only). You can add your favorite database adapter, checkout one of the existing adapters to learn how, it's super-easy, I guarantee.
Jugglingdb also works on client-side (using WebService and Memory adapters), which allows to write rich client-side apps talking to server using JSON API.
Installation
npm install promised-jugglingdbplus you should install appropriated adapter, for example for redis:
npm install jugglingdb-redischeck following list of available adapters
What's the difference?
Take this callback based jugglingdb code
Article;And compare to this:
Article//since we are dealing with 3 models, we need to be able to pass them around; which can be written as:
var Q = ;Qall Article Article Tag;Or this:
db;to
db;or even better
all db Book Chapter Author Reader ;More verbose, but everything in it's place, and the flow is linear and easy to spot any errors, plus each error or
exception goes to their own catch call since if any error or exception happens in any of the calls, it will be
caught by the catch part of the chain, and it won't procceed.
Everything will be executed in order, and can be watched and easily tested, in comparision the to callback hell, that's deeply nested and might lead to memory leaks.
JugglingDB adapters
| Database type | Package name | Maintainer | Build status |
|---|---|---|---|
 Firebird |
jugglingdb-firebird | Henri Gourvest |
Participation
- Check status of project on trello board: https://trello.com/board/jugglingdb/4f0a0b1e27d3103c64288388
- Make sure all tests pass (
npm testcommand) - Feel free to vote and comment on cards (tickets/issues), if you want to join team -- send me a message with your email.
If you want to create your own jugglingdb adapter, you should publish your
adapter package with name jugglingdb-ADAPTERNAME. Creating adapter is simple,
check jugglingdb/redis-adapter for example.
For more information, see the Testing section below.
Usage
var Schema = Schema;var schema = 'redis' port: 6379; //port number depends on your configuration// define modelsvar Post = schema; // simplier way to describe modelvar User = schema; var Group = schema; // define any custom methodUserprototype { return thisname + ', ' + thisage;}; // models also accessible in schema:schemamodelsUser;schemamodelsPost;SEE schema(3) for details schema usage.
// setup relationshipsUser;// creates instance methods:// user.posts(conds)// user.posts.build(data) // like new Post({userId: user.id});// user.posts.create(data) // build and save Post;// creates instance methods:// post.author() -- getter when called with function// post.author() -- sync getter when called without params// post.author(user) -- setter when called with object User;// user.groups().then() - get groups of user// user.groups.create(data).then() - create new group and connect with user// user.groups.add(group).then() - connect existing group with user// user.groups.remove(group).then() - remove connection between group and user schema; // required only for mysql and postgres NOTE: it will drop User and Post tables // work with models:var user = ;user; // or just call it as function (with the same result):var user = ;user; // Common API methods // just instantiate model // save model (of course async)Post; // all postsPostall // all posts by userPostallwhere: userId: userid order: 'id' limit: 10 skip: 20; // the same as prevuser // get one latest postPost; // same as new Post({userId: user.id});userpostsbuild // save as Post.create({userId: user.id}).then();userposts // find instance by idUser // count instancesUser // destroy instanceuser; // destroy all instancesUser; // update a post (currently only on the mysql adapter)Post;SEE model(3) for more information about
jugglingdb Model API. Or man jugglingdb-model in terminal.
// Setup validationsUserUser;User;User;User;User; user; SEE ALSO jugglingdb-validations(3) or
man jugglingdb-validations in terminal. Validation tests: ./test/validations.test.js
Hooks
The following hooks supported:
- afterInitialize
- beforeCreate
- afterCreate
- beforeSave
- afterSave
- beforeUpdate
- afterUpdate
- beforeDestroy
- afterDestroy
- beforeValidate
- afterValidate
Each callback is class method of the model, it should accept single argument: next, this is callback which should
be called after end of the hook. Except afterInitialize because this method is syncronous (called after new Model).
During beforehooks the next callback accepts one argument, which is used to terminate flow. The argument passed on
as the err parameter to the API method callback.
Object lifecycle:
var user = ;// afterInitializeuser; // If Model.id isn't set, save will invoke Model.create() instead // beforeValidate// afterValidate// beforeSave// beforeUpdate// afterUpdate// afterSave// callbackuser; // beforeValidate// afterValidate// beforeSave// beforeUpdate// afterUpdate// afterSave// callbackuser; // beforeDestroy// afterDestroy// callback User;// beforeValidate// afterValidate// beforeCreate// beforeSave// afterSave// afterCreate// callbackSEE jugglingdb-hooks or type this command
in your fav terminal: man jugglingdb-hooks. Also check tests for usage
examples: ./test/hooks.test.js
Your own database adapter
To use custom adapter, pass it's package name as first argument to Schema constructor:
var mySchema = 'mycouch' host: port:...;In that case your adapter should be named as 'jugglingdb-mycouch' npm package.
Testing
Core of jugglingdb tests only basic features (database-agnostic) like
validations, hooks and runs db-specific tests using memory storage. It also
exports complete bucket of tests for external running. Each adapter should run
this bucket (example from jugglingdb-redis):
// test/init.jsvar jdb = Schema = jdbSchema; global{ // ../ is your adapter path, assuming we are in /test/, and it's in your /lib/ folder return host: 'localhost' database: 1;};Each adapter could add specific tests to standart bucket:
// adapter.test.js;If you are using mocha, to run tests use this command (will search for files in the test directory by default):
mocha test/*.test.jsand to skip, for example adapter call mocha with --grep:
mocha --grep "^adapter*"Before running make sure you've installed package (npm install) and if you
running some specific adapter tests, ensure you've configured database
correctly (host, port, username, password).
Contributing
If you have found a bug please try to write unit test before reporting. Before
submit pull request make sure all tests still passed. Check
roadmap, github issues if you want to
help. Contribution to docs highly appreciated. Contents of man pages and
http://jugglingdb.co generated from md files stored in this repo at ./docs repo
MIT License
Copyright (C) 2011 by Anatoliy Chakkaev <mail [åt] anatoliy [døt] in>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.