Couchbase Lite Plugin for Telerik NativeScript

Couchbase Lite is a NoSQL embedded database for mobile devices. It is a replacement for common database technologies like SQLite and Core Data.

Configuration

To add this plugin to your Angular or vanilla JavaScript NativeScript project, execute the following from the Terminal or Command Prompt:

tns plugin add nativescript-couchbase

If you wish to try either of the demo applications that are bundled with this project, execute the following after cloning the repository:

npm install
npm run deploy-android-angular

For the third line, the list of options are:

npm run deploy-android-angular
npm run deploy-android-vanilla
npm run deploy-ios-angular
npm run deploy-ios-vanilla

If you're using TypeScript and wish to make use of the type definitions for this plugin, add the following line to your project's references.d.ts file:

/// <reference path="./node_modules/nativescript-couchbase/couchbase.d.ts" />

Without the above line included, your TypeScript compiler may throw errors during the build.

Usage

Including the Plugin in Your Project

var couchbaseModule = require("nativescript-couchbase");

Creating or Opening an Existing Database

var database = new couchbaseModule.Couchbase("test-database");

Managing the Data with CRUD Operations

Creating a New Document

var documentId = database.createDocument({
    "firstname": "Nic",
    "lastname": "Raboy",
    "address": {
        "city": "San Francisco",
        "state": "CA",
        "country": "USA"
    }
    "twitter": "https://www.twitter.com/nraboy"
});

Retrieving an Existing Document

var person = database.getDocument(documentId);

Updating an Existing Document

database.updateDocument(documentId, {
    "firstname": "Nicolas",
    "lastname": "Raboy",
    "twitter": "https://www.twitter.com/nraboy"
});

Deleting a Document

var isDeleted = database.deleteDocument(documentId);

Querying with MapReduce Views

Knowing the document id isn't always an option. With this in mind, multiple documents can be queried using criteria defined in a view.

Creating a MapReduce View

A MapReduce View will emit a key-value pair. Logic can be placed around the emitter to make the views more specific.

database.createView("people", "1", function(document, emitter) {
    emitter.emit(document._id, document);
});

Querying a MapReduce View

var rows = database.executeQuery("people", {descending : false, limit : 20,  skip : 1, startKey: "name to strat with", endKey:"name to end at"});
for(var i = 0; i < rows.length; i++) {
    personList.push(rows[i]);
}

The available options when querying a MapReduce View are as follows:

• startKey: the key to start at. The default value, null, means to start from the beginning.

• endKey: the last key to return. The default value, null, means to continue to the end.

• descending: If set to true, the keys will be returned in reverse order. (This also reverses the meanings of the startKey and endKey properties, since the query will now start at the highest keys and end at lower ones!)

• limit: If nonzero, this is the maximum number of rows that will be returned.

• skip: If nonzero, this many rows will be skipped (starting from the startKey if any.)

Synchronization with Couchbase Sync Gateway and Couchbase Server

Couchbase Lite can work in combination with Couchbase Sync Gateway to offer synchronization support between devices and platforms. Couchbase Sync Gateway is not a requirement to use Couchbase Lite if the goal is to only use it for offline purposes.

Couchbase Sync Gateway can be downloaded via the Couchbase Downloads Portal in the mobile section.

A demo configuration file for Sync Gateway is included in the demo directory. It can be started by executing the following from a Command Prompt or Terminal:

/path/to/sync/gateway/bin/sync_gateway /path/to/demo/sync-gateway-config.json

In the demo configuration file, Couchbase Server is not used, but instead an in-memory database good for prototyping. It can be accessed via http://localhost:4985/_admin/ in your web browser.

To replicate between the local device and server, the following must be added to your project:

var couchbaseModule = require("nativescript-couchbase");
database = new couchbaseModule.Couchbase("test-database");

var push = database.createPushReplication("http://sync-gateway-host:4984/test-database");
var pull = database.createPullReplication("http://sync-gateway-host:4984/test-database");
push.setContinuous(true);
pull.setContinuous(true);
push.start();
pull.start();

Data will now continuously be replicated between the local device and Sync Gateway.

Listening for Changes

database.addDatabaseChangeListener(function(changes) {
    for(var i = 0; i < changes.length; i++) {
        console.log(changes[i].getDocumentId());
    }
});

Plugin Development

The Couchbase NativeScript plugin is under active development. Changes to the API are infrequent in the underlying Couchbase Android and Couchbase iOS SDKs so as a result changes are infrequent in the JavaScript wrapper for NativeScript.

If you feel something is missing or you've found a bug, open a ticket so it can be corrected or submit a pull request and be recognized for your contributions.