atelier-typescript-dynamodb-toolbox_skill

Overview

This skill provides a TypeScript-focused atelier for designing single-table DynamoDB schemas using dynamodb-toolbox v2. It packages patterns for entity definitions, key design, GSIs, queries, pagination, transactions, and type-safe repository layers. The goal is predictable, high-performance data access with clear modeling and robust error handling.

How this skill works

You define a single Table and multiple typed Entity objects using dynamodb-toolbox v2 schemas that separate business attributes from computed keys. Keys (PK/SK/GSI) are computed via linked schema functions and validated with the schema API, enabling compile-time types for inputs and formatted reads. The skill includes repository patterns that build Put/Get/Delete/Query/Transaction commands, plus utilities for cursor pagination and error translation to domain errors.

When to use it

• Building a microservice with known, stable access patterns that require sub-10ms reads and writes
• Implementing single-table design where multiple entity types share one DynamoDB table and GSIs
• Needing TypeScript type safety for entity input (writes) and formatted items (reads)
• Designing predictable, index-driven queries, pagination, and transactional operations
• Enforcing domain validation and converting DynamoDB condition failures into domain errors

Best practices

• Document all access patterns first: create an ERD, entity chart, and required queries before coding
• Compute PK/SK and GSI keys from business attributes using linked schema functions to keep reads/writes consistent
• Plan GSI roles (collection, relationship, temporal sorting) and avoid ad-hoc indexes
• Use conditional Put/Update for create/update semantics and map ConditionalCheckFailedException to domain errors
• Encode pagination cursors as base64-encoded LastEvaluatedKey and decode them on subsequent queries
• Write tests against DynamoDB Local, use unique IDs per test, and clean up fixtures after each run

Example use cases

• Define User, Repository, Issue, Comment, and Star entities that share a single table and common GSIs
• List repository issues with GSI queries and filter by status using beginsWith on the sort key
• Implement paginated repo listings by owner with reverse chronological ordering using a GSI3 SK timestamp
• Build a repository layer that enforces no-duplicate creates and converts DynamoDB errors to domain errors
• Run multi-entity transactions for operations that must be atomic (e.g., create issue + increment counter)