Required dependencies

npm install @aws-sdk/client-dynamodb js-object-utilities
npm install --save-dev typescript @types/node

No native modules, no pod install, no Android linking, no Expo prebuild required.

Project setup

1. Copy the source/ directory into your project, e.g. src/dynamoose/.
2. In tsconfig.json, ensure "moduleResolution": "node" (or "bundler"), "strict": true, and that src/ is under rootDir:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "rootDir": "src",
    "outDir": "dist"
  }
}

3. Set AWS credentials via environment variables or the AWS SDK's default provider chain:

export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

4. For local development with DynamoDB Local, call ddb.local() early in your app bootstrap (see examples below).
5. Import from the entry point:

import dynamoose = require("./dynamoose"); // or the path to index.ts

Public API

model

function model<T extends Item = AnyItem>(
  name: string,
  schema?: Schema | SchemaDefinition | (Schema | SchemaDefinition)[],
  options?: ModelTableOptions
): ModelType<T>

Primary entry point for defining a DynamoDB model. Pass a table name, a schema definition object or Schema instance, and optional table options. Returns a model constructor with get, create, update, delete, query, scan, batchGet, batchPut, and transaction methods attached.

Schema

class Schema {
  constructor(definition: SchemaDefinition, options?: SchemaOptions)
}

Defines the shape, types, validation rules, indexes, and defaults for items stored in a table. Pass a plain object where keys are attribute names and values are type constructors or attribute config objects. Use when you need reuse, index definitions, or non-trivial validation beyond a plain definition literal.

Table

class Table extends InternalPropertiesClass<TableInternalProperties> {
  static defaults: TableOptions;
  constructor(name: string, models: ModelType<any>[], options?: TableOptionsOptional)
}

Manages the DynamoDB table lifecycle independently of any single model. Use it when adopting Single Table Design with multiple models sharing one table, or when you need explicit control over table creation, billing mode, and TTL configuration.

AWS (ddb)

class AWS {
  public ddb: DDBInterface; // callable: () => DynamoDB, plus .set(), .revert(), .local()
  public converter: typeof Converter;
}

Exposes the underlying DynamoDB client and attribute converter. Use ddb.local() in tests/dev, ddb.set(client) to inject a custom client (e.g. for multi-region), and ddb.revert() to reset to defaults.

Working examples

Scenario - Define a model and perform basic CRUD

Define a User model, create an item, retrieve it by key, update it, and delete it.

import dynamoose = require("./dynamoose/index");

const userSchema = new dynamoose.Schema({
  "id": { "type": String, "hashKey": true },
  "email": { "type": String, "required": true },
  "age": Number
});

const User = dynamoose.model("User", userSchema, {
  "create": true,
  "waitForActive": true
});

async function main() {
  // Create
  const user = await User.create({ "id": "u1", "email": "alice@example.com", "age": 30 });
  console.log("Created:", user);

  // Get
  const fetched = await User.get("u1");
  console.log("Fetched:", fetched);

  // Update
  const updated = await User.update({ "id": "u1" }, { "age": 31 });
  console.log("Updated:", updated);

  // Delete
  await User.delete("u1");
  console.log("Deleted");
}

main().catch(console.error);

Scenario - Query with conditions

Use the Condition builder and Model.query() for filtering on indexed attributes.

import dynamoose = require("./dynamoose/index");

const OrderSchema = new dynamoose.Schema({
  "userId": { "type": String, "hashKey": true },
  "orderId": { "type": String, "rangeKey": true },
  "status": {
    "type": String,
    "index": { "type": "global", "rangeKey": "createdAt", "name": "StatusIndex" }
  },
  "createdAt": { "type": Number }
});

const Order = dynamoose.model("Order", OrderSchema);

async function getUserOrders(userId: string) {
  const results = await Order
    .query("userId")
    .eq(userId)
    .where("status")
    .eq("PENDING")
    .exec();

  console.log("Orders:", results);
}

getUserOrders("user-42").catch(console.error);

Scenario - Use DynamoDB Local and transactions

Configure a local DynamoDB endpoint, then run a multi-operation transaction.

import dynamoose = require("./dynamoose/index");

// Point at DynamoDB Local
dynamoose.aws.ddb.local("http://localhost:8000");

const AccountSchema = new dynamoose.Schema({
  "id": { "type": String, "hashKey": true },
  "balance": Number
});
const Account = dynamoose.model("Account", AccountSchema);

async function transfer(fromId: string, toId: string, amount: number) {
  await dynamoose.transaction([
    Account.transaction.update(
      { "id": fromId },
      { "$ADD": { "balance": -amount } }
    ),
    Account.transaction.update(
      { "id": toId },
      { "$ADD": { "balance": amount } }
    )
  ]);
  console.log("Transfer complete");
}

transfer("acc-1", "acc-2", 50).catch(console.error);

File walkthrough

• index.ts — Assembles and re-exports all public symbols; the model() factory function lives here and checks ModelStore before creating a new Model instance.
• Model/index.ts — Implements the full Model class: all CRUD methods (get, create, update, delete, batchGet, batchPut), query/scan builders, serializer registration, and transaction helpers.
• Table/index.ts — Manages DynamoDB table lifecycle: tracks ready state, pending tasks, and triggers setup flow (create/update table, wait for active).
• Table/defaults.ts — Holds mutable default TableOptions that apply to all tables unless overridden per-table.
• Table/utilities.ts — Pure async functions for createTable, updateTable, updateTimeToLive, and waitForActive using the DynamoDB SDK.
• Schema.ts — Parses and validates schema definitions; resolves attribute types, index configurations, default, validate, required, enum, and set/get transforms.
• Item.ts — Base class for model instances; provides save(), delete(), populate(), and toJSON() on the instance level.
• ItemRetriever.ts — Fluent builder for Query and Scan operations, supporting chained filter/condition methods and exec().
• Condition.ts — Fluent Condition builder for constructing DynamoDB filter and key condition expressions.
• Transaction.ts — Exports the transaction() function and input types for composing multi-operation DynamoDB transactions.
• Serializer.ts — Allows registering named serializers on a model to project or transform output fields.
• ModelStore.ts — Simple registry (name → Model) enabling model lookup by name without circular imports.
• Instance.ts — Allows creating isolated Dynamoose instances with independent AWS config, useful for multi-region setups.
• Error.ts — Exports CustomError with subclasses like InvalidParameter, MissingKey, and TypeMismatch.
• General.ts — Shared TypeScript types: ModelType, KeyObject, InputKey, CallbackType, ItemArray, etc.
• aws/index.ts — Wraps ddb client factory and converter in a single AWS class exposed as dynamoose.aws.
• aws/ddb/index.ts — Stateful DynamoDB client factory; supports set, revert, and local for test/multi-region use.
• utils/ — Pure utility functions: deep_copy, merge_objects, combine_objects, array_flatten, async_reduce, unique_array_elements, and more.
• utils/dynamoose/ — Dynamoose-specific helpers: index diffing (index_changes), item serialization (itemToJSON), condition string building, and model return normalization.

Common pitfalls and fixes

• Missing AWS credentials at runtime: The SDK will throw a CredentialsProviderError; set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION or configure an IAM role.
• Table not ready before first operation: Set waitForActive: true in model/table options or call Table.waitForActive() explicitly before issuing queries.
• model() called twice with the same name returns the cached model: If you need a fresh model in tests, clear ModelStore or use a new Instance.
• ESM/CJS interop: index.ts uses export = (CommonJS style); import with import dynamoose = require(...) in TypeScript or const dynamoose = require(...) in JS. Named ES imports (import { model } from ...) will fail.
• Schema type mismatch at save time: Dynamoose enforces types strictly; ensure JavaScript Date values are used for Date schema types and Number for numeric attributes, not strings.
• Local DynamoDB endpoint not set before model creation: Call dynamoose.aws.ddb.local() before any model() or Table constructor call to ensure the local endpoint is used throughout.

Vibe-coding prompt template

I have a copy of the Dynamoose source (dynamoose npm package) located at `src/dynamoose/`
in my project. I also have a `USAGE.md` file in the same directory that documents
the real exported API, working code examples, and setup steps.

Please help me integrate Dynamoose into my existing Node.js/TypeScript/Express project
step by step:

1. Read `src/dynamoose/USAGE.md` for the correct import paths, exported symbols,
   and TypeScript signatures. Do not invent API methods not shown there.
2. Install the required dependencies listed in the ## Required dependencies section.
3. Set up the AWS DynamoDB client configuration (or local endpoint for development)
   using `dynamoose.aws.ddb.local()` or environment variables as described.
4. Define a Schema and Model for my [describe your entity, e.g. "User with id, email, createdAt"].
5. Add service functions for: create, get by key, update, delete, and a query by [field].
6. Wire these service functions into my Express route handlers.
7. Show me how to run a DynamoDB transaction for [describe your transaction use case].

Use only the real exports from `src/dynamoose/index.ts` as documented in USAGE.md.
Show complete, runnable TypeScript code with correct imports from `src/dynamoose/index`.

License and credit

Dynamoose is released under the MIT License (see source/LICENSE if present, or the GitHub repository). The upstream package is dynamoose by Charlie Fish and contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

ElectroDB DynamoDB Single-Table Entity Modeling Library

Automation, Utilities & Developer Tools

Free