alfgoto/ddb-toolbox-skill

Overview

This skill is a concise guide for using DynamoDB-Toolbox v2, a lightweight TypeScript library that provides type-safe query building, schema validation, and the .build() command pattern for DynamoDB. It explains how to define Tables and Entities, declare schemas and attribute modifiers, and run commands like GetItem, PutItem, UpdateItem, Query, Scan, batch operations and transactions. The goal is to help you implement robust DynamoDB access with strong typing and predictable formatting. The content assumes TypeScript 5+ and strict typing in your project.

How this skill works

The guide walks through the import pattern, Table and Entity construction, and schema primitives/collections (string, number, list, map, record, anyOf). It shows the .build() fluent API used to create command builders for GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGet/Write and Transaction commands. It also documents conditional expressions, update modifiers ($add, $remove, $append, $set) and helper patterns like Single-Table design and EntityAccessPattern. Examples demonstrate options, pagination, parallel scans, and execute helpers for batch/transaction operations.

When to use it

• When you need type-safe DynamoDB access with schema validation in TypeScript.
• When you want a compact .build() fluent API for Get/Put/Update/Delete/Query/Scan commands.
• When implementing batch or transactional workflows across multiple entities or tables.
• When using single-table design or indexing via GSIs/LSIs and need entity mapping.
• When you require conditional writes, custom validations or default/transform logic on attributes.

Best practices

• Use TypeScript 5+ with "strict": true to get full type safety and schema inference.
• Define base key attributes (PK/SK) once and reuse via shared schemas for single-table design.
• Prefer schema modifiers (required, optional, default, transform) to centralize validation and formatting.
• Use .options({ filters, limit, index, exclusiveStartKey }) for predictable queries and pagination.
• Use update modifiers ($add, $remove, $append, $set) to express atomic updates and avoid client-side read/modify/write races.

Example use cases

• Define a User entity with computeKey to map userId to PK/SK and use PutItemCommand to create profiles.
• Query a user’s orders with MyTable.build(QueryCommand).query({ partition }).entities(OrderEntity) and paginate with LastEvaluatedKey.
• Perform atomic increments or list updates using UpdateItemCommand with $add and $append modifiers.
• Execute bulk reads/writes via BatchGet/BatchWrite and use executeBatchGet/executeBatchWrite to handle retries.
• Build multi-step transactions with executeTransactWrite combining PutTransaction, UpdateTransaction and ConditionCheck.