couchbase-driver v0.5.2

couchbase-driver

An improved version of the official Couchbase driver.

Installation

npm install couchbase-driver

Overview

A simple alternative driver for Couchbase that wraps the Bucket from existing driver with the following modifications:

• get works on a single key or an array of keys, calling Bucket.getMulti if appropriate. Automatically handles key not found errors and doesn't return an error in that scenario. In case of multiple keys, optionally returns an array of missing keys.
• remove also handles key not found errors more gracefully.
• getAndLock also handles key not found errors more gracefully.
• adds atomic function that tries to do perform getAndLock + transform + specified database operation utilizing CAS in one step until success or maximum retries have occurred. By default we use getAndLock to lock the document while we transform and perform document operation and unlock. Optionally we can use normal get function.
• adds Promise support so that functions call be called with either Node-style callbacks or with Promises.
• adds option to automatically retry operations on Couchbase temporary errors. Uses async.retry and is configurable with the tempRetryTimes, tempRetryInterval and retryTemporaryErrors options (defaults to false).
• adds getServerVersion function that attempts to get the server version from the cluster.

Usage

Creating:

const couchbase = require('couchbase');
const Driver = require('couchbase-driver');
const cluster = new couchbase.Cluster('couchbase://127.0.0.1');
const bucket = cluster.openBucket('default');
const driver = Driver.create(bucket);

Simple retrieval:

driver.get('my_doc_key', (err, res) => {
  if (err) return console.log(err)
  console.dir(res.value)
});

If key does not exist err and res will be undefined.

Getting multiple documents:

driver.get(['my_doc_key_1', 'my_doc_key_2', 'my_missing_doc_key_3'], (err, results, missing) => {
  if (err) return console.log(err);
  if (mising.length > 0) console.dir(missing); // ['my_missing_doc_key_3']
  console.dir(res.value);
});

"Atomic" transformations can be achieved using the atomic function which attempts to do get + transform + specified database operation where CAS in get and the final operation have to match. This uses async.retry until successful or maximum retries have occurred, which can be specified in the Driver construction or as function option parameter.

function transform(doc) {
  doc.foo = 'bar';
  return {
    value: doc,
    action: Driver.OPERATIONS.UPSERT
  };
}

driver.atomic('my_doc_key', transform, (err, res) => {
  if(err) return console.dir(err);
  console.dir(res);
});

With promises:

const result = await driver.get('mykey');
console.dir(result.value); // document

Note that with Promise style call and multiple keys we do not get misses.

const results = await driver.get(['mykey1', 'mykey2']);
console.dir(_.map(results, 'value')); // array of documents

API Reference

Driver

A simple alternative driver for Couchbase that wraps the Bucket from existing driver and improves get and remove methods and adds atomic method.

Kind: global class

• Driver
  • new Driver(bucket, options)
  • instance
    • .OPERATIONS
    • .get(keys, options, fn)
    • .getAndLock(key, options, fn)
    • .remove(key, options, fn)
    • .insert(key, value, options, fn)
    • .upsert(key, value, options, fn)
    • .atomic(key, transform, options, fn)
    • .getServerVersion(fn)
  • static
    • .OPERATIONS
    • .OPERATIONS : enum
    • .isKeyNotFound(err)
    • .isTemporaryError(err)
    • .create(bucket, options) ⇒ Driver

new Driver(bucket, options)

Constructs the new instance. This should not be called directly, but rather use Driver.create().

driver.OPERATIONS

Get operation enums

Kind: instance property of Driver
Example

const Driver = require('couchbase-driver');
const driver = Driver.create(bucket);
console.log(driver.OPERATIONS.UPSERT);

driver.get(keys, options, fn)

A simplified get. Properly handles key not found errors. In case of multi call, returns array of found and an array of misses.

Kind: instance method of Driver

Example

driver.get('my_doc_key', (err, res) => {
  if (err) return console.log(err)
  console.dir(res.value)
}

Example

driver.get(['my_doc_key_1', 'my_doc_key_2', 'my_missing_doc_key_3'], (err, results, missing) => {
  if (err) return console.log(err);
  if (mising.length > 0) console.dir(missing); // ['my_missing_doc_key_3']
  console.dir(res.value);
});

driver.getAndLock(key, options, fn)

Our implementation of Bucket.getAndLock that properly ignores key not found errors.

Kind: instance method of Driver

Example

driver.getAndLock('my_doc_key', (err, res) => {
  if (err) return console.log(err);
  console.dir(res.value)
});

driver.remove(key, options, fn)

Our implementation of Bucket.remove that properly ignores key not found errors.

Kind: instance method of Driver

Example

driver.remove('my_doc_key', (err, res) => {
  if (err) return console.log(err);
});

driver.insert(key, value, options, fn)

Our implementation of Bucket.insert that can recover from temporary errors.

Kind: instance method of Driver

Example

driver.insert('my_doc_key', "doc_contents", (err, res) => {
  if (err) return console.log(err);
});

driver.upsert(key, value, options, fn)

Our implementation of Bucket.upsert that can recover from temporary errors.

Kind: instance method of Driver

Example

driver.upsert('my_doc_key', "doc_contents", (err, res) => {
  if (err) return console.log(err);
});

driver.atomic(key, transform, options, fn)

Performs an "atomic" operation where it tries to first get the document given the key, then perform the function transform on the value and then write using the CAS value in the upsert. If the final document operation fails due to a CAS error, the whole process is retried.

Kind: instance method of Driver

Example

function transform(doc) {
  doc.foo = 'bar';
  return {
    value: doc,
    action: OPERATIONS.UPSERT
  };
}

driver.atomic('my_doc_key', transform, (err, res) => {
  if(err) return console.log(err);
  console.dir(res);
});

driver.getServerVersion(fn)

Attempts to get the lowest couchbase server version from the nodes in the cluster.

Warning This depends on undocumented internals of Node.js couchbase library

Kind: instance method of Driver

Example

driver.getServerVersion((err, version) => {
  if(err) return console.log(err);
  console.log(version);
});

Driver.OPERATIONS

Get operation enums

Kind: static property of Driver
Example

const Driver = require('couchbase-driver');
console.log(Driver.OPERATIONS.UPSERT);

Driver.OPERATIONS : enum

Enum for Database operations

Kind: static enum of Driver
Read only: true
Properties

Driver.isKeyNotFound(err)

Determines if error is a "key not found" error

Kind: static method of Driver

Example

Driver.isKeyNotFound(err);

Driver.isTemporaryError(err)

Determines if error is a "Temporary" error https://developer.couchbase.com/documentation/server/current/sdk/nodejs/handling-error-conditions.html

Kind: static method of Driver

Example

Driver.isTemporaryError(err);

Driver.create(bucket, options) ⇒ Driver

Create a Driver object by wrapping the Couchbase bucket and creates a new Driver instance and adds Promise support to the instance.

Kind: static method of Driver

Example

const couchbase = require('couchbase');
const Driver = require('couchbase-driver');
const cluster = new couchbase.Cluster('couchbase://127.0.0.1');
const bucket = cluster.openBucket('default');
const driver = Driver.create(bucket);

Debug logging

debug package is used for debug logging.

DEBUG=couchbase-driver node app.js

License

Copyright 2015 Bojan D.

Licensed under the MIT License.