DynamoFlow

A practical & extendable DynamoDB client for TypeScript applications.

Release notes

Features

• Supports & encourages single table design
• Abstracts your different item types into collections
• Transactions
• Unique constraints
• Secondary indexes
• Timestamping
• Zod validation
• TTL
• Foreign counts
• Extendable via extensions
• On the fly schema migrations
• Scan / batch schema migrations

Why?

Unlike many other database technologies, DynamoDB expects your data management logic to live in the application layer. Rather than providing built-in features such as unique fields, foreign keys, or cascading deletes, DynamoDB provides the foundational technologies to implement these features yourself.

Rather than picking which of these features we do and don't include, DynamoFlow provides a set of tools to make it easy to implement these features yourself. We also provide a set of ready-to-go extensions for common patters, such as unique fields, foreign keys, secondary indexes & timestamping

There are several other Typescript DynamoDB clients available, and I encourage you to check them all out before committing to one.

My personal favourites are

• dynamodb-toolbox
• TypeDORM
• AWS lib-dynamodb

Getting Started

1. Install the package: npm install --save dynamoflow or yarn add dynamoflow
2. Install the Amazon SDK, if not already installed npm install --save @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb or yarn add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
3. Start DynamoDB Local docker run -p 8000:8000 amazon/dynamodb-local (or copy our example docker-compose.yml file)
4. Create a DFTable instance
   1. Following single table design, your application will likely only have one DFTable instance
   2. AWS credentials are loaded from the v3 SDK

import {DFTable} from "dynamoflow";

const table = new DFTable({
  tableName: "my-application-table",
  GSIs: ["GSI1", "GSI2"], // GSIs can be added later if needed

  // using DynamoDBLocal
  endpoint: "http://localhost:8000",
});

// not recommended for production use, but useful for local development
await table.createTableIfNotExists();

4. Define types for your entities
   1. Any normal TypeScript type can be used, DynamoFlow does not care about the schema of your objects
   2. If desired, you can use extensions like DFZodValidationExt to validate your objects at runtime
5. Create collections for each entity type you have
   1. Collections are used to read & write from your table
   2. Many collections can exist within a single Table
   3. Extensions can be used to add additional functionality to your collections

import {DFUniqueConstraintExt} from "dynamoflow";

interface User {
   id: string;

   name: string;
   email: string;
}

const usersCollection = table.createCollection<User>({
   name: "users",
   partitionKey: "id",
   extensions: [
      new DFUniqueConstraintExt('email')
   ],
});

interface Project {
   id: string;
   userId: string;

   name: string;
   description: string;

   status: "DRAFT" | "IN-PROGRESS" | "COMPLETED";
}

const projectsCollection = table.createCollection<Project>({
   // the name of the collection is used to prefix the partition key for each item
   name: "projects",

   // any string, number or boolean fields of this entity can be used as keys
   // different collections can have different keys
   partitionKey: "userId",
   sortKey: "id"
});

6. Use these collections to read & write from your table

const user1 = await usersCollection.insert({
    id: "user-1",
    name: "John Smith",
    email: "[email protected]"
});

const insertedProject = await projectsCollection.insert({
  id: "project-1",
  userId: user1.id,

  name: "My First Project",
  description: "This is my first project",

  status: "DRAFT",
});

await projectsCollection.update({
  id: "project-1"
}, {
  status: "IN-PROGRESS"
});

const retrievedProject = await projectsCollection.retrieveOne({
  where: {
    userId: "user-1",
    id: "project-1"
  }
});

For a more comprehensive example, take a look at the included Messaging app demo.

Once you're ready to test against a real DynamoDB table, read Configuring DynamoDB Tables