Amazon DAX Client for JavaScript
raw JSON →The `amazon-dax-client` package provides a client library for Node.js applications to interact with Amazon DynamoDB Accelerator (DAX), a fully managed caching service. DAX offers high-performance in-memory caching for DynamoDB, significantly boosting read performance by up to 10 times, even at millions of requests per second. This client is API compatible with DynamoDB's AWS SDK v2, allowing for minimal code changes to integrate DAX caching into existing applications. The current stable version, 1.2.10, focuses on optimizing connection clean-up and addressing various connection stability and data parsing issues, indicating an active maintenance and bug-fix release cadence for the v1.x branch. It differentiates itself by providing a seamless caching layer for AWS SDK v2 DynamoDB operations, transparently handling caching logic. For applications utilizing AWS SDK for JavaScript v3, a separate client, `@aws-sdk/client-dax`, is available and features a modular architecture, which represents a significant shift in usage patterns.
Common errors
error NeedMoreData: not enough data ↓
amazon-dax-client version 1.2.8 or higher, where this specific error was addressed and fixed. error SocketTimeout caused by connection establishment ↓
amazon-dax-client version 1.1.3 or higher, which increased the default connectTimeout and allowed it to be configurable. Further fixes in 1.1.2 also addressed socket timeouts during connection. error Unrecoverable request timeout after DAX node restart ↓
amazon-dax-client version 1.2.2 or higher, which includes specific fixes for unrecoverable request timeouts and connection timeouts during DAX server restarts. error Connection leaks on timeout / socket leaks on errors ↓
amazon-dax-client version 1.1.4, 1.1.2, 1.1.1, or later for fixes addressing connection and socket leaks in various error scenarios. The latest 1.2.10 includes further optimizations for connection clean-up. Warnings
breaking This `amazon-dax-client` package is designed for AWS SDK for JavaScript v2. If you are migrating to or starting a new project with AWS SDK for JavaScript v3, you must use the `@aws-sdk/client-dax` package instead, which has a different import and instantiation pattern. ↓
gotcha The `amazon-dax-client` is strictly a Node.js-only library and does not support browser environments. ↓
gotcha Earlier versions (pre-1.2.7) had issues with `AuthenticationRequiredException` not being retryable, leading to unhandled errors during transient authentication failures. ↓
gotcha Versions prior to 1.2.5 might experience issues or breaking changes if running on Node.js versions incompatible with `antlr4`'s 4.9.0 release, as `antlr4` was explicitly locked to `4.8.x` to prevent this. ↓
gotcha Persistent connection leaks and unrecoverable request timeouts were common in older versions, particularly following DAX node restarts or connection establishment issues. ↓
Install
npm install amazon-dax-client yarn add amazon-dax-client pnpm add amazon-dax-client Imports
- AmazonDaxClient wrong
import { AmazonDaxClient } from 'amazon-dax-client';correctconst AmazonDaxClient = require('amazon-dax-client'); - AWS.DynamoDB.DocumentClient
const AWS = require('aws-sdk'); const doc = new AWS.DynamoDB.DocumentClient({ service: dax }); - AWS.DynamoDB
const AWS = require('aws-sdk'); const dax = new AmazonDaxClient({ endpoints: [endpoint], region: region }); const ddbWithDax = dax;
Quickstart
const AmazonDaxClient = require('amazon-dax-client');
const AWS = require('aws-sdk'); // Make sure aws-sdk is installed
// Replace with your actual DAX cluster discovery endpoint
const endpoint = process.env.DAX_CLUSTER_ENDPOINT ?? 'dax://my-cluster.abc123.dax-clusters.us-east-1.amazonaws.com';
const region = process.env.AWS_REGION ?? 'us-east-1';
console.log(`Connecting to DAX endpoint: ${endpoint} in region: ${region}`);
try {
// Instantiate the DAX client
const dax = new AmazonDaxClient({ endpoints: [endpoint], region: region });
// Integrate DAX with DynamoDB DocumentClient
const docClient = new AWS.DynamoDB.DocumentClient({ service: dax });
// Example: Put an item using DocumentClient with DAX
const tableName = 'MyTestTable'; // Replace with your table name
const item = { pk: '123', sk: 'data', attribute: 'cached value' };
console.log('Putting item with DAX-enabled DocumentClient...');
docClient.put({ TableName: tableName, Item: item }, (err, data) => {
if (err) {
console.error('Error putting item:', JSON.stringify(err, null, 2));
} else {
console.log('Successfully put item:', data);
// Example: Get the item using DocumentClient with DAX
console.log('Getting item with DAX-enabled DocumentClient...');
docClient.get({ TableName: tableName, Key: { pk: '123', sk: 'data' } }, (getErr, getData) => {
if (getErr) {
console.error('Error getting item:', JSON.stringify(getErr, null, 2));
} else {
console.log('Successfully got item:', getData);
}
});
}
});
} catch (e) {
console.error('Failed to initialize DAX client:', e);
}