Atomic operations

The Node.js Couchbase SDK supports several operations that allow one-step, atomic changes to documents. These operations include counter, prepend, and append functions.

Counter operation

The counter() method enables you to implement an atomic counter as a Couchbase document. These operations expect UTF-8 encoded string representations of the number. You can either execute this operation against a previously created document, or create a new document by using the initial property passed as an option. More information about the initial property is available below.

The following example shows how to use the counter() method to increment your counter and get the value back:

var myBucket = myCluster.openBucket();
myBucket.insert('document_name', 10, function() {
  myBucket.counter('document_name', 1, function(err, res) {
    if (err) {
      console.log('operation failed', err);
      return;
    }

    console.log('success!', res);
  });
});

Sample output from the example:

success! { cas: { '0': 3085434880, '1': 1662465098 }, value: 11 }

The following example shows how to use the counter() method to decrement your counter and get the value back:

var myBucket = myCluster.openBucket();
myBucket.set('document_name', 10, function() {
  myBucket.counter('document_name', -1, function(err, res) {
    if (err) {
      console.log('operation failed', err);
      return;
    }

    console.log('success!', res);
  });
});

Sample output from the example:

success! { cas: { '0': 9977273, '1': 3468060 }, value: 9 }

You can additionally perform a counter operation with an initial value specified. In this case, the document will be created if it does not exist. The initial property will do nothing if the document already exists.

var myBucket = myCluster.openBucket();
myBucket.counter('document_name', 1, {initial:10}, function(err, res) {
  if (err) {
    console.log('operation failed', err);
    return;
  }

  console.log('success!', res);
});

Sample output from the example:

success! { cas: { '0': 9977273, '1': 3468060 }, value: 10 }

Note: If a new counter document is created by using the initial property, the counter is set to the value of initial, not initial+offset.

Append and prepend operations

The append and prepend operations allow you to perform a binary append or prepend to a Couchbase document.

Note: This operation is performed without any consideration for data type, thus appending a JSON document to a JSON document will result in an invalid object (for instance: {}{}).

The following is an example of how to use the append() method to add further text to an already existing document:

var myBucket = myCluster.openBucket();
// Insert a starting document
myBucket.insert('document_name', 'Beautiful', function() {
  // Append some content to it
  myBucket.append('document_name', 'World!', function() {
    // Prepend some more text
    myBucket.prepend('document_name', 'Hello ', function() {
      // Retrieve its updated contents
      myBucket.get('document_name', function(err, res) {
        console.log(err, res);
      });
    });
  });
});

Sample output from the example:

null { cas: { '0': 7112265, '1': 69427 }, value: 'Hello Beautiful World!' }