@amazon-dax-sdk/lib-dax/README.md

Amazon DAX Document Client for JavaScript

# 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:
```sh
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
```javascript
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:
```javascript
// 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
```javascript
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
```javascript
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
```javascript
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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DAX.client.run-application-nodejs.html)

## Getting Help
Please use these community resources for getting help.

 * Follow Official Documentation for Node.js for more Details [AWS Dax Documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DAX.client.run-application-nodejs.html)
 * Ask a question on [StackOverflow](https://stackoverflow.com/) and tag it with `amazon-dynamodb-dax`
 * Ask a question on [the AWS DynamoDB forum](https://forums.aws.amazon.com/forum.jspa?forumID=131&start=0)
 * Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/)


## 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