The [AWS SDK for JavaScript V3 API Reference Guide](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) describes in detail all the API operations for the AWS SDK for JavaScript version 3 (V3).
# Migrate from version 2.x to 3.x of the AWS SDK for JavaScript
The AWS SDK for JavaScript version 3 is a major rewrite of version 2. The section describes the differences between the two versions and explains how to migrate from version 2 to version 3 of the SDK for JavaScript.
## Migrate your code to SDK for JavaScript v3 using codemod
AWS SDK for JavaScript version 3 (v3) comes with modernized interfaces for client configurations and utilities, which include credentials, Amazon S3 multipart upload, DynamoDB document client, waiters, and more. You can find what changed in v2 and the v3 equivalents for each change in the [migration guide on the AWS SDK for JavaScript GitHub repo](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md).
To take full advantage of the AWS SDK for JavaScript v3, we recommend using the codemod scripts described below.
### Use codemod to migrate existing v2 code
The collection of codemod scripts in [aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod) helps migrate your existing AWS SDK for JavaScript (v2) application to use v3 APIs. You can run the transform as follows.
```
$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...
```
For example, consider you have the following code, which creates a Amazon DynamoDB client from v2 and calls `listTables` operation.
```
// example.ts
import AWS from "aws-sdk";
const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
.then(console.log)
.catch(console.error);
```
You can run our `v2-to-v3` transform on `example.ts` as follows.
```
$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts
```
The transform will convert the DynamoDB import to v3, create v3 client and call the `listTables` operation as follows.
```
// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";
const region = "us-west-2";
const client = new DynamoDB({ region });
await client.listTables({})
.then(console.log)
.catch(console.error);
```
We’ve implemented transforms for common use cases. If your code doesn’t transform correctly, please create a [bug report](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yml&title=%5BBug%3F%5D%3A+) or [feature request](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=enhancement&template=feature_request.yml&title=%5BFeature%5D%3A+) with example input code and observed/expected output code. If your specific use case is already reported in [an existing issue](https://github.com/awslabs/aws-sdk-js-codemod/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) , show your support by an upvote.
## What's new in Version 3
Version 3 of the SDK for JavaScript (v3) contains the following new features.
Modularized packages
Users can now use a separate package for each service.
New middleware stack
Users can now use a middleware stack to control the lifecycle of an operation call.
In addition, the SDK is written in TypeScript, which has many advantages, such as static typing.
**Important**
The code examples for v3 in this guide are written in ECMAScript 6 (ES6). ES6 brings new syntax and new features to make your code more modern and readable, and do more. ES6 requires you use Node.js version 13.x or higher. To download and install the latest version of Node.js, see [Node.js downloads](https://nodejs.org/en/download/). For more information, see [JavaScript ES6/CommonJS syntax](sdk-example-javascript-syntax.md).
## Modularized packages
Version 2 of the SDK for JavaScript (v2) required you to use the entire AWS SDK, as follows.
```
var AWS = require("aws-sdk");
```
Loading the entire SDK isn’t an issue if your application is using many AWS services. However, if you need to use only a few AWS services, it means increasing the size of your application with code you don't need or use.
In v3, you can load and use only the individual AWS Services you need. This is shown in the following example, which gives you access to Amazon DynamoDB (DynamoDB).
```
import { DynamoDB } from "@aws-sdk/client-dynamodb";
```
Not only can you load and use individual AWS services, but you can also load and use only the service commands you need. This is shown in the following examples, which gives you access to DynamoDB client and the `ListTablesCommand` command.
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
```
**Important**
You should not import submodules into modules. For example, the following code might result in errors.
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";
```
The following is the correct code.
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";
```
### Comparing code size
In Version 2 (v2), a simple code example that lists all of your Amazon DynamoDB tables in the `us-west-2` Region might look like the following.
```
var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({ region: "us-west-2" });
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit: 10 }, function (err, data) {
if (err) {
console.log("Error", err.code);
} else {
console.log("Tables names are ", data.TableNames);
}
});
```
v3 looks like the following.
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({ region: "us-west-2" });
try {
const results = await dbclient.send(new ListTablesCommand);
for (const item of results.TableNames) {
console.log(item);
}
} catch (err) {
console.error(err)
}
```
The `aws-sdk` package adds about 40 MB to your application. Replacing `var AWS = require("aws-sdk")` with `import {DynamoDB} from "@aws-sdk/client-dynamodb"` reduces that overhead to about 3 MB. Restricting the import to just the DynamoDB client and `ListTablesCommand` command reduces the overhead to less than 100 KB.
```
// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});
```
### Calling commands in v3
You can perform operations in v3 using either v2 or v3 commands. To use v3 commands you import the commands and the required AWS Services package clients, and run the command using the `.send` method using the async/await pattern.
To use v2 commands you import the required AWS Services packages, and run the v2 command directly in the package using either a callback or async/await pattern.
#### Using v3 commands
v3 provides a set of commands for each AWS Service package to enable you to perform operations for that AWS Service. After you install an AWS Service, you can browse the available commands in your project's `node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.`
You must import the commands you want to use. For example, the following code loads the DynamoDB service, and the `CreateTableCommand` command.
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
```
To call these commands in the recommended async/await pattern, use the following syntax.
```
CLIENT.send(new XXXCommand);
```
For example, the following example creates a DynamoDB table using the recommended async/await pattern.
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
TableName: TABLE_NAME
};
try {
const data = await dynamodb.send(new CreateTableCommand(tableParams));
console.log("Success", data);
} catch (err) {
console.log("Error", err);
};
```
#### Using v2 commands
To use v2 commands in the SDK for JavaScript, you import the full AWS Service packages, as demonstrated in the following code.
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
```
To call v2 commands in the recommended async/await pattern, use the following syntax.
```
client.command(parameters);
```
The following example uses the v2 `createTable` command to create a DynamoDB table using the recommended async/await pattern.
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
const dynamoDB = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
TableName: TABLE_NAME
};
async function run() => {
try {
const data = await dynamoDB.createTable(tableParams);
console.log("Success", data);
}
catch (err) {
console.log("Error", err);
}
};
run();
```
The following example uses the v2 `createBucket` command to create an Amazon S3 bucket using the callback pattern.
```
const { S3 } = require('@aws-sdk/client-s3');
const s3 = new S3({ region: 'us-west-2' });
var bucketParams = {
Bucket : BUCKET_NAME
};
function run() {
s3.createBucket(bucketParams, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Location);
}
})
};
run();
```
## New middleware stack
v2 of the SDK enabled you to modify a request throughout the multiple stages of its lifecycle by attaching event listeners to the request. This approach can make it difficult to debug what went wrong during a request’s lifecycle.
In v3, you can use a new middleware stack to control the lifecycle of an operation call. This approach provides a couple of benefits. Each middleware stage in the stack calls the next middleware stage after making any changes to the request object. This also makes debugging issues in the stack much easier, because you can see exactly which middleware stages were called leading up to the error.
The following example adds a custom header to a Amazon DynamoDB client (which we created and showed earlier) using middleware. The first argument is a function that accepts `next`, which is the next middleware stage in the stack to call, and `context`, which is an object that contains some information about the operation being called. The function returns a function that accepts `args`, which is an object that contains the parameters passed to the operation and the request. It returns the result from calling the next middleware with `args`.
```
dbclient.middlewareStack.add(
(next, context) => args => {
args.request.headers["Custom-Header"] = "value";
return next(args);
},
{
name: "my-middleware",
override: true,
step: "build"
}
);
dbclient.send(new PutObjectCommand(params));
```
# What's different between the AWS SDK for JavaScript v2 and v3
This section captures notable changes from AWS SDK for JavaScript v2 to v3. Because v3 is a modular rewrite of v2, some basic concepts are different between v2 and v3. You can learn about these changes in our [blog posts](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/). The following blog posts will get you up to speed:
+ [Modular packages in AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/)
+ [Introducing Middleware Stack in Modular AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/)
The summary of interface changes from AWS SDK for JavaScript v2 to v3 is given below. The goal is to help you easily find the v3 equivalents of the v2 APIs you are already familiar with.
**Topics**
+ [
# Client constructors
](migrate-client-constructors.md)
+ [
# Credential providers
](migrate-credential-providers.md)
+ [
# Amazon S3 considerations
](migrate-s3.md)
+ [
# DynamoDB document client
](migrate-dynamodb-doc-client.md)
+ [
# Waiters and signers
](migrate-waiters-signers.md)
+ [
# Notes on specific service clients
](migrate-service-client-notes.md)
# Client constructors
This list is indexed by [v2 config parameters](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html).
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property)
+ **v2**: Whether to compute MD5 checksums for payload bodies when the service accepts it (currently supported in S3 only).
+ **v3**: applicable commands of S3 (PutObject, PutBucketCors, etc.) will automatically compute the MD5 checksums for of the request payload. You can also specify a different checksum algorithm in the commands' `ChecksumAlgorithm` parameter to use a different checksum algorithm. You can find more information in the [S3 feature announcement](https://aws.amazon.com/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/).
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property)
+ **v2**: Whether types are converted when parsing response data.
+ **v3**: **Deprecated**. This option is considered not type-safe because it doesn't convert the types like time stamp or base64 binaries from the JSON response.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property)
+ **v2**: Whether to apply a clock skew correction and retry requests that fail because of an skewed client clock.
+ **v3**: **Deprecated**. SDK *always* applies a clock skew correction.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property)
+ **v2**: An offset value in milliseconds to apply to all signing times.
+ **v3**: No change.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property)
+ **v2**: The AWS credentials to sign requests with.
+ **v3**: No change. It can also be an async function that returns credentials. If the function returns an `expiration (Date)`, the function will be called again when the expiration datetime nears. See [v3 API reference for `AwsAuthInputConfig` credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-signing/Interface/AwsAuthInputConfig/).
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property)
+ **v2**: The size of the global cache storing endpoints from endpoint discovery operations.
+ **v3**: No change.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property)
+ **v2**: Whether to call operations with endpoints given by service dynamically.
+ **v3**: No change.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property)
+ **v2**: Whether to marshal request parameters to the prefix of hostname.
+ **v3**: **Deprecated**. SDK *always* injects the hostname prefix when necessary.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property)
A set of options to pass to the low-level HTTP request. These options are aggregated differently in v3. You can configure them by supplying a new `requestHandler`. Here's the example of setting http options in Node.js runtime. You can find more in [v3 API reference for NodeHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/).
All v3 requests use HTTPS by default. You only need to provide custom httpsAgent.
```
const { Agent } = require("https");
const { Agent: HttpAgent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpsAgent: new Agent({
/*params*/
}),
connectionTimeout: /*number in milliseconds*/,
socketTimeout: /*number in milliseconds*/
}),
});
```
If you are passing custom endpoint which uses http, then you need to provide httpAgent.
```
const { Agent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpAgent: new Agent({
/*params*/
}),
}),
endpoint: "http://example.com",
});
```
If the client is running in browsers, a different set of options is available. You can find more in [v3 API reference for FetchHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-fetch-http-handler/).
```
const { FetchHttpHandler } = require("@smithy/fetch-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new FetchHttpHandler({
requestTimeout: /* number in milliseconds */
}),
});
```
Each option of `httpOptions` is specified below:
+ `proxy`
+ **v2**: The URL to proxy requests through.
+ **v3**: You can set up a proxy with an agent following [Configuring proxies for Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html).
+ `agent`
+ **v2**: The Agent object to perform HTTP requests with. Used for connection pooling.
+ **v3**: You can configure `httpAgent` or `httpsAgent` as shown in the examples above.
+ `connectTimeout`
+ **v2**: Sets the socket to timeout after failing to establish a connection with the server after `connectTimeout` milliseconds.
+ **v3**: `connectionTimeout` is available [in `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/).
+ `timeout`
+ **v2**: The number of milliseconds a request can take before automatically being terminated.
+ **v3**: `socketTimeout` is available [in `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/).
+ `xhrAsync`
+ **v2**: Whether the SDK will send asynchronous HTTP requests.
+ **v3**: **Deprecated**. Requests are *always* asynchronous.
+ `xhrWithCredentials`
+ **v2**: Sets the "withCredentials" property of an XMLHttpRequest object.
+ **v3**: Not available. SDK inherits [the default fetch configurations](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property)
+ **v2**: An object that responds to `.write()` (like a stream) or `.log()` (like the console object) in order to log information about requests.
+ **v3**: No change. More granular logs are available in v3.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property)
+ **v2**: The maximum amount of redirects to follow for a service request.
+ **v3**: **Deprecated**. SDK *does not* follow redirects to avoid unintentional cross-region requests.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property)
+ **v2**: The maximum amount of retries to perform for a service request.
+ **v3**: Changed to `maxAttempts`. See more in [v3 API reference for RetryInputConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-middleware-retry/Interface/RetryInputConfig/). Note that `maxAttempts` should be `maxRetries + 1`.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property)
+ **v2**: Whether input parameters should be validated against the operation description before sending the request.
+ **v3**: **Deprecated**. SDK *does not* do validation on client-side at runtime.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property)
+ **v2**: The region to send service requests to.
+ **v3**: No change. It can also be an async function that returns a region string.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property)
+ **v2**: A set of options to configure the retry delay on retryable errors.
+ **v3**: **Deprecated**. SDK supports more flexible retry strategy with `retryStrategy` client constructor option. See more [in v3 API reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-util-retry/).
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property)
+ **v2**: Whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint).
+ **v3**: Changed to `bucketEndpoint`. See more in [v3 API reference for bucketEndpoint](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-bucket-endpoint/Interface/BucketEndpointInputConfig/). Note that when set to `true`, you specify the request endpoint in the `Bucket` request parameter, the original endpoint will be overwritten. Whereas in v2, the request endpoint in client constructor overwrites the `Bucket` request parameter.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property)
+ **v2**: Whether to disable S3 body signing when using signature version v4.
+ **v3**: Renamed to `applyChecksum`.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property)
+ **v2**: Whether to force path style URLs for S3 objects.
+ **v3**: Renamed to `forcePathStyle`.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property)
+ **v2**: Whether to override the request region with the region inferred from requested resource's ARN.
+ **v3**: Renamed to `useArnRegion`.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property)
+ **v2**: When region is set to 'us-east-1', whether to send s3 request to global endpoints or 'us-east-1' regional endpoints.
+ **v3**: **Deprecated**. S3 client will always use regional endpoint if region is set to `us-east-1`. You can set the region to `aws-global` to send requests to S3 global endpoint.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property)
+ **v2**: Whether the signature to sign requests with (overriding the API configuration) is cached.
+ **v3**: **Deprecated**. SDK *always* caches the hashed signing keys.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property)
+ **v2**: The signature version to sign requests with (overriding the API configuration).
+ **v3**: **Deprecated**. Signature V2 supported in v2 SDK has been deprecated by AWS. v3 *only* supports signature v4.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property)
+ **v2**: Whether SSL is enabled for requests.
+ **v3**: Renamed to `tls`.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property)
+ **v2**: Whether to send sts request to global endpoints or regional endpoints.
+ **v3**: **Deprecated**. STS client will *always* use regional endpoints if set to a specific region. You can set the region to `aws-global` to send request to STS global endpoint.
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property)
+ **v2**: Whether to use the Accelerate endpoint with the S3 service.
+ **v3**: No change.
# Credential providers
In v2, the SDK for JavaScript provides a list of credential providers to choose from, as well as a credentials provider chain, available by default on Node.js, that tries to load the AWS credentials from all the most common providers. The SDK for JavaScript v3 simplifies the credential provider's interface, making it easier to use and write custom credential providers. On top of a new credentials provider chain, the SDK for JavaScript v3 all provides a list of credential providers aiming to provide equivalent to v2.
Here are all the credential providers in v2 and their equivalents in v3.
## Default Credential Provider
The default credential provider is how the SDK for JavaScript resolve the AWS credential if you *do not* provide one explicitly.
+ **v2**: [CredentialProviderChain](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) in Node.js resolves credential from sources as following order:
+ [Environmental variable](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html)
+ [Shared credentials file](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
+ [ECS container credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ [Spawning external process](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html)
+ [OIDC token from specified file](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ [Amazon EC2 instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
If one of the credential providers above fails to resolve the AWS credential, the chain falls back to next provider until a valid credential is resolved, and the chain will throw an error when all of the providers fail.
In Browser and React Native runtimes, the credential chain is empty, and credentials must be set explicitly.
+ **v3**: [defaultProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1). The credential sources and fallback order *does not* change in v3. It also supports [AWS IAM Identity Center credentials](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html).
## Temporary Credentials
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html) represents temporary credentials retrieved from `AWS.STS`. Without any extra parameters, credentials will be fetched from the `AWS.STS.getSessionToken()` operation. If an IAM role is provided, the `AWS.STS.assumeRole()` operation will be used to fetch credentials for the role instead. `AWS.ChainableTemporaryCredentials` differs from `AWS.TemporaryCredentials` in the way masterCredentials and refreshes are handled. `AWS.ChainableTemporaryCredentials` refreshes expired credentials using the masterCredentials passed by the user to support chaining of STS credentials. However, `AWS.TemporaryCredentials` recursively collapses the masterCredentials during instantiation, precluding the ability to refresh credentials which require intermediate, temporary credentials.
The original [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) has been **deprecated** in favor of `ChainableTemporaryCredentials` in v2.
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials). You can call `fromTemporaryCredentials()` from the `@aws-sdk/credential-providers` package. Here's an example:
```
import { FooClient } from "@aws-sdk/client-foo";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
// const { FooClient } = require("@aws-sdk/client-foo");
// const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import
const sourceCredentials = {
// A credential can be a credential object or an async function that returns a credential object
};
const client = new FooClient({
credentials: fromTemporaryCredentials({
masterCredentials: sourceCredentials,
params: { RoleArn },
}),
});
```
## Amazon Cognito Identity Credentials
Load credentials from the Amazon Cognito Identity service, normally used in browsers.
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) Represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service.
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) The [`@aws/credential-providers` package](https://www.npmjs.com/package/@aws-sdk/credential-providers) provides two credential provider functions, one of which [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) takes an identity ID and calls `cognitoIdentity:GetCredentialsForIdentity`, while the other [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) takes an identity pool ID, calls `cognitoIdentity:GetId` on the first invocation, and then calls`fromCognitoIdentity`. Subsequent invocations of the latter do not re-invoke GetId.
The provider implements the "Simplified Flow" described in the [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html). The "Classic Flow" which involves calling `cognito:GetOpenIdToken` and then calling `sts:AssumeRoleWithWebIdentity` is *not* supported. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) to us if you need it.
```
// fromCognitoIdentityPool example
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentityPool({
clientConfig: cognitoIdentityClientConfig, // Optional
identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
```
// fromCognitoIdentity example
import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentity } = require("@aws-sdk/credential-provider-cognito-identity"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentity({
clientConfig: cognitoIdentityClientConfig, // Optional
identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
## Amazon EC2 Metadata (IMDS) Credential
Represents credentials received from the metadata service on an Amazon EC2 instance.
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata). Creates a credential provider that will source credentials from the Amazon EC2 Instance Metadata Service.
```
import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromInstanceMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## Amazon ECS Credentials
Represents credentials received from specified URL. This provider will request temporary credentials from URI specified by the `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or the `AWS_CONTAINER_CREDENTIALS_FULL_URI` environment variable.
+ **v2**: `ECSCredentials` or [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata). Creates a credential provider that will source credentials from the Amazon ECS Container Metadata Service.
```
import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromContainerMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## File System Credentials
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html). Represents credentials from a JSON file on disk.
+ **v3**: **Deprecated**. You can explicitly read the JSON file and supply to the client. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) to us if you need it.
## SAML Credential Provider
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html) Represents credentials retrieved from STS SAML support.
+ **v3**: **Not available**. Please open a [feature request](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=) to us if you need it.
## Shared Credential File Credentials
Loads credentials from shared credentials file (defaulting to `~/.aws/credentials` or defined by the `AWS_SHARED_CREDENTIALS_FILE` environment variable). This file is supported across different AWS SDKs and tools. You can refer to the [shared config and credentials files document](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) for more information.
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
```
import { fromIni } from "@aws-sdk/credential-providers";
// const { fromIni } from("@aws-sdk/credential-providers");
const client = new FooClient({
credentials: fromIni({
configFilepath: "~/.aws/config", // Optional
filepath: "~/.aws/credentials", // Optional
mfaCodeProvider: async (mfaSerial) => {
// implement a pop-up asking for MFA code
return "some_code";
}, // Optional
profile: "default", // Optional
clientConfig: { region }, // Optional
}),
});
```
## Web Identity Credentials
Retrieves credentials using OIDC token from a file on disk. Commonly used in Amazon EKS.
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile)
```
import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromTokenFile } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromTokenFile({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
## Web Identity Federation Credentials
Retrieves credentials from STS web identity federation support.
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken)
```
import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromWebToken } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromWebToken({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
# Amazon S3 considerations
## Amazon S3 multipart upload
In v2, the Amazon S3 client contains an [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property) operation that supports uploading large objects with [multipart upload feature offered by Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html).
In v3, the [https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage) package is available. It supports all the features offered in the v2 `upload()` operation and supports both Node.js and browsers runtime.
## Amazon S3 presigned URL
In v2, the Amazon S3 client contains the [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property) and [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property) operations to generate an URL that users can use to upload or download objects from Amazon S3.
In v3, the [https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner) package is available. This package contains the functions for both `getSignedUrl()` and ` getSignedUrlPromise()` operations. This [ blog post](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/) discusses the details of this package.
## Amazon S3 region redirects
If an incorrect region is passed to the Amazon S3 client and a subsequent ` PermanentRedirect` (status 301) error is thrown, the Amazon S3 client in v3 supports region redirects (previously known as the Amazon S3 Global Client in v2). You can use the [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/) flag in the client configuration to make the Amazon S3 client follow region redirects and support its function as a global client.
**Note**
Note that this feature can result in additional latency as failed requests are retried with a corrected region when receiving a `PermanentRedirect` error with status 301. This feature should only be used if you do not know the region of your bucket(s) ahead of time.
## Amazon S3 streaming and buffered responses
The v3 SDK prefers not to buffer potentially large responses. This is commonly encountered in the Amazon S3 `GetObject` operation, which returned a `Buffer` in v2, but returns a `Stream` in v3.
For Node.js, you must consume the stream or garbage collect the client or its request handler to keep the connections open to new traffic by freeing sockets.
```
// v2
const get = await s3.getObject({ ... }).promise(); // this buffers consumes the stream already.
```
```
// v3, consume the stream to free the socket
const get = await s3.getObject({ ... }); // object .Body has unconsumed stream
const str = await get.Body.transformToString(); // consumes the stream
// other ways to consume the stream include writing it to a file,
// passing it to another consumer like an upload, or buffering to
// a string or byte array.
```
For more information, see section on [ socket exhaustion](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler).
# DynamoDB document client
## Basic usage of DynamoDB document client in v3
+ In v2, you can use the [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html) class to call DynamoDB APIs with native JavaScript types like Array, Number, and Object. It thus simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values.
+ In v3, the equivalent [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html) client is available. It's similar to normal service clients from v3 SDK, with the difference that it takes a basic DynamoDB client in its constructor.
Example:
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); // CommonJS import
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocumentClient, PutCommand } = require("@aws-sdk/lib-dynamodb"); // CommonJS import
// Bare-bones DynamoDB Client
const client = new DynamoDBClient({});
// Bare-bones document client
const ddbDocClient = DynamoDBDocumentClient.from(client); // client is DynamoDB client
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "1",
content: "content from DynamoDBDocumentClient",
},
})
);
```
## `Undefined` values in when marshalling
+ In v2, `undefined` values in objects were automatically omitted during the marshalling process to DynamoDB.
+ In v3, the default marshalling behavior in `@aws-sdk/lib-dynamodb` has changed: objects with `undefined` values are no longer omitted. To align with v2's functionality, developers must explicitly set the `removeUndefinedValues` to `true` in the `marshallOptions` of the DynamoDB Document Client.
Example:
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
// The DynamoDBDocumentClient is configured to handle undefined values properly
const ddbDocClient = DynamoDBDocumentClient.from(client, {
marshallOptions: {
removeUndefinedValues: true
}
});
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "123",
content: undefined // This value will be automatically omitted.
array: [1, undefined], // The undefined value will be automatically omitted.
map: { key: undefined }, // The "key" will be automatically omitted.
set: new Set([1, undefined]), // The undefined value will be automatically omitted.
};
})
);
```
More examples and configurations are available in the [package README](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md).
# Waiters and signers
This page describes the usage of waiters and signers in the AWS SDK for JavaScript v3.
## Waiters
In v2, all waiters are bound to the service client class, and you need to specify in waiter's input which designed state the client will be waiting for. For example, you need to call [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter) to wait for a newly created bucket to be ready.
In v3, you don't need to import waiters if your application doesn't need one. Moreover, you can import only the waiter you need to wait for the particular desired state you want. Thus, you can reduce your bundle size and improve performance. Here is an example of waiting for bucket to be ready after creation:
```
import { S3Client, CreateBucketCommand, waitUntilBucketExists } from "@aws-sdk/client-s3"; // ES6 import
// const { S3Client, CreateBucketCommand, waitUntilBucketExists } = require("@aws-sdk/client-s3"); // CommonJS import
const Bucket = "BUCKET_NAME";
const client = new S3Client({ region: "REGION" });
const command = new CreateBucketCommand({ Bucket });
await client.send(command);
await waitUntilBucketExists({ client, maxWaitTime: 60 }, { Bucket });
```
You can find everything of how to configure the waiters in the [blog post of waiters in the AWS SDK for JavaScript v3](https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/).
## Amazon CloudFront Signer
In v2, you can sign the request to access restricted Amazon CloudFront distributions with [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html).
In v3, you have the same utilities provided in the [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html) package.
## Amazon RDS Signer
In v2, you can generate the auth token to an Amazon RDS database using [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html).
In v3, the similar utility class is available in [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html) package.
## Amazon Polly Signer
In v2, you can generate a signed URL to the speech synthesized by Amazon Polly service with [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html).
In v3, the similar utility function is available in [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html) package.
# Notes on specific service clients
## AWS Lambda
Lambda invocations response type differs in v2 and v3.
```
// v2
import { Lambda } from "@aws-sdk/client-lambda";
import AWS from "aws-sdk";
const lambda = new AWS.Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
}).promise();
// in v2, Lambda::invoke::Payload is automatically converted to string via a
// specific code customization.
const payloadIsString = typeof invoke.Payload === "string";
console.log("Invoke response payload type is string:", payloadIsString);
const payloadObject = JSON.parse(invoke.Payload);
console.log("Invoke response object", payloadObject);
```
```
// v3
const lambda = new Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
});
// in v3, Lambda::invoke::Payload is not automatically converted to a string.
// This is to reduce the number of customizations that create inconsistent behaviors.
const payloadIsByteArray = invoke.Payload instanceof Uint8Array;
console.log("Invoke response payload type is Uint8Array:", payloadIsByteArray);
// To maintain the old functionality, only one additional method call is needed:
// v3 adds a method to the Uint8Array called transformToString.
const payloadObject = JSON.parse(invoke.Payload.transformToString());
console.log("Invoke response object", payloadObject);
```
## Amazon SQS
### MD5 Checksum
To skip computation of MD5 checksums of message bodies, set `md5` to *false* on the configuration object. Otherwise, the SDK by default will calculate the checksum for sending messages, as well as validating the checksum for retrieved messages.
```
// Example: Skip MD5 checksum in Amazon SQS
import { SQS } from "@aws-sdk/client-sqs";
new SQS({
md5: false // note: only available in v3.547.0 and higher
});
```
When using a custom `QueueUrl` in Amazon SQS operations that have this as an input parameter, in v2 it was possible to supply a custom `QueueUrl` which would override the Amazon SQS Client's default endpoint.
### Multi-region messages
You should use one client per region in v3. The AWS region is meant to be initialized at the client level and not changed between requests.
```
import { SQS } from "@aws-sdk/client-sqs";
const sqsClients = {
"us-east-1": new SQS({ region: "us-east-1" }),
"us-west-2": new SQS({ region: "us-west-2" }),
};
const queues = [
{ region: "us-east-1", url: "https://sqs.us-east-1.amazonaws.com/{AWS_ACCOUNT}/MyQueue" },
{ region: "us-west-2", url: "https://sqs.us-west-2.amazonaws.com/{AWS_ACCOUNT}/MyOtherQueue" },
];
for (const { region, url } of queues) {
const params = {
MessageBody: "Hello",
QueueUrl: url,
};
await sqsClients[region].sendMessage(params);
}
```
### Custom endpoint
In v3, when using a custom endpoint, i.e. one that differs from the default public Amazon SQS endpoints, you should always set the endpoint on the Amazon SQS Client as well as the ` QueueUrl` field.
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
// client endpoint should be specified in v3 when not the default public SQS endpoint for your region.
// This is required for versions <= v3.506.0
// This is optional but recommended for versions >= v3.507.0 (a warning will be emitted)
endpoint: "https://my-custom-endpoint:8000/",
});
await sqs.sendMessage({
QueueUrl: "https://my-custom-endpoint:8000/1234567/MyQueue",
Message: "hello",
});
```
If you are not using a custom endpoint, then you do not need to set `endpoint` on the client.
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
region: "us-west-2",
});
await sqs.sendMessage({
QueueUrl: "https://sqs.us-west-2.amazonaws.com/1234567/MyQueue",
Message: "hello",
});
```
# Supplemental documentation
The following table includes links to supplemental documentation that will help you use and understand the AWS SDK for JavaScript (v3).
****
| Name | Notes |
| --- | --- |
| [SDK Clients](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md) | Information about initializing an SDK client and common configurable constructor parameters. |
| [Upgrading Notes (2.x to 3.x)](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md) | Information regarding upgrading from AWS SDK for JavaScript (v2). |
| [Using the AWS SDK for JavaScript (v3) on AWS Lambda Node.js runtimes](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/AWS_LAMBDA.md) | Best practices for working within AWS Lambda using the AWS SDK for JavaScript (v3). |
| [Performance](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/performance/README.md) | Information on how the AWS SDK team has optimized performance of the SDK and includes tips for configuring the SDK to run efficiently. |
| [TypeScript](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/TYPESCRIPT.md) | TypeScript tips and FAQs related to the AWS SDK for JavaScript (v3). |
| [Error Handling](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/ERROR_HANDLING.md) | Tips for dealing with errors related to the AWS SDK for JavaScript (v3). |
| [Effective Practices](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/EFFECTIVE_PRACTICES.md) | General recommendations for using the AWS SDK for JavaScript (v3). |