dynamodb-atomic-counter

dynamodb-atomic-counter
=======================

This library provides atomic counters using Amazon DynamoDB. Each increment request
increments a counter value that is stored in a DynamoDB table (named "AtomicCounters" by default).
Multiple increment requests can be sent simultaneously but each request will receive a
unique value, therefore this library can be use to generate auto-increment ids.

Installation
------------

Execute the following command at the root of your project:

npm install dynamodb-atomic-counter

config
--------

This object is an instance of AWS.Config.
To configure the internal instance of AWS.DynamoDB,
you can follow one of the many methods described here or
manually using this config instance.

increment( counterId, options )
---------------------------------

This method increments the counter for the specified counterId.
It returns an AWS-SDK request
instance with a jQuery style promise interface applied to it.
See the jQuery documentation for details on how the promises work.
underscore.deferred is used to add the Promise interface to the returned request object.
Additionally, success, error, and complete callback can be provided in the second argument.
The increment method takes the following arguments:

* counterId: The unique name/identifier of the counter.
* options (optional): An options object to overwrite some of the default behaviour of the increment operation. All attributes in this object are optional.
* options.tableName: The name of the DynamoDB table that stores the counters. If not specified, it uses "AtomicCounters" by default.
* options.keyAttribute: The name of the attribute that stores the counter name/identifier. If not specified, it uses "id" by default.
* options.countAttribute: The name of the attribute that stores the last value generated for the specified counterId. If not specified, it uses "lastValue" by default.
* options.increment: Specifies by how much the counter should be incremented. If not specified, it uses 1 by default.
* options.success: Success callback function. It receives a single argument: the value (integer) generated by this increment operation for the specified counterId.
* options.error: Error callback function. If the DynamoDB UpdateItem request fails, the error callback is executed. It receives a single argument: the error object returned from AWS-SDK.
* options.complete: Complete callback function. This callback is executed when the increment operation is completed, whether or not it was successful. It receives a single argument: an integer, if the operation was successful, or an error object if it failed.
* options.context: The context object to use in all callbacks. If specified, the value of this within all callbacks will be options.context.

getLastValue( counterId, options )
------------------------------------

This method retrieves, from DynamoDB, the last generated value for the specified counterId. If the counter doesn't exist,
the success callback would receive 0 as the first argument.
It returns an AWS-SDK request
instance with a jQuery style promise interface applied to it.
See the jQuery documentation for details on how the promises work.
underscore.deferred is used to add the Promise interface to the returned request object.
Additionally, success, error, and complete callback can be provided in the second argument.
The getLastValue method takes the following arguments:

* counterId: The unique name/identifier of the counter.
* options (optional): The same options supported by the increment method are also supported by this method.

Basic Usage
-----------

The following few lines of code demonstrate basic usage of this library. Additional examples can be found in the examples.js file.

var atomicCounter = require( 'dynamodb-atomic-counter' );

// Configure AWS as needed
atomicCounter.config.update({ region: 'us-east-1' });

/**
* Increment the "Users" counter. Make sure there's a table named
* "AtomicCounters", with "id" (string) as the primary hash key,
* in your AWS account.
*/
atomicCounter.increment( 'Users' ).done(function (value) {
// value is the new incremented value.
}).fail(function (error) {
// An error occurred
}).always(function (valueOrError) {
// Executed whether or not the increment operation was successful
});

/**
* Retrieve the last value generated for the "Clients" counter.
*/
atomicCounter.getLastValue( 'Clients' ).done(function (lastValue) {
// lastValue is the last value generated for the "Clients" counter.
// If a values has not been generated before, lastValue would be 0.
}).fail(function (error) {
// An error occurred
}).always(function (valueOrError) {
// Executed whether or not the request was successful
});