Amazon DAX Client for JavaScript

raw JSON →
1.2.10 verified Tue Apr 21 auth: no javascript

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.

error NeedMoreData: not enough data
cause This error typically occurred in earlier versions due to issues in parsing server exception responses or insufficient data received.
fix
Upgrade to amazon-dax-client version 1.2.8 or higher, where this specific error was addressed and fixed.
error SocketTimeout caused by connection establishment
cause Connection timeouts could occur during the initial establishment of a connection to the DAX cluster, especially in versions prior to 1.1.3 and 1.1.2.
fix
Upgrade to 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
cause Older versions of the client could enter an unrecoverable state for requests if a DAX node restarted, leading to persistent timeouts.
fix
Upgrade to 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
cause Prior versions of the client had issues with connection and socket resources not being properly released during timeouts, validation errors, or general errors.
fix
Upgrade to 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.
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.
fix For AWS SDK v3, install `@aws-sdk/client-dax` (`npm install @aws-sdk/client-dax`) and use `import { DAXClient } from '@aws-sdk/client-dax';` for ESM, or `const { DAXClient } = require('@aws-sdk/client-dax');` for CJS.
gotcha The `amazon-dax-client` is strictly a Node.js-only library and does not support browser environments.
fix Ensure the client is only used in Node.js environments. For browser-based applications that need to interact with DAX, you would typically route requests through a backend service using the Node.js client or the AWS SDK for JavaScript directly.
gotcha Earlier versions (pre-1.2.7) had issues with `AuthenticationRequiredException` not being retryable, leading to unhandled errors during transient authentication failures.
fix Upgrade to `amazon-dax-client` version 1.2.7 or higher to benefit from improved retry logic for `AuthenticationRequiredException`.
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.
fix Upgrade to `amazon-dax-client` version 1.2.5 or higher to ensure `antlr4` dependency compatibility and avoid potential runtime errors in specific Node.js environments.
gotcha Persistent connection leaks and unrecoverable request timeouts were common in older versions, particularly following DAX node restarts or connection establishment issues.
fix Always use the latest 1.2.x version (currently 1.2.10) to benefit from continuous improvements in connection management, timeout handling, and socket leak prevention.
npm install amazon-dax-client
yarn add amazon-dax-client
pnpm add amazon-dax-client

This quickstart demonstrates how to instantiate the `AmazonDaxClient` and integrate it with the `AWS.DynamoDB.DocumentClient` to perform basic `put` and `get` operations, leveraging DAX for caching. It assumes `aws-sdk` is already installed and configures region and endpoint from environment variables or defaults.

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);
}