Type-safe DynamoDB (SDK v3) client for single-table design with powerful querying, great DX, and first-class TypeScript.

Install

npm i @karmaniverous/entity-client-dynamodb

Quick start (tiny)

import {
  EntityClient,
  generateTableDefinition,
} from '@karmaniverous/entity-client-dynamodb';
import { EntityManager } from '@karmaniverous/entity-manager';

declare const entityManager: EntityManager<any>;

const client = new EntityClient({
  entityManager,
  tableName: 'UserTable',
  region: 'local',
});

// One-time table creation (from EntityManager config)
await client.createTable({
  BillingMode: 'PAY_PER_REQUEST',
  ...generateTableDefinition(entityManager),
});

// Put / Get (storage records; strip keys for domain)
await client.putItem({ hashKey2: 'h', rangeKey: 'r', a: 1 });
const out = await client.getItem('user', { hashKey2: 'h', rangeKey: 'r' });
const item = out.Item && client.entityManager.removeKeys('user', out.Item);

Documentation (guides)

• Getting Started - Install, wire, and make your first calls.
• EntityClient: CRUD and Batches - Record/recordset operations with strong types.
• Querying with QueryBuilder - Cross-shard, multi-index querying and projections.
• Tables & Table Definition - Generate AttributeDefinitions/GSIs/KeySchema.
• Type Inference Mental Model - Tokens, projection K, and values‑first config (CF-enabled index inference).
• AWS X-Ray - Enable tracing for the DynamoDB SDK client.

CLI Plugin (get-dotenv)

• CLI Plugin - get-dotenv plugin (subpath export @karmaniverous/entity-client-dynamodb/get-dotenv) for versioned table lifecycle, transforms, migration, config overlays, Local DynamoDB, Serverless, and recipes.

API Reference

• TypeDoc API - Full API surface generated from the source.

License

BSD-3-Clause

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.