readme.hbs

# couchbase-driver

An improved version of the official Couchbase driver.

## Installation

`npm install couchbase-driver`

## Overview

A simple alternative driver for [Couchbase](http://docs.couchbase.com/sdk-api/couchbase-node-client-2.1.4/) 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 <code>Promise</code> 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](https://developer.couchbase.com/documentation/server/current/sdk/nodejs/handling-error-conditions.html). Uses
[`async.retry`](http://caolan.github.io/async/docs.html#.retry) and is configurable with the <code>tempRetryTimes</code>,  <code>tempRetryInterval</code> and <code>retryTemporaryErrors</code> options (defaults to <code>false</code>).
* adds `getServerVersion` function that attempts to get the server version from the cluster.

## Usage

Creating:

```js
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:

```js
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:

```js
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`](http://caolan.github.io/async/docs.html#.retry) until successful or maximum retries have occurred,
which can be specified in the `Driver` construction or as function option parameter.

```js
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:

```js
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.

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

## API Reference

{{>all-docs~}}

## Debug logging

[debug](https://npmjs.com/package/debug) package is used for debug logging.

```sh
DEBUG=couchbase-driver node app.js
```

## License

Copyright 2015 Bojan D.

Licensed under the MIT License.