jugglingdb

    2.0.1 • Public • Published

    NPM Version NPM Downloads Build status Test Coverage

    About

    JugglingDB is cross-db ORM for nodejs, providing common interface to access most popular database formats. Currently supported are: mysql, sqlite3, postgres, mongodb, redis 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.

    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 jugglingdb
    

    and you should install appropriate adapter, for example for redis:

    npm install jugglingdb-redis-hq
    

    check following list of available adapters

    JugglingDB adapters

    Database type Package name Maintainer Build status / coverage
    ArangoDB ArangoDB jugglingdb-arango Andreas Streichardt Build Status
    Firebird Firebird jugglingdb-firebird Henri Gourvest
    MongoDB MongoDB jugglingdb-mongodb Anatoliy Chakkaev Build Status Coverage Status
    MySQL MySQL jugglingdb-mysql dgsan Build Status Coverage Status
    CouchDB CouchDB / nano jugglingdb-nano Nicholas Westlake Build Status
    PostgreSQL PostgreSQL jugglingdb-postgres Anatoliy Chakkaev Build Status Coverage Status
    Redis Redis jugglingdb-redis-hq Anatoliy Chakkaev Build Status Coverage Status
    RethinkDB RethinkDB jugglingdb-rethink Tewi Inaba Build Status
    SQLite SQLite jugglingdb-sqlite3 Anatoliy Chakkaev Build Status Coverage Status
    WebService built-in Anatoliy Chakkaev n/a
    Memory (bogus) built-in Anatoliy Chakkaev n/a
    DynamoDB jugglingdb-dynamodb tmpaul Build Status
    SQL Server jugglingdb-mssql Quadrus n/a
    Azure Table Storage jugglingdb-azure-tablestorage Vadim Kazakov n/a

    Participation

    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. JugglingDB core exports common tests each adapter should pass, you could create your adapter in TDD style, check that adapter pass all tests defined in test/common_test.js.

    Usage

    var Schema = require('jugglingdb').Schema;
    var schema = new Schema('redis', {port: 6379}); //port number depends on your configuration
    // define models
    var Post = schema.define('Post', {
        title:     { type: String, length: 255 },
        content:   { type: Schema.Text },
        date:      { type: Date,    default: function () { return new Date;} },
        timestamp: { type: Number,  default: Date.now },
        published: { type: Boolean, default: false, index: true }
    });
     
    // simplier way to describe model
    var User = schema.define('User', {
        name:         String,
        bio:          Schema.Text,
        approved:     Boolean,
        joinedAt:     Date,
        age:          Number
    }, {
        restPath: '/users' // tell WebService adapter which path use as API endpoint
    });
     
    var Group = schema.define('Group', {name: String});
     
    // define any custom method
    User.prototype.getNameAndAge = function () {
        return this.name + '' + this.age;
    };
     
    // models also accessible in schema:
    schema.models.User;
    schema.models.Post;

    SEE schema(3) for details schema usage.

    // setup relationships
    User.hasMany(Post,   {as: 'posts',  foreignKey: 'userId'});
    // creates instance methods:
    // user.posts(conds)
    // user.posts.build(data) // like new Post({userId: user.id});
    // user.posts.create(data) // build and save
     
    Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
    // creates instance methods:
    // post.author(callback) -- getter when called with function
    // post.author() -- sync getter when called without params
    // post.author(user) -- setter when called with object
     
    User.hasAndBelongsToMany('groups');
    // user.groups(callback) - get groups of user
    // user.groups.create(data, callback) - create new group and connect with user
    // user.groups.add(group, callback) - connect existing group with user
    // user.groups.remove(group, callback) - remove connection between group and user
     
    schema.automigrate(); // required only for mysql and postgres NOTE: it will drop User and Post tables
     
    // work with models:
    var user = new User;
    user.save(function (err) {
        var post = user.posts.build({title: 'Hello world'});
        post.save(console.log);
    });
     
    // or just call it as function (with the same result):
    var user = User();
    user.save(...);
     
    // Common API methods
    // each method returns promise, or may accept callback as last param
     
    // just instantiate model
    new Post({ published: 0, userId: 1 });
     
    // save model (of course async)
    Post.create();
     
    // all posts
    Post.all();
     
    // all posts by user
    Post.all({ where: { userId: user.id }, order: 'id', limit: 10, skip: 20 });
     
    // the same as prev
    user.posts(cb)
     
    // get one latest post
    Post.findOne({ where: { published: true }, order: 'date DESC' });
     
    // same as new Post({userId: user.id});
    user.posts.build({ published: 1 });
     
    // save as Post.create({userId: user.id});
    user.posts.create();
     
    // find instance by id
    User.find(1);
     
    // find instance by id and reject promise when not found
    User.fetch(1)
        .then(user => console.log('found user', user))
        .catch(err => console.error('can not fetch user with id 1:', err));
     
    // count instances
    User.count([conditions])
     
    // destroy instance
    user.destroy();
     
    // destroy all instances
    User.destroyAll();
     
    // update multiple instances (currently only on the sql adapters)
    Post.bulkUpdate({ update: { published: 0 }, where: { id: [1, 2, 3] }});
     
    // update single instance
    Post.update(1, { published: 1 });

    SEE model(3) for more information about jugglingdb Model API. Or man jugglingdb-model in terminal.

     
    // Setup validations
    User.validatesPresenceOf('name', 'email')
    User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
    User.validatesInclusionOf('gender', {in: ['male', 'female']});
    User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
    User.validatesNumericalityOf('age', {int: true});
    User.validatesUniquenessOf('email', {message: 'email is not unique'});
     
    user.isValid(function (valid) {
        if (!valid) {
            user.errors // hash of errors {attr: [errmessage, errmessage, ...], attr: ...}    
        }
    })
     

    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 = new User;
    // afterInitialize
    user.save(callback); // If Model.id isn't set, save will invoke Model.create() instead
    // beforeValidate
    // afterValidate
    // beforeSave
    // beforeUpdate
    // afterUpdate
    // afterSave
    // callback
    user.updateAttribute('email', 'email@example.com', callback);
    // beforeValidate
    // afterValidate
    // beforeSave
    // beforeUpdate
    // afterUpdate
    // afterSave
    // callback
    user.destroy(callback);
    // beforeDestroy
    // afterDestroy
    // callback
    User.create(data, callback);
    // beforeValidate
    // afterValidate
    // beforeCreate
    // beforeSave
    // afterSave
    // afterCreate
    // callback

    SEE 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 = new Schema('mycouch', {host:.., port:...});
    

    In that case your adapter should be named as 'jugglingdb-mycouch' npm package.

    Testing [outdated]

    TODO: upd this section

    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):

    var jdb = require('jugglingdb'),
    Schema = jdb.Schema,
    test = jdb.test;
    
    var schema = new Schema(__dirname + '/..', {host: 'localhost', database: 1});
    
    test(module.exports, schema);
    

    Each adapter could add specific tests to standart bucket:

    test.it('should do something special', function (test) {
        test.done();
    });
    

    Or it could tell core to skip some test from bucket:

    test.skip('name of test case');
    

    To run tests use this command:

    npm test
    

    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://1602.github.com/jugglingdb/ 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.
    

    Bitdeli Badge

    Keywords

    none

    Install

    npm i jugglingdb

    DownloadsWeekly Downloads

    1,357

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    878 kB

    Total Files

    122

    Last publish

    Collaborators

    • avatar