aws-sdk-js-v3-usage

Files (12)

• SKILL.md
• clients.md · references/
• credentials.md · references/
• dynamodb.md · references/
• effective-practices.md · references/
• error-handling.md · references/
• lambda.md · references/
• performance.md · references/
• s3.md · references/
• schemas.md · references/
• sigv4a.md · references/
• typescript.md · references/

SKILL.md (first lines)

> Do not use emojis in any code, comments, or output when this skill is active.

# AWS SDK for JavaScript v3

## Package Structure

- `@aws-sdk/client-*` — one per service, generated by [smithy-typescript](https://github.com/awslabs/smithy-typescript); one-to-one with AWS services and operations
- `@aws-sdk/lib-*` — higher-level helpers (e.g. `lib-dynamodb`, `lib-storage`)
- `@aws-sdk/*` (no prefix) — utility packages (mostly internal; don't import deep paths)

Always import from the package root:

```js
import { S3Client } from "@aws-sdk/client-s3"; // correct
// NOT: import { S3Client } from "@aws-sdk/client-s3/dist-cjs/S3Client"
```

## Two Client Styles

**Bare-bones** (preferred — smaller bundle):

```js
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
const output = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
```

**Aggregated** (v2-style but NOT v2, larger bundle):

```js
import { S3 } from "@aws-sdk/client-s3";
const client = new S3({ region: "us-east-1" });
const output = await client.getObject({ Bucket: "b", Key: "k" });
```

## Client Configuration

No global config in v3 — pass config to each client. `region` is always required; set it explicitly or via `AWS_REGION` env var.

```js
const config = { region: "us-east-1", maxAttempts: 5 };
const s3 = new S3Client(config);
const dynamo = new DynamoDBClient(config);
```

**Do not read or mutate `client.config` after instantiation** — it is a resolved form (e.g. `region` becomes an async function). See `references/effective-practices.md`.

For HTTP handler (`NodeHttpHandler` from `@smithy/node-http-handler`), retry strategy, endpoint details, logging, FIPS, dual-stack, protocol selection, and S3-specific options → see `references/clients.md`.

## Credentials

All providers from `@aws-sdk/credential-providers`. Credentials are lazy and cached per client until ~5 min before expiry.

```js
// Default chain (env → ini → IMDS/ECS) — use in most Node.js apps
const client = new S3Client({ credentials: fromNodeProviderChain() });

// Assume role (NOTE: fromTemporaryCredentials is correct for STS AssumeRole)
const client = new S3Client({
  credentials: fromTemporaryCredentials({ params: { RoleArn: "arn:aws:iam::123456789012:role/MyRole" } }),
});

// Named profile
const client = new S3Client({ profile: "my-profile" });
```

Share credentials and socket pool across multi-region clients:

```js
const east = new S3Client({ region: "us-east-1" });
const { credentials, requestHandler } = east.config;
const west = new S3Client({ region: "us-west-2", credentials, requestHandler });
```

For all providers (Cognito, SSO, web identity, custom chains, STS region priority) → see `references/credentials.md`.

## Streams (e.g. S3 GetObject Body)

**Always read or discard streaming responses** — unread streams leave sockets open (socket exhaustion):

```js
const { Body } = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
const str = await Body.transformToString();       // read as string
const bytes = await Body.transformToByteArray();  // read as Uint8Array
// or discard:
await (Body.destroy?.() ?? Body.cancel?.());
```

Streams can only be read once.

## Paginators

Use `paginate*` functions instead of manual token handling:

```js
import { DynamoDBClient, paginateListTables } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
  // page contains a single paginated output.
  tableNames.push(...page.TableNames);
}
```

## DynamoDB DocumentClient

Use `@aws-sdk/lib-dynamodb` to work with native JS types instead of AttributeValues:

```js
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
await client.send(new PutCommand({ TableName: "T", Item: { id: "1", name: "Alice" } }));
const { Item } = await client.send(new GetCommand({ TableName: "T", Key: { id: "1" } }));
```

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws