Table of Contents

• Introduction
• Install
  • Available adapters
• How does it work
  • Connection
  • Inserting data
  • Selecting data
    • .find()
    • .findOne()
    • .findAll()
  • Counting data
  • Updating data
    • .update()
    • .updateAll()
  • Deleting data
    • .delete()
    • .deleteAll()
• Contributing
• Community

Introduction

Fruit is a NodeJS ORM for database manipulations. This project is currently in Alpha version, so using it in production is at your own risk.

Feel free to contribute to this awesome project.

Install

The Fruit package needs to be installed along with an adapter, you can choose one of the available adapters bellow or write your own.

Available adapters

• fruit-mongodb
• fruit-mysql
• fruit-postgresql
• ... Help us by creating other adapters

To use Fruit with mongodb for example, you can install both fruit and fruit-mongodb.

$ npm install fruit fruit-mongodb

If you want to install fruit with all the adapters, you can take a look at fruits package

How does it work

First you need to require both the fruit module and the adapter, for example let's use fruit-mongodb

  var Fruit   = require('fruit')
    , adapter = require('fruit-mongodb');

Then you need to instantiate the fruit object

  var fruit = new Fruit(mongodbAdapter);

Connection

To test connection to the database, you need to pass options as arguments. Those options are the information needed to get connected to the database. You need to check documentation for the adapter of your choice.

  fruit.connect(options)
    .success(successCallBack)
    .error(errorCalBack);

You can also specify your options without testing the connection to the database

  var fruit = new Fruit(adapter).config(options);

  // or you can do this

  var fruit = new Fruit(adapter.config(options));

Inserting data

To insert data, you can use the .insert() method:

  function successCallBack (results) {
    console.log(results);
  }

  function errorCallBack (error) {
    console.log(error);
  }

  fruit.insert({ name: 'Khalid', age: 26 })
    .into(collectionName)
    .success(successCallBack)
    .error(errorCallBack);

If data was successfully inserted, the results passed as argument to the successCallBack would be like this:

  {
      result : {
          success       : true
        , affectedCount : 1
        , count         : 1
      }
    , insertedId : [1] // id of the inserted row ( _id for mongodb )
  }

You can also insert multiple rows at the same time

  var collectionName = 'users'
    , data = [
        { name: 'Khalid', age: 26 }
      , { name: 'Ahmed', age: 29 }
    ];

  fruit.insert(data)
    .into(collectionName)
    .success(successCallBack)
    .error(errorCallBack);

Selecting data

To filter data, you may need to call one of the methods .find(), .findOne(), .findAll()

.find():

This method allows you to look for data that fulfills the specified conditions

  var collectionName  = 'users'
    , condition       = { name: 'Khalid' };

  fruit.find(condition)
    .from(collectionName)
    .success(successCallBack)
    .error(errorCallBack);

The data found and passed as argument to the success callBack will be an array of models created using fishbone. Each model has columns as attributes and a number of useful methods.

• .print() : It prints the model as JSON on the console using the package jsome.
• .save() : It updates changes made on the model directly to the database. It returns a promise.
• .delete() : It deletes the concerned row from the database. It returns a primise.
• .toJSON() : It converts results to JSON.

examples :

If you need to update or delete records, you can use .update() and .delete()

  // using .save() method
  fruit.find({ name : 'Khalid' })
    .from('users')
    .success(function (results) {
      results[0].name; // 'Khalid'
      results[0].age = 30;
      results[0].save()
        .success(successCB)
        .error(errorCB)
    });

  // using .delete() method
  fruit.find({ name : 'Khalid' })
    .from('users')
    .success(function (results) {
      results[0].name; // 'Khalid'
      if(results[0].age == 30) {
        results[0].delete()
          .success(successCB)
          .error(errorCB)
      }
    });

You also can specify an offset and a limit :

  var collectionName  = 'users'
    , condition       = { name: 'Khalid' };

  fruit.find(condition)
    .from(collectionName)
    .offset(5)
    .limit(10)
    .success(successCallBack)
    .error(errorCallBack);

.findOne():

This method is exactly like .find() but it returns only one model, not an array. The only difference on its usage, is that it can't be combined with offset and limit.

.findAll():

This method doesn't take any filters, it returns all data of a table or a collection.

  fruit.findAll('users')
    .success(successCallBack)
    .error(errorCallBack);

Counting data

To count rows fulfilling a condition, you can use the .count() method

  fruit.count('users')
    .where({ name : 'Khalid' })
    .success(function (count) {
      console.log(count);
    })

To count all the rows of a table, you can call it without adding .where() method

  fruit.count('users')
    .success(function (count) {
      console.log(count);
    })

Updating data

There are two methods to update data, .update() and .updateAll(). The difference between them is that .update() method, updates only one row, and the .updateAll() updates many. On MySQL when you run an update query without condition, you are updating all the rows. Fruit reduces the damage of day dreaming developers. If you need to update many rows, you actually need to type updateAll.

.update():

Updating one row :

  fruit.update('users')
    .set({ age : 30 })
    .where({ name : 'Khalid' })
    .success(successCallBack)
    .error(errorCallBack)

You can also call update without .where() method.

  fruit.update('users')
    .set({ age : 30 })
    .success(successCallBack)
    .error(errorCallBack)

The arguments passed to the successCallBack would be like this :

  {
      result : {
          success       : true
        , affectedCount : 1
        , count         : 1
      }
  }

.updateAll():

Updating many rows :

  fruit.updateAll('users')
    .set({ age : 30 })
    .where({ name : 'Khalid' })
    .success(successCallBack)
    .error(errorCallBack)

You also can use it without .where() method.

The argument passed to the successCallBack is similar to the one described for .update()

Deleting data

There are two methods to delete data, .delete() and .deleteAll(). The difference between them is that .delete() method, deletes only one row, and the .deleteAll() deletes many.

.delete():

Deleting one row :

  fruit.delete('users')
    .where({ name : 'Khalid' })
    .success(successCallBack)
    .error(errorCallBack)

You can also call delete without .where() method.

  fruit.delete('users')
    .success(successCallBack)
    .error(errorCallBack)

The argument passed to the successCallBack is similar to the one described for .update()

.deleteAll():

Deleting many rows :

  fruit.deleteAll('users')
    .where({ name : 'Khalid' })
    .success(successCallBack)
    .error(errorCallBack)

You also can use it without .where() method.

The argument passed to the successCallBack is similar to the one described for .update()

Contributing

All contributions are welcome. Let's get this project to the next level. Significant and valuable contributions will allow you to be part of Fruit organisation. See the contribution guide for more details

Community

If you'd like to chat and discuss this project, you can find us here:

• Mailing list: https://groups.google.com/forum/#!forum/nodefruit
• 

Back to TOC