power-document-db

A lightweight utility library to simplify connecting and working with Amazon DocumentDB (with MongoDB compatibility).
Built for real-world usage, including production DocumentDB clusters, containerized local MongoDB, and Koa middleware integration.

---

📦 NPM Package

---

📚 Table of Contents

1. Features
2. Installation
3. Environment Variables
4. Usage
   • With Environment Variables
   • With Explicit Parameters
5. Koa Middleware
6. Transactions
7. API
8. Local Development
9. Troubleshooting
10. Contributing
11. Maintainers
12. License

---

✅ Features

• Connect easily to DocumentDB or local MongoDB
• SSL/TLS support with AWS CA certificates
• Works with Docker-based Mongo
• Koa middleware support → ctx.db
• Supports transactions
• TypeScript friendly
• Minimal, simple API

---

🔧 Installation

npm install @awsmag/power-document-db

---

🌍 Environment Variables

Variable	Description	Optional
CONNECTION_URI	Mongo/DocumentDB connection string	✅
DB_NAME	Database name	✅

If set → connectDb() can be called without arguments Otherwise → pass parameters explicitly

---

🚀 Usage

Using Environment Variables

import { connectDb } from "@awsmag/power-document-db";

async function main() {
  const db = await connectDb();
  const users = await db.collection("users").find({}).toArray();
  console.log(users);
}

main();

Passing Parameters Explicitly

import { connectDb } from "@awsmag/power-document-db";

async function main() {
  const uri = "mongodb://localhost:27017";
  const dbName = "test";
  const ssl = false;
  const tlsCAFile = "./certs/global-bundle.pem"; // Required only when ssl=true

  const db = await connectDb(uri, dbName, ssl, tlsCAFile);
}

---

🧩 Koa Middleware

Attach DB client automatically to ctx.db:

import Koa from "koa";
import { connectDb, getDbClientMw } from "@awsmag/power-document-db";

const app = new Koa();

(async () => {
  await connectDb("mongodb://localhost:27017", "test");
  app.use(getDbClientMw());

  app.use(async ctx => {
    const users = await ctx.db.collection("users").find({}).toArray();
    ctx.body = users;
  });

  app.listen(3000);
})();

---

🔄 Transactions

import { startSession } from "@awsmag/power-document-db";

async function runWithTransaction(db) {
  const session = await startSession();

  try {
    await session.startTransaction();

    await db.collection("orders").insertOne({ item: "Book" }, { session });

    await session.commitTransaction();
  } catch (err) {
    await session.abortTransaction();
    console.error("Transaction aborted:", err);
  } finally {
    session.endSession();
  }
}

---

🧠 API

connectDb(uri?, dbName?, ssl?, tlsCAFile?)

Returns: Promise<Db>

If no args → uses env variables

---

startSession()

Returns: Promise<ClientSession>

---

getDbClientMw()

Koa middleware → adds ctx.db

---

🛠 Local Development

Using Docker

docker run \
  -p 27017:27017 \
  --name mongo \
  mongo:latest

Then connect using:

mongodb://localhost:27017

Use ssl=false for local development.

---

❗ Troubleshooting

Issue	Fix
SSL enabled without CA bundle	Provide tlsCAFile
Timeout connecting to AWS DocDB	Check VPC + security group access
Transaction errors	Ensure cluster supports transactions
ctx.db undefined	Make sure connectDb() runs before middleware

---

🤝 Contributing

1. Fork the repo
2. Create branch → feature/my-change
3. Add tests if needed
4. Submit a PR

---

👨‍🔧 Maintainers

• AWSMAG
• S25 Digital

---

📄 License

MIT