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 } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
import { Table } from 'dynamodb-toolbox/table';
import { Entity } from 'dynamodb-toolbox/entity';
import { item, string, number, list, map } from 'dynamodb-toolbox/schema';

const client = new DynamoDBClient({ region: process.env.AWS_REGION ?? 'eu-west-1' });
const documentClient = DynamoDBDocumentClient.from(client);

export const AppTable = new Table({
  name: 'app-single-table',
  partitionKey: { name: 'PK', type: 'string' },
  sortKey: { name: 'SK', type: 'string' },
  indexes: {
    byType: { type: 'global', partitionKey: { name: 'GSI1PK', type: 'string' }, sortKey: { name: 'GSI1SK', type: 'string' } }
  },
  documentClient
});