infra-platform-aws-sdk
AWS SDK v3 for TypeScript — modular clients, command pattern, S3, DynamoDB, SQS, Lambda, SNS, Secrets Manager
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/infra-platform-aws-sdk/skills/infra-platform-aws-sdk
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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, callclient.send(command). Import only the services you need for tree-shaking. UseDynamoDBDocumentClientfor native JS types. UsegetSignedUrlfrom@aws-sdk/s3-request-presignerfor presigned URLs. Handle errors withinstanceofspecific exception classes. Use built-in paginators (paginate*) withfor await...of.
<critical_requirements>
CRITICAL: Before Using This Skill
(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)
</critical_requirements>
Examples
- Core Patterns — Client setup, S3 operations, DynamoDB basics, credential providers, error handling, pagination
- Messaging — SQS send/receive/delete, SNS publish, FIFO queues, dead-letter patterns
- Advanced — Lambda invocation, Secrets Manager, presigned URLs, middleware, streaming
- Quick Reference — 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:
DynamoDBDocumentClientwithGet,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
instanceofexception classes and$metadata - Pagination with async iterators
- Middleware stack customization
- Retry configuration
<decision_framework>
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
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Using the monolithic
aws-sdkv2 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
DynamoDBClientcommands with manualmarshall()/unmarshall()— useDynamoDBDocumentClientfrom@aws-sdk/lib-dynamodb. - Catching errors with
.codestring comparison (v2 style) — useinstanceofwith typed exception classes. - Manually tracking pagination tokens in a while loop — use built-in
paginate*functions withfor 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-dynamodband@aws-sdk/lib-dynamodbcommand imports — pick one approach per codebase. - Missing
ContentTypeon S3PutObject— S3 defaults toapplication/octet-stream, breaking browser downloads. - Not buffering the S3
GetObjectresponse body —response.Bodyis a stream; call.transformToString()or.transformToByteArray().
Gotchas and Edge Cases:
GetObjectresponse body is aReadableStream(not a string) — you must consume it with.transformToString(),.transformToByteArray(), or pipe it to a writable stream.DynamoDBDocumentClientcommands come from@aws-sdk/lib-dynamodb, NOT@aws-sdk/client-dynamodb— importing from the wrong package gives you rawAttributeValuetypes.- Presigned URLs require the separate
@aws-sdk/s3-request-presignerpackage — it is NOT included in@aws-sdk/client-s3. InvokeCommandreturnsPayloadas aUint8Array— decode withnew TextDecoder().decode(response.Payload)beforeJSON.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 ReceiveMessageCommandmay returnMessages: undefined(not empty array) when no messages are available — always useresponse.Messages ?? [].- Presigned URL expiry is capped at 7 days, but temporary credentials may expire sooner — the URL stops working when the signing credentials expire.
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(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).
</critical_reminders>
Files (skills)
-
examples
-
advanced.md 8.8 KB
Loading… -
core.md 9.9 KB
Loading… -
messaging.md 6.1 KB
Loading…
-
-
reference.md 5.1 KB
Loading… -
SKILL.md 15.7 KB
--- 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_requirements> ## CRITICAL: Before Using This Skill **(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)** </critical_requirements> --- ## 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> ## 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 </philosophy> --- <patterns> ## 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. </patterns> --- <decision_framework> ## 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 ``` </decision_framework> --- <red_flags> ## 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. </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(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).** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.