node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



NPM Version NPM Downloads Build Status

NodeJS request-promise based client for IBM Bluemix Data Cache service.


npm install datacache-client

Using the Data Cache client in a Node JS application:

var DataCacheClient = require('datacache-client');
var dcClient = new DataCacheClient();
// save data to storage 
dcClient.put('key-name', {item: 'test'})
    .then(function(resp) {
     // data saved - continue your logic 
        console.log('Data saved to storage at key "key-name"');
    }).catch(function(err) {
     // something went wrong 
        console.log('Failed to save data to storage');
// get data from storage 
    .then(function(resp) {
     // data loaded in resp.body 
        var obj = resp.body;
        console.log('Object returned with item ' + obj.item);
    }).catch(function(err) {
     // no data found 
        console.log('Failed to retrieve data from storage');
// destroy data 
    .then(function(resp) {
     // data deleted from storage 
        console.log('Data deleted for "key-name"');
    }).catch(function(err) {
     // no data found 
        console.log('Failed to delete data from storage');


.put(key, data, ttl)

key - string - name of the key to put data under in DataCache

data - Object|string - Data to be saved to cache service - based on the contentType parameter for the client it saves it as JSON or plain text

ttl - optional - overrides the client Time To Live default value (seconds)

returns: Promise


key - string - key name to be used for retrieval of data from cache storage

returns: Promise - resolved value has the full response (check resolveWithFullResponse parameter for request-promise)

ex: resolved.body - Object retrieved from cache resolved.statusCode - Status code from REST API


key - string - key name to be used for deletion

returns: Promise - resolved value has the full response (check resolveWithFullResponse parameter for request-promise)

Storage Options

Bellow is an example with the full list of parameters - default values for optional ones:

var store = new DataCacheClient({
        // required parameters when no custom client provided 
        restResource: '{gridName}',
        restResourceSecure: '{gridName}',
        gridName: '{gridName}',
        username: '{username}',
        password: '{password}',
        // optional parameters - default values 
        mapName: '{gridName}',
        eviction: 'LUT',
        locking: 'optimistic',
        contentType: 'application/json',
        secure: true,
        ttl: 3600,
        cfenvServiceName: null

Bluemix environment

The datacache client is looking first for DataCache service cfenv values. For the Bluemix NodeJS app with a DataCache service associated the required parameters are read from ENV variables (credentials):

Environment Variables > VCAP_SERVICES

    "system_env_json": {
      "VCAP_SERVICES": {
         "DataCache-dedicated": [
               "credentials": {
                 "catalogEndPoint": "...",
                 "restResource": "http://ip-numeric/resources/datacaches/SYS_GENERATED_GRIDNAME",
                 "restResourceSecure": "",
                 "gridName": "SYS_GENERATED_GRIDNAME",
                 "username": "sysGeneratedUsername",
                 "password": "sysGeneratedPass"
               "name": "datacache-service-name",
               "tags": []


defaults: VCAP_SERVICES credentials values

Depending on the "secure" value, one of them is required if not found in ENV variables by cfenv.


For a Bluemix application it is required to have the same value as for "gridName". A resource is identified with a complete URI as:



For non-Bluemix environments can be customized as a namespace for data.


  • 'LUT' - default - expires based on the Last Update Time
  • 'NONE' - data is stored indefinitly (until si programaticaly deleted)
  • 'LAT' - expires based on Last Access Time


  • 'optimistic' - default
  • 'pessimistic'


  • 'application/json' - default - turns on the JSON encoder/decoder for stored data
  • other - saves data as plain text


  • true - default - uses 'restResourceSecure' as store entrypoint
  • false - uses 'restResource' as store entrypoint


  • default storage time to live per client (seconds)


  • allows using multiple Data Cache services for same application - loads credentials from ENV using service name;
var dcClient = new DataCacheClient({'cfenvServiceName': 'datacache-service-name'});


PR code needs to pass the lint check and unit test

npm test

PR code should be covered by UT

npm run coverage


The module uses debug npm module - in order to turn the debuging on follow the steps:

Local environment:

$> DEBUG=datacache-client npm start

CF environmment (Bluemix) - using manifest.yml

path: .
# ... 
    DEBUG: datacache-client
  - datacache-service-name