feat: MongoDB store

[tzezar]

feat: MongoDB store

Labels: enhancement, roadmap, help wanted

---

Summary

Add a MongoDB storage adapter for environments that already use MongoDB and don't want to add Redis.

Proposed API

import { mongoStore } from '@tzezar/throtto/stores/mongo'
import { MongoClient } from 'mongodb'

const client = new MongoClient('mongodb://localhost:27017')
const db = client.db('myapp')

const store = mongoStore({
  collection: db.collection('rate_limits'),  // or just db + auto-create
  ensureIndexes: true,                       // create TTL index on first use
  cleanupInterval: 0,                        // not needed - MongoDB TTL handles it
})

Implementation notes

• Use MongoDB TTL indexes for automatic expiration (no manual cleanup needed)
• findOneAndUpdate with upsert: true for atomic operations
• Peer dependency: mongodb >= 5
• Should work with both self-hosted MongoDB and MongoDB Atlas

Schema

{
  _id: "prefix:key",           // string key
  state: { ... },              // algorithm state (BSON object)
  expiresAt: ISODate(...),     // TTL index field
  createdAt: ISODate(...),
}

TTL index: { expiresAt: 1 }, { expireAfterSeconds: 0 }

Acceptance criteria

• mongoStore() factory function
• Peer dependency on mongodb >= 5
• Atomic operations via findOneAndUpdate
• TTL index for auto-expiration
• ping() health check
• keys(prefix) support
• ensureIndexes option
• Tests (unit + conformance suite)
• Documentation in docs/stores.md
• Export path: @tzezar/throtto/stores/mongo