@qumra/app-session-storage-mongodb

MongoDB-based session storage for Qumra apps — with automatic TTL index and connection management.

Installation

npm install @qumra/app-session-storage-mongodb @qumra/app-sdk

Requires mongodb >=6.0.0 as a peer dependency:

npm install -D mongodb

Connection Methods

Option A: Using Connection String

import { MongoDBSessionStorage } from '@qumra/app-session-storage-mongodb';

const sessionStorage = new MongoDBSessionStorage({
  url: 'mongodb://localhost:27017',
  dbName: 'qumra',
  collectionName: 'sessions'
});

Option B: Using Existing MongoDB Db Instance

import { MongoClient } from 'mongodb';
import { MongoDBSessionStorage } from '@qumra/app-session-storage-mongodb';

const client = new MongoClient('mongodb://localhost:27017');
await client.connect();
const db = client.db('qumra');

const sessionStorage = new MongoDBSessionStorage(db);

Usage with qumraApp

Initialize the session storage adapter:

import { qumraApp } from '@qumra/app-sdk';
import { MongoDBSessionStorage } from '@qumra/app-session-storage-mongodb';

const sessionStorage = new MongoDBSessionStorage({
  url: 'mongodb://localhost:27017',
  dbName: 'qumra'
});

const app = qumraApp({
  sessionStorage,
  // ... other config
});

API Reference

storeSession(store, session)

Stores or updates a session in the database.

await sessionStorage.storeSession('my-store', {
  id: 'session-123',
  userId: 'user-456',
  data: { preferences: { theme: 'dark' } },
  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
});

loadSession(store, id)

Retrieves a session by store and ID. Returns null if not found or expired.

const session = await sessionStorage.loadSession('my-store', 'session-123');

deleteSession(store, id)

Deletes a single session.

await sessionStorage.deleteSession('my-store', 'session-123');

deleteSessions(store, ids)

Deletes multiple sessions in a single operation.

await sessionStorage.deleteSessions('my-store', ['session-123', 'session-456']);

findSessionsByStore(store, options?)

Finds all sessions for a given store with optional filtering.

const sessions = await sessionStorage.findSessionsByStore('my-store', {
  userId: 'user-456',
  limit: 10,
  offset: 0,
});

disconnect()

Closes the MongoDB connection. Call this when your application shuts down.

await sessionStorage.disconnect();

ensureIndex()

Manually ensures that database indexes are created. Indexes are automatically created on first connection.

await sessionStorage.ensureIndex();

TTL Index

MongoDB automatically maintains a TTL (Time-To-Live) index on the expiresAt field. Sessions are automatically deleted when their expiration time passes:

const expiresIn24Hours = new Date(Date.now() + 24 * 60 * 60 * 1000);

await sessionStorage.storeSession('my-store', {
  id: 'session-123',
  userId: 'user-456',
  expiresAt: expiresIn24Hours,  // Auto-deleted after this date
  data: { /* ... */ }
});

MongoDB vs Prisma

| Feature | MongoDB | Prisma | |---------|---------|--------| | Database | NoSQL (document) | SQL (relational) | | Schema | Flexible, schema-less | Strict schema in prisma.schema | | Connection | Lazy (on first operation) | Requires explicit instantiation | | Migrations | None needed | Requires migration files | | Type Safety | Runtime type checking | Compile-time via generated types | | TTL/Expiration | Built-in TTL index | Manual cleanup required | | Scalability | Horizontal via sharding | Vertical via connection pooling |

Session Interface

Sessions conform to the following interface:

interface Session {
  id: string;
  store: string;
  userId?: string;
  data?: Record<string, any>;
  expiresAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

• id: Unique session identifier
• store: Logical store/namespace identifier
• userId: Optional user association
• data: Arbitrary session metadata
• expiresAt: Optional expiration timestamp
• createdAt: Session creation time
• updatedAt: Last modification time

Qumra Ecosystem

| Package | Description | |---|---| | @qumra/app-sdk | Core SDK — sessions, security, errors | | @qumra/app-react-router | React Router 7 integration | | @qumra/app-session-storage-prisma | Prisma session storage | | @qumra/app-session-storage-mongodb | MongoDB session storage | | @qumra/jisr | App Bridge — Admin communication | | @qumra/manara | Design system & components | | @qumra/riwaq | UI Extensions SDK |

License

ISC © Qumra