@zeroinbox/dynamo

Super simple, type-safe DynamoDB ORM for TypeScript.

It covers the exact DynamoDB patterns most apps repeat:

• typed table + index metadata
• put, get, delete, update
• batchGet, putMany, transactWrite
• PK/SK queries, prefix queries, GSI queries
• raw query escape hatch for advanced key conditions
• partition/index counting

Install

npm i @zeroinbox/dynamo

Quick Start

import { createDynamoClient, defineTable, model } from "@zeroinbox/dynamo";

type TaskItem = {
  ownerId: string;
  taskSk: string;
  scheduleKey?: string;
  status: "Open" | "Ready" | "Processing" | "Done";
  payload?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
};

const TasksTable = defineTable<TaskItem>()({
  name: "tasks-flows-prod",
  partitionKey: "ownerId",
  sortKey: "taskSk",
  indexes: {
    schedule: {
      name: "schedule-index",
      partitionKey: "ownerId",
      sortKey: "scheduleKey",
    },
  },
});

const client = createDynamoClient({ region: "us-east-1" });
const tasks = model(client, TasksTable);

await tasks.put({
  item: {
    ownerId: "USER#1",
    taskSk: "TASK#abc",
    scheduleKey: "STATUS#Open#2026-03-01T12:00:00.000Z",
    status: "Open",
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  },
});

const one = await tasks.get({
  key: { ownerId: "USER#1", taskSk: "TASK#abc" },
});

const queue = await tasks.queryIndexPrefix("schedule", {
  partitionValue: "USER#1",
  sortPrefix: "STATUS#Open#",
  scanIndexForward: true,
  limit: 50,
});

await tasks.update({
  key: { ownerId: "USER#1", taskSk: "TASK#abc" },
  set: {
    status: "Ready",
    updatedAt: new Date().toISOString(),
  },
  remove: ["scheduleKey"],
});

const totalForOwner = await tasks.count({
  partitionValue: "USER#1",
});

API

model(client, table, options?) returns:

• put, putMany
• get, delete, batchGet
• query, queryPrefix
• queryIndex, queryIndexPrefix
• queryRaw (custom key conditions / advanced GSI calls)
• update
• count, countIndex
• transactWrite

Query Sort Conditions

{ operator: "begins_with", value: "PREFIX#" }
{ operator: "=", value: "A" }
{ operator: ">", value: "2026-03-01T00:00:00.000Z" }
{ operator: "between", from: "A", to: "Z" }

Build

npm run typecheck
npm run build