Amazon DAX Document for JavaScript

DAX is a DynamoDB-compatible caching service that enables you to benefit from fast in-memory performance for demanding applications.

Overview

The DaxDocument client simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values. This abstraction
annotates native JavaScript types supplied as input parameters, as well as converts annotated response data to native JavaScript types.
This client library provides access from NodeJS to DAX.

Installing

The Amazon DAX client only runs from NodeJS, and can be installed using npm:

npm install @amazon-dax-sdk/lib-dax

Usage and Getting Started

You can follow the Getting Started tutorial at:

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DAX.client.sample-app.html

To quickly use DaxDocument, replace DynamoDBDocument full client with DaxDocument:

Initializing DaxDocument

import { DaxDocument } from '@amazon-dax-sdk/lib-dax';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';

// Override Client ...
var client = DynamoDBDocument.from(new DynamoDBClient({region: region}));

// with this ...
const endpoint = "your-cluster-discovery-endpoint";
client = new DaxDocument({endpoints: endpoint, region: region});

The DAX Cluster Discovery Endpoint can be found in the AWS console or by using aws dax describe-clusters from the command line.

Creating a connection to your DAX cluster requires using the Cluster Discovery Endpoint URL returned in the DescribeClusters response as the endpoint.

For example:

// Format: const endpoint = <ClusterDiscoveryEndpoint.URL>;
// Unencrypted Cluster Endpoint
const endpoint = 'dax://my-cluster.abc123.dax-clusters.us-east-1.amazonaws.com';
// Encrypted Cluster Endpoint
const endpoint = 'daxs://my-cluster.abc123.dax-clusters.us-east-1.amazonaws.com';

Calling Operations

import { DaxDocument } from '@amazon-dax-sdk/lib-dax';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';

// Replace this ...
var client = DynamoDBDocument.from(new DynamoDBClient({region: region}));

// with this ...
const endpoint = "your-cluster-discovery-endpoint";
client = new DaxDocument({endpoints: endpoint, region: region});

var params = {
  TableName: 'TryDaxTable',
  pk: 1,
  sk: '1'
}
// Similarly for other API calls
client.get(params).then((res)=>{
  console.log(res);
}).catch(err=>{
  throw err;
});

daxPaginateScan Usage Example

import { DaxDocument, daxPaginateScan } from "@amazon-dax-sdk/lib-dax";
import { DynamoDBDocument, paginateScan } from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

var region = "eu-west-1";
var client = DynamoDBDocument.from(new DynamoDBClient({region: region}));
if(process.argv.length > 2) {
  client = new DaxDocument({
    region: region,
    endpoint: process.argv[2]
  });
}

async function scanPaginate(clientConfig, params) {
  var paginator = paginateScan(clientConfig, params);
  if(process.argv.length > 2) {
    paginator = daxPaginateScan(clientConfig, params);
  }
  for await (const page of paginator) {
    console.log(page);
  }
}
var scanParams = {
  TableName: 'TryDaxTable',
};
await scanPaginate({client, pageSize: 10}, scanParams);

daxPaginateQuery Usage Example

import { DaxDocument, daxPaginateQuery } from "@amazon-dax-sdk/lib-dax";
import { DynamoDBDocument, paginateQuery } from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

var region = "eu-west-1";
var client = DynamoDBDocument.from(new DynamoDBClient({region: region}));
if(process.argv.length > 2) {
  client = new DaxDocument({
    region: region,
    endpoint: process.argv[2]
  });
}

async function queryPaginate(clientConfig, params) {
  var paginator = paginateQuery(clientConfig, params);
  if(process.argv.length > 2) {
    paginator = daxPaginateQuery(clientConfig, params);
  }
  for await (const page of paginator) {
    console.log(page);
  }
}
var queryParams = {
  TableName: tableName,
  KeyConditionExpression: "pk = :pkval and sk between :skval1 and :skval2",
  ExpressionAttributeValues: {
    ":pkval": 5,
    ":skval1": 1,
    ":skval2": 10
  }
};
await queryPaginate({client, pageSize: 10}, queryParams);

Retry Behavior

The DAX client implements different retry strategies depending on the type of error encountered.

Retry Conditions:

1. Decoder: 'DecoderException'
2. Unrecognized: 'UnrecognizedClientException'
3. MalformedResult: 'MalformedResultException'
4. EndOfStream: 'EndOfStreamException'
5. IllegalArgument: 'IllegalArgumentException'
6. NoRoute: 'NoRouteException'
7. ProvisionedThroughputExceeded: 'ProvisionedThroughputExceededException'
8. LimitExceeded: 'LimitExceededException'
9. RequestLimitExceeded: 'RequestLimitExceeded'
10. Throttling: 'ThrottlingException'
11. Connection: 'ConnectionException'

Throttling Errors

Errors related to throttling ('ProvisionedThroughputExceededException', 'LimitExceededException', 'RequestLimitExceeded', 'ThrottlingException') are retried using an exponential backoff strategy. This means the delay between retry attempts increases exponentially with each subsequent retry to avoid overwhelming the service.

Other Errors

All other retry-eligible errors (such as 'DecoderException', 'UnrecognizedClientException', 'MalformedResultException', 'EndOfStreamException', 'IllegalArgumentException', 'NoRouteException', 'ConnectionException') are retried immediately without any delay between attempts.

Special Case: waitForRecoveryBeforeRetrying

For certain error types where the DAX server sets the waitForRecoveryBeforeRetrying flag to true, the client will wait for recovery before attempting a retry. In these cases, the maxRetryDelay parameter controls the maximum amount of time to wait between retries.

Features not in parity with DynamoDBDocument

1. Use of Minimal Client is not supported by DaxDocument
2. Use of Middleware Stack is not supported by DaxDocument

For more details follow Official Documentation for Node.js AWS Dax Documentation

Getting Help

Please use these community resources for getting help.

• Follow Official Documentation for Node.js for more Details AWS Dax Documentation
• Ask a question on StackOverflow and tag it with amazon-dynamodb-dax
• Ask a question on the AWS DynamoDB forum
• Open a support ticket with AWS Support

Changes

3.0.3

• Optimized clean-up of connections during timeouts

3.0.2

• Added support to limit concurrent connections that a client instance can create per node in DAX cluster

3.0.1

• Initial release