giuseppe-trisciuoglio/developer-kit

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys.

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill dynamodb-toolbox-patterns

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

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

bash
npm install dynamodb-toolbox @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
typescript
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
});

Entity Schema with Modifiers and Complex Attributes

typescript
const now = () => new Date().toISOString();

export const UserEntity = new Entity({
  name: 'User',
  table: AppTable,
  schema: item({
    tenantId: string().required('always'),
    userId: string().required('always'),
    email: string().required('always').transform(input => input.toLowerCase()),
    role: string().enum('admin', 'member').default('member'),
    loginCount: number().default(0),
    tags: list(string()).default([]),
    profile: map({
      displayName: string().optional(),
      timezone: string().default('UTC')
    }).default({ timezone: 'UTC' })
  }),
  computeKey: ({ tenantId, userId }) => ({
    PK: `TENANT#${tenantId}`,
    SK: `USER#${userId}`,
    GSI1PK: `TENANT#${tenantId}#TYPE#USER`,
    GSI1SK: `EMAIL#${userId}`
  })
});

.build() CRUD Commands

typescript
import { PutItemCommand } from 'dynamodb-toolbox/entity/actions/put';
import { GetItemCommand } from 'dynamodb-toolbox/entity/actions/get';
import { UpdateItemCommand, $add } from 'dynamodb-toolbox/entity/actions/update';
import { DeleteItemCommand } from 'dynamodb-toolbox/entity/actions/delete';

await UserEntity.build(PutItemCommand)
  .item({ tenantId: 't1', userId: 'u1', email: 'A@Example.com' })
  .send();

const { Item } = await UserEntity.build(GetItemCommand)
  .key({ tenantId: 't1', userId: 'u1' })
  .send();

await UserEntity.build(UpdateItemCommand)
  .item({ tenantId: 't1', userId: 'u1', loginCount: $add(1) })
  .send();

await UserEntity.build(DeleteItemCommand)
  .key({ tenantId: 't1', userId: 'u1' })
  .send();

Query and Scan Patterns

typescript
import { QueryCommand } from 'dynamodb-toolbox/table/actions/query';
import { ScanCommand } from 'dynamodb-toolbox/table/actions/scan';

const byTenant = await AppTable.build(QueryCommand)
  .query({
    partition: `TENANT#t1`,
    range: { beginsWith: 'USER#' }
  })
  .send();

const byTypeIndex = await AppTable.build(QueryCommand)
  .query({
    index: 'byType',
    partition: 'TENANT#t1#TYPE#USER'
  })
  .options({ limit: 25 })
  .send();

const scanned = await AppTable.build(ScanCommand)
  .options({ limit: 100 })
  .send();

Batch and Transaction Workflows

typescript
import { BatchWriteCommand } from 'dynamodb-toolbox/table/actions/batchWrite';
import { TransactWriteCommand } from 'dynamodb-toolbox/table/actions/transactWrite';

await AppTable.build(BatchWriteCommand)
  .requests(
    UserEntity.build(PutItemCommand).item({ tenantId: 't1', userId: 'u2', email: 'u2@example.com' }),
    UserEntity.build(PutItemCommand).item({ tenantId: 't1', userId: 'u3', email: 'u3@example.com' })
  )
  .send();

await AppTable.build(TransactWriteCommand)
  .requests(
    UserEntity.build(PutItemCommand).item({ tenantId: 't1', userId: 'u4', email: 'u4@example.com' }),
    UserEntity.build(UpdateItemCommand).item({ tenantId: 't1', userId: 'u1', loginCount: $add(1) })
  )
  .send();

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

Relacionados por tarea

del mismo repositorio

Más Skills

Todos los Skills
giuseppe-trisciuoglio
Comunidad

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

Instalaciones / 1h
3
GitHub Stars
372
Actualizado
10 sept
giuseppe-trisciuoglio
Comunidad

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

Instalaciones / 1h
1
GitHub Stars
372
Actualizado
10 sept
giuseppe-trisciuoglio
Comunidad

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

Instalaciones / 1h
1
GitHub Stars
371
Actualizado
10 sept
giuseppe-trisciuoglio
Comunidad

typescript-security-review

Provides security review capability for TypeScript/Node.js applications, validates code against XSS, injection, CSRF, JWT/OAuth2 flaws, dependency CVEs, and secrets exposure. Use when performing security audits, before deployment, reviewing authentication/authorization implementations, or ensuring OWASP compliance for Express, NestJS, and Next.js. Triggers on "security review", "check for security issues", "TypeScript security audit".

Instalaciones / 1h
1
GitHub Stars
371
Actualizado
10 sept