MongoDb client for Nodejs

This node module provides a set of methods to authenticate against MongoDb's services and execute commands. The module was created as part of KidoZen project, as a connector for its Enterprise API feature.

This module is based on module mongodb.

Installation

Use npm to install the module:

> npm install mongodb-api

Runing tests

Use npm to run the set of tests

> npm test

API

Due to the asynchrounous nature of Nodejs, this module uses callbacks in requests. All callbacks have 2 arguments: err and data.

function callback (err, data) {
    // err contains an Error class instance, if any
    // data contains the resulting data
} 

Constructor

The module exports a Class and its constructor requires a configuration object with following properties

• url: Required string. Connection string URI format
• timeout: Optional integer for the session timeout in milleseconds. Default 15 minutes.
• username: Optional MongoDb's user name.
• password: Optional user's password

var Mongo = require("mongodb-api");
var mongo = new Mongo({ url: "mongodb://localhost/test", timeout: 5*60*1000 }); // Timeout of 5 minutes

Methods

authenticate(credentials, callback)

This method should be used for authenticate user's credentials. A successed authentication will return an object intance containing the auth property. The value of this property is the athentication token that could be required by other methods.

Parameters:

• credentials: A required object instance containing authentication's parameters:
  • username: A string with a MongoDB's user name.
  • password: A string containing the user's password.
• callback: A required function for callback.

mongo.authenticate({ username:"foo", password: "bar" }, function(err, result) {
    if (err) return console.error(err);
    console.log(result.auth);
});

lookupMethod(name, callback)

Use this method to get a Function object. The Function object represents the function to execute on MongoDB. This method adds dinamically the returned Function to the connector's instance.

The methods's names have the same sintax that the MongoDb's console, for instance:

• "db.collectionNames": Represents the 'collectionName' method on current Db.
• "db.drop": Represents the 'drop' method on current Db.
• "db.customer.find": Represents the 'find' method on collection 'customer'.
• "db.orders.pending.insert": Represents the 'insert' method on collection 'orders.pending'.

Parameters:

• name: A required string. Name of the method. Sintax: "db.[collection.]method"
• callback: A required function for callback. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the Function object or null if the a method with that name does not exist.

// looks for the db's collectionNames method.
mongo.lookupMethod("db.collectionNames", function(err, method) {
    if (err) return console.error(err);    

    method(function(err, names) {        console.log ("Collection names:", names);
    });

    // Invokes same method again. It was added dinamically to the instance by the lookupMethod
    mongo["db.collectionNames"](function(err, names) {
        console.log ("Collection names (again):", names);
    });
});

List of available MongoDb methods.

All there methods have the same signature, their have two arguments: options and callback.

options must be an object instance containig all parameters for the method. callback must be a function.

Methods for a db instance

• addUser ({ usr: ..., pwd: ...[, options: ...] }, callback)
• collectionNames ({ [collectionName: ...][, options: ...] }, callback)
• command ({ selector: ...[, options: ...] }, callback)
• createCollection ({ collectionName: ...[, options: ...] }, callback)
• createIndex ({ collectionName: ..., fieldOrSpec: ...[, options: ...] }, callback)
• dropCollection ({ collectionName: ... }, callback)
• dropDatabase ({ }, callback)
• dropIndex ({ collectionName: ..., name: ...[, options: ...] }, callback)
• ensureIndex ({ collectionName: ..., fieldOrSpec: ...[, options: ...] }, callback)
• lastError ({ [options: ...] }, callback)
• previousErrors ({ [options: ...] }, callback)
• removeUser ({ usr: ...[, options: ...] }, callback)
• renameCollection ({ fromCollection: ..., toCollection: ...[, options: ...] }, callback)
• resetErrorHistory ({ [options: ...] }, callback)

Methods for a collection instance

• aggregate ({ array: ...[, options: ...] }, callback)
• count ({ [query: ...][, options: ...] }, callback)
• createIndex ({ fieldOrSpec: ...[, options: ...] }, callback)
• distinct ({ key: ...[, query: ...][, options: ...] }, callback)
• drop ({ }, callback)
• dropAllIndexes ({ [options: ...] }, callback)
• dropIndex ({ name: ...[, options: ...] }, callback)
• ensureIndex ({ fieldOrSpec: ...[, options: ...] }, callback)
• find ({ query: ...[, options: ...] }, callback)
• findAndModify ({ query: ..., sort: ..., doc: ...[, options: ...] }, callback)
• findAndRemove ({ query: ..., sort: ...[, options: ...] }, callback)
• findOne ({ query: ...[, options: ...] }, callback)
• geoHaystackSearch ({ x: ..., y: ...[, options: ...] }, callback)
• geoNear ({ x: ..., y: ...[, options: ...] }, callback)
• group ({ keys: ..., condition: ..., initial: ..., reduce: ..., finalize: ..., command: ...[, options: ...] }, callback)
• indexExists ({ indexNames: ... }, callback)
• indexInformation ({ [options: ...] }, callback)
• indexes ({ }, callback)
• insert ({ docs: ...[, options: ...] }, callback)
• isCapped ({ }, callback)
• mapReduce ({ map: ..., reduce: ...[, options: ...] }, callback)
• options ({ }, callback)
• remove ({ [selector: ...][, options: ...] }, callback)
• rename ({ newName: ...[, options: ...] }, callback)
• save ({ doc: ...[, options: ...] }, callback)
• stats ({ [options: ...] }, callback)
• update ({ selector: ..., doc: ...[, options: ...] }, callback)