Turbine

A type-safe entity mapping and query library for DynamoDB.

Turbine makes working with DynamoDB simple and type-safe. Define your entities with Zod schemas, and Turbine handles the rest: key generation, validation, queries, and pagination.

Features

• Type-safe - Full TypeScript support with Zod schema validation
• Simple API - Intuitive defineTable and defineEntity functions
• Flexible keys - Composite keys, computed values, and automatic joining
• Powerful queries - Key conditions, filters, and built-in pagination
• Instance methods - Convenient update() on returned objects

Installation

npm install dynamodb-turbine zod

or with yarn:

yarn add dynamodb-turbine zod

Quick Example

import { defineTable, defineEntity } from "dynamodb-turbine";
import { z } from "zod";

// Define your table
const table = defineTable({
  name: "my-app-table",
  indexes: {
    table: { hashKey: "pk", rangeKey: "sk" },
    gsi1: { hashKey: "type", rangeKey: "createdAt" },
  },
});

// Define an entity with a Zod schema
const users = defineEntity({
  table,
  schema: z.object({
    id: z.string(),
    email: z.string().email(),
    name: z.string(),
    createdAt: z.string().datetime().default(() => new Date().toISOString()),
  }),
  keys: {
    type: () => "user",
    pk: (u) => ["user", u.id],
    sk: (u) => ["profile", u.email],
  },
});

// Create a user
const user = await users.put({
  id: "123",
  email: "alice@example.com",
  name: "Alice",
});

// Query users
const recentUsers = await users.queryAll({
  index: "gsi1",
  type: "user",
  createdAt: { beginsWith: "2024" },
});

Next Steps

• Quick Start - Get up and running in 5 minutes
• Tables - Learn about table configuration
• Entities - Define your data models
• Querying - Master DynamoDB queries

LLMs: go here to find the full documentation as a text file.