---
name: infra-platform-aws-sdk
description: AWS SDK v3 for TypeScript — modular clients, command pattern, S3, DynamoDB, SQS, Lambda, SNS, Secrets Manager
---
# AWS SDK v3 Patterns
> **Quick Guide:** AWS SDK v3 for JavaScript/TypeScript uses modular packages (`@aws-sdk/client-*`) with a command pattern: create a client, instantiate a command, call `client.send(command)`. Import only the services you need for tree-shaking. Use `DynamoDBDocumentClient` for native JS types. Use `getSignedUrl` from `@aws-sdk/s3-request-presigner` for presigned URLs. Handle errors with `instanceof` specific exception classes. Use built-in paginators (`paginate*`) with `for await...of`.
---
## CRITICAL: Before Using This Skill
> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)
**(You MUST use AWS SDK v3 modular packages (`@aws-sdk/client-*`) — NEVER the monolithic `aws-sdk` v2 package)**
**(You MUST use the command pattern: `client.send(new XxxCommand({...}))` — NEVER call methods directly on the client)**
**(You MUST use `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb` for DynamoDB — it auto-marshalls native JS types)**
**(You MUST handle errors with `instanceof` specific exception classes — NEVER catch generic `Error` and check `.code`)**
**(You MUST use built-in paginators (`paginate*` functions) for paginated APIs — NEVER manually track continuation tokens)**
---
## Examples
- [Core Patterns](examples/core.md) — Client setup, S3 operations, DynamoDB basics, credential providers, error handling, pagination
- [Messaging](examples/messaging.md) — SQS send/receive/delete, SNS publish, FIFO queues, dead-letter patterns
- [Advanced](examples/advanced.md) — Lambda invocation, Secrets Manager, presigned URLs, middleware, streaming
- [Quick Reference](reference.md) — Package cheat sheet, import patterns, error handling decision tree, credential provider chain
---
**Auto-detection:** AWS SDK, @aws-sdk/client, S3Client, DynamoDBClient, DynamoDBDocumentClient, SQSClient, LambdaClient, SNSClient, SecretsManagerClient, PutObjectCommand, GetObjectCommand, GetCommand, PutCommand, QueryCommand, SendMessageCommand, InvokeCommand, GetSecretValueCommand, getSignedUrl, s3-request-presigner, credential-providers, fromEnv, fromIni, paginateListObjectsV2, aws-sdk-client-mock
**When to use:**
- Interacting with any AWS service from TypeScript/JavaScript
- S3 file operations (upload, download, presigned URLs, listings)
- DynamoDB CRUD operations and queries
- SQS message sending, receiving, and queue management
- Lambda function invocation from other services
- SNS topic publishing and notifications
- Secrets Manager secret retrieval
- Custom middleware for request/response modification
**When NOT to use:**
- Infrastructure provisioning (use an IaC tool)
- AWS console-only operations with no SDK equivalent
- Simple CLI-only tasks better served by the AWS CLI directly
**Key patterns covered:**
- Modular client setup with typed configuration
- Command pattern (`client.send(new Command({...}))`)
- S3: upload, download, delete, list, presigned URLs, streaming
- DynamoDB: `DynamoDBDocumentClient` with `Get`, `Put`, `Query`, `Update`, `Delete`
- SQS: send, receive, delete messages, long polling, FIFO
- SNS: publish to topics, message attributes
- Lambda: synchronous and asynchronous invocation
- Secrets Manager: secret retrieval with caching
- Credential provider chain and explicit providers
- Error handling with `instanceof` exception classes and `$metadata`
- Pagination with async iterators
- Middleware stack customization
- Retry configuration
---
## Philosophy
AWS SDK v3 is a ground-up rewrite of the v2 SDK for modern JavaScript/TypeScript. The core design principles:
1. **Modular packages** — Each service is a separate npm package (`@aws-sdk/client-s3`, `@aws-sdk/client-dynamodb`). Import only what you use. This reduces bundle size by up to 90% compared to the monolithic v2 `aws-sdk` package.
2. **Command pattern** — Every API call is a Command object sent through a Client. This enables middleware, type safety, and testability. The client handles serialization, signing, retries, and deserialization.
3. **First-class TypeScript** — Every command input and output is fully typed. Use the types to avoid runtime errors.
4. **Middleware stack** — Customize request/response handling at various stages (serialize, build, finalize, deserialize) without monkey-patching.
5. **Built-in pagination** — Paginator functions return async iterators, eliminating manual token tracking.
**When to use AWS SDK v3:**
- Any server-side or serverless TypeScript/JavaScript that interacts with AWS services
- Frontend applications that need direct AWS access (with appropriate auth)
- Lambda functions (SDK v3 is included in Node.js 18+ Lambda runtimes)
**When NOT to use:**
- Infrastructure provisioning and management (use an IaC tool)
- One-off tasks better served by the AWS CLI
- Languages other than JavaScript/TypeScript
---
## Core Patterns
### Pattern 1: Client Setup and Command Pattern
Every AWS service follows the same pattern: import the client and command, create a client instance, send the command.
```typescript
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-east-1" });
await s3.send(
new PutObjectCommand({
Bucket: "my-bucket",
Key: "data.json",
Body: JSON.stringify({ hello: "world" }),
ContentType: "application/json",
}),
);
```
**Why good:** modular import keeps bundle small, command pattern enables middleware and type safety, region is explicit
Create clients once and reuse them — they manage connection pooling internally. In Lambda, create clients outside the handler for connection reuse across invocations.
See [examples/core.md](examples/core.md) for client reuse patterns and configuration options.
---
### Pattern 2: S3 Operations
S3 is the most commonly used service. Key operations: `PutObject`, `GetObject`, `DeleteObject`, `ListObjectsV2`, and presigned URLs via `@aws-sdk/s3-request-presigner`.
```typescript
import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
const response = await s3.send(
new GetObjectCommand({
Bucket: "my-bucket",
Key: "data.json",
}),
);
const body = await response.Body?.transformToString();
```
For presigned URLs, use the separate `@aws-sdk/s3-request-presigner` package:
```typescript
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const PRESIGN_EXPIRY_SECONDS = 3_600;
const url = await getSignedUrl(
s3,
new GetObjectCommand({
Bucket: "my-bucket",
Key: "file.pdf",
}),
{ expiresIn: PRESIGN_EXPIRY_SECONDS },
);
```
See [examples/core.md](examples/core.md) for upload, download, delete, list, and streaming patterns.
---
### Pattern 3: DynamoDB with Document Client
Use `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb` — it automatically marshalls/unmarshalls between native JS types and DynamoDB's `AttributeValue` format.
```typescript
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
GetCommand,
PutCommand,
} from "@aws-sdk/lib-dynamodb";
const ddbDocClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const { Item } = await ddbDocClient.send(
new GetCommand({
TableName: "users",
Key: { userId: "abc-123" },
}),
);
```
**Why good:** no manual `marshall()`/`unmarshall()` calls, native JS objects in and out, full type safety
**Gotcha:** Import commands from `@aws-sdk/lib-dynamodb` (not `@aws-sdk/client-dynamodb`) when using the document client — the lib-dynamodb commands accept native JS types.
See [examples/core.md](examples/core.md) for Put, Query, Update, Delete, and batch operations.
---
### Pattern 4: Error Handling
AWS SDK v3 errors extend service-specific base classes (e.g., `S3ServiceException`). Use `instanceof` for typed error handling.
```typescript
import {
GetObjectCommand,
NoSuchKey,
S3ServiceException,
} from "@aws-sdk/client-s3";
try {
await s3.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
} catch (error) {
if (error instanceof NoSuchKey) {
// Typed: error.name === "NoSuchKey", error.$metadata.httpStatusCode === 404
return null;
}
if (error instanceof S3ServiceException) {
// Any S3 service error — check error.$metadata.httpStatusCode
throw error;
}
throw error; // Non-AWS error (network, etc.)
}
```
**Why good:** `instanceof` gives TypeScript type narrowing, exception classes are exported from the client package, `$metadata` provides HTTP status and request ID for debugging
See [examples/core.md](examples/core.md) for the full error handling decision tree and retry patterns.
---
### Pattern 5: Pagination with Async Iterators
Use built-in paginator functions for any paginated API. They return async iterators that handle continuation tokens automatically.
```typescript
import { paginateListObjectsV2 } from "@aws-sdk/client-s3";
for await (const page of paginateListObjectsV2(
{ client: s3 },
{ Bucket: "my-bucket" },
)) {
// page.Contents is an array of objects for this page
}
```
**Why good:** no manual token tracking, clean `for await...of` loop, handles all edge cases (empty pages, token format)
See [examples/core.md](examples/core.md) for full S3 list, DynamoDB pagination, and good/bad comparison with manual token tracking.
---
### Pattern 6: SQS Messaging
SQS uses `SendMessageCommand`, `ReceiveMessageCommand`, and `DeleteMessageCommand`. Always delete messages after processing.
```typescript
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
const sqs = new SQSClient({});
await sqs.send(
new SendMessageCommand({
QueueUrl: QUEUE_URL,
MessageBody: JSON.stringify({ orderId: "order-123" }),
}),
);
```
See [examples/messaging.md](examples/messaging.md) for receive/delete, long polling, FIFO queues, and dead-letter patterns.
---
### Pattern 7: SNS Publishing
SNS publishes messages to topics. Subscribers receive messages on their configured endpoints.
```typescript
import { SNSClient, PublishCommand } from "@aws-sdk/client-sns";
const sns = new SNSClient({});
await sns.send(
new PublishCommand({
TopicArn: TOPIC_ARN,
Message: JSON.stringify({ event: "order.created", orderId: "order-123" }),
MessageAttributes: {
eventType: { DataType: "String", StringValue: "order.created" },
},
}),
);
```
See [examples/messaging.md](examples/messaging.md) for topic management and message filtering.
---
### Pattern 8: Lambda Invocation and Secrets Manager
Invoke Lambda functions synchronously or asynchronously. Retrieve secrets from Secrets Manager with caching.
```typescript
import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
const lambda = new LambdaClient({});
const response = await lambda.send(
new InvokeCommand({
FunctionName: "process-order",
InvocationType: "RequestResponse", // synchronous
Payload: JSON.stringify({ orderId: "order-123" }),
}),
);
const result = JSON.parse(new TextDecoder().decode(response.Payload));
```
See [examples/advanced.md](examples/advanced.md) for async invocation, Secrets Manager retrieval, and caching patterns.
---
## Decision Framework
### Choosing the Right DynamoDB Client
```
Are you working with DynamoDB?
|
+-- Need native JS objects (recommended) --> DynamoDBDocumentClient from @aws-sdk/lib-dynamodb
| +-- Import Get/Put/Query/Update/Delete Commands from @aws-sdk/lib-dynamodb
|
+-- Need raw AttributeValue format --> DynamoDBClient from @aws-sdk/client-dynamodb
+-- Import commands from @aws-sdk/client-dynamodb
+-- Manually marshall/unmarshall with @aws-sdk/util-dynamodb
```
### Choosing Between Synchronous and Async Lambda Invocation
```
Do you need the Lambda response immediately?
|
+-- YES --> InvocationType: "RequestResponse" (synchronous, waits for result)
|
+-- NO --> InvocationType: "Event" (async, returns immediately, 3 retries)
```
### Credential Provider Selection
```
Where is this code running?
|
+-- Lambda / ECS / EC2 --> Default chain (auto-detects IAM role) — no config needed
|
+-- Local development --> fromIni() (reads ~/.aws/credentials) or fromEnv()
|
+-- CI/CD pipeline --> fromEnv() with AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
|
+-- Cross-account access --> fromTemporaryCredentials() with STS AssumeRole
```
---
## RED FLAGS
**High Priority Issues:**
- Using the monolithic `aws-sdk` v2 package — it ships the entire SDK (~70 MB). Use modular `@aws-sdk/client-*` packages.
- Calling methods directly on the client (v2 style: `s3.getObject()`) — use the command pattern: `s3.send(new GetObjectCommand({...}))`.
- Using raw `DynamoDBClient` commands with manual `marshall()`/`unmarshall()` — use `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb`.
- Catching errors with `.code` string comparison (v2 style) — use `instanceof` with typed exception classes.
- Manually tracking pagination tokens in a while loop — use built-in `paginate*` functions with `for await...of`.
- Hardcoding AWS credentials in source code — use the credential provider chain or environment variables.
**Medium Priority Issues:**
- Creating a new client instance per request — create clients once and reuse them (they manage connection pooling).
- Not setting a region explicitly — defaults vary by environment and cause confusing errors.
- Mixing `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` command imports — pick one approach per codebase.
- Missing `ContentType` on S3 `PutObject` — S3 defaults to `application/octet-stream`, breaking browser downloads.
- Not buffering the S3 `GetObject` response body — `response.Body` is a stream; call `.transformToString()` or `.transformToByteArray()`.
**Gotchas and Edge Cases:**
- `GetObject` response body is a `ReadableStream` (not a string) — you must consume it with `.transformToString()`, `.transformToByteArray()`, or pipe it to a writable stream.
- `DynamoDBDocumentClient` commands come from `@aws-sdk/lib-dynamodb`, NOT `@aws-sdk/client-dynamodb` — importing from the wrong package gives you raw `AttributeValue` types.
- Presigned URLs require the separate `@aws-sdk/s3-request-presigner` package — it is NOT included in `@aws-sdk/client-s3`.
- `InvokeCommand` returns `Payload` as a `Uint8Array` — decode with `new TextDecoder().decode(response.Payload)` before `JSON.parse`.
- SDK v3 version mismatches across client packages cause TypeScript errors — pin all `@aws-sdk/*` packages to the same version range.
- In Lambda, the SDK is bundled in the runtime but may be outdated — bundle your own version for latest features.
- `SQS ReceiveMessageCommand` may return `Messages: undefined` (not empty array) when no messages are available — always use `response.Messages ?? []`.
- Presigned URL expiry is capped at 7 days, but temporary credentials may expire sooner — the URL stops working when the signing credentials expire.
---
## CRITICAL REMINDERS
> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)
**(You MUST use AWS SDK v3 modular packages (`@aws-sdk/client-*`) — NEVER the monolithic `aws-sdk` v2 package)**
**(You MUST use the command pattern: `client.send(new XxxCommand({...}))` — NEVER call methods directly on the client)**
**(You MUST use `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb` for DynamoDB — it auto-marshalls native JS types)**
**(You MUST handle errors with `instanceof` specific exception classes — NEVER catch generic `Error` and check `.code`)**
**(You MUST use built-in paginators (`paginate*` functions) for paginated APIs — NEVER manually track continuation tokens)**
**Failure to follow these rules will cause bloated bundles (v2), lost type safety (direct calls), marshalling bugs (raw DynamoDB), and fragile error handling (string comparison).**