dynamodb-toolbox-patterns

DynamoDB-Toolbox v2 Patterns (TypeScript)

Overview

This skill provides practical TypeScript patterns for using DynamoDB-Toolbox v2 with AWS SDK v3 DocumentClient. It focuses on type-safe schema modeling, .build() command usage, and production-ready single-table design.

When to Use

• Defining DynamoDB tables and entities with strict TypeScript inference
• Modeling schemas with item, string, number, list, set, map, and record
• Implementing GetItem, PutItem, UpdateItem, DeleteItem via .build()
• Building query and scan access paths with primary keys and GSIs
• Handling batch and transactional operations
• Designing single-table systems with computed keys and entity patterns

Instructions

1. Start from access patterns: identify read/write queries first, then design keys.
2. Create table + entity boundaries: one table, multiple entities if using single-table design.
3. Define schemas with constraints: apply .key(), .required(), .default(), .transform(), .link().
4. Use .build() commands everywhere: avoid ad-hoc command construction for consistency and type safety.
5. Add query/index coverage: validate GSI/LSI paths for each required access pattern.
6. Use batch/transactions intentionally: batch for throughput, transactions for atomicity.
7. Keep items evolvable: use optional fields, defaults, and derived attributes for schema evolution.

Examples

Install and Setup

npm install dynamodb-toolbox @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

import { DynamoDBClient } 

Entity Schema with Modifiers and Complex Attributes

.build() CRUD Commands

Query and Scan Patterns

Batch and Transaction Workflows

Single-Table Design Guidance

• Model each business concept as an entity with strict schema.
• Keep PK/SK predictable and composable (TENANT#, USER#, ORDER#).
• Encode access paths into GSI keys, not in-memory filters.
• Prefer append-only timelines for audit/history data.
• Keep hot partitions under control with scoped partitions and sharding where needed.

Best Practices

• Design keys from access patterns first, then derive entity attributes.
• Keep one source of truth for key composition (computeKey) to avoid drift.
• Use .options({ consistent: true }) only where strict read-after-write is required.
• Prefer targeted queries over scans for runtime request paths.
• Add conditional expressions for idempotency and optimistic concurrency control.
• Validate batch/transaction size limits before execution to avoid partial failures.

Constraints and Warnings

• DynamoDB-Toolbox v2 relies on AWS SDK v3 DocumentClient integration.
• Avoid table scans in request paths unless explicitly bounded.
• Use conditional writes for concurrency-sensitive updates.
• Transactions are limited and slower than single-item writes; use only for true atomic requirements.
• Validate key design against target throughput before implementation.

References

Primary references curated from Context7 are available in:

• references/api-dynamodb-toolbox-v2.md