@maykonpaulo/maestro-provider-dynamodb

📖 Guia completo — criar o admin de qualquer sistema: está no README do pacote @maykonpaulo/maestro-server no npm → https://www.npmjs.com/package/@maykonpaulo/maestro-server

An Amazon DynamoDB provider for @maykonpaulo/maestro-core — a key-value/document-family provider (ADR 0007).

• IntrospectionProvider — DescribeTable's KeySchema gives the real partition/sort key (not a guess, unlike every other schemaless provider in this monorepo); every other attribute is inferred by scanning the whole table, since DynamoDB items in the same table can hold completely different attributes.
• DatasourceProvider — real list/findById/create/update/delete/count via @aws-sdk/lib-dynamodb, filters/sort/search applied in-process after a full Scan (DynamoDB's own filter expressions aren't expressive enough for the core's generic FilterDescriptor set).
• SchemaWriteProvider — ensureEntity creates the table (waiting for it to become ACTIVE) — requires entity.fields to include exactly one field with isPrimaryKey: true, since DynamoDB mandates a partition key at creation time, unlike a relational CREATE TABLE's more flexible key story.

Installation

npm install @maykonpaulo/maestro-provider-dynamodb @maykonpaulo/maestro-core

@maykonpaulo/maestro-core, @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb are peer dependencies.

Usage

import { createDynamoDbProvider } from '@maykonpaulo/maestro-provider-dynamodb';

const provider = createDynamoDbProvider({ region: 'us-east-1' }); // real AWS, via default credential chain
// or, against DynamoDB Local: createDynamoDbProvider({ endpoint: 'http://localhost:8000', credentials: { accessKeyId: 'local', secretAccessKey: 'local' } })

await provider.ensureEntity({
  entity: { table: 'users', fields: [{ name: 'id', nativeType: '', type: 'uuid', nullable: false, isPrimaryKey: true }] },
});
const created = await provider.create({ table: 'users', primaryKey: 'id', data: { name: 'Ada' } });

Configuration

export interface DynamoDbProviderOptions {
  region?: string;
  endpoint?: string;      // point at DynamoDB Local or a custom endpoint
  credentials?: { accessKeyId: string; secretAccessKey: string; sessionToken?: string };
  client?: DynamoDBDocumentClient; // an already-connected document client — for tests/embedding
}

All fields are optional — with none set, the AWS SDK's default credential/region resolution chain applies. Call await provider.close() when done with a provider that opened its own client.

Known limitations

• list/count scan the whole table and filter/sort/paginate client-side — correct, but DynamoDB's own indexed Query (much cheaper than Scan) is not used, since the core's generic filter set doesn't map onto "query only by partition/sort key" the way DynamoDB expects.
• No relations, no secondary indices: neither is introspected.
• ensureEntity requires a declared partition key: unlike other providers, this one cannot infer or default one — DynamoDB has no concept of a table without one.
• Composite (partition + sort) keys: ensureEntity only ever creates a single-attribute HASH key; a table needing a sort key must be created outside this provider.

Testing

Tests run against a real, ephemeral DynamoDB Local server, started per test run via Docker (amazon/dynamodb-local:latest, through testcontainers's GenericContainer — no dedicated @testcontainers/dynamodb module exists). See tests/dynamodb-integration.test.ts.

Turnkey admin (point at your database, get a UI)

This provider plugs straight into the Maestro turnkey layer: install @maykonpaulo/maestro-server and @maykonpaulo/maestro-admin, point them at your database and get a full governed admin (list/CRUD/RBAC/audit + a metadata-driven UI) with no per-entity code.

import { createDynamoDbProvider } from '@maykonpaulo/maestro-provider-dynamodb';
import { createMaestroServer, createIntrospectedEngine } from '@maykonpaulo/maestro-server';

const provider = createDynamoDbProvider({ region: 'us-east-1' });
const engine = await createIntrospectedEngine({ provider, access: 'full' });
await createMaestroServer({ engine }).listen(3000);

See the Turnkey admin guide.