Connection API

Functions for managing MongoDB connections.

Import

import { resolveConnection, disconnectAll, setDebug } from '@codician-team/monch';

resolveConnection()

Resolve a MongoDB connection from configuration:

async function resolveConnection(config: ConnectionConfig): Promise<ConnectionResult>

ConnectionConfig

interface ConnectionConfig {
  uri?: string;           // MongoDB connection string
  client?: MongoClient;   // Existing MongoClient
  db?: Db;               // Existing Db instance
  database?: string;      // Database name
}

ConnectionResult

interface ConnectionResult {
  client: MongoClient;    // MongoDB client
  db: Db;                // Database instance
}

Resolution Order

1. Existing Db instance (config.db)
2. Existing MongoClient (config.client + config.database)
3. Explicit URI (config.uri)
4. Environment variables (MONGODB_URI, MONGO_URL, DATABASE_URL)

Example

// Using environment variables (recommended)
const { client, db } = await resolveConnection({});

// Explicit URI
const { client, db } = await resolveConnection({
  uri: 'mongodb://localhost:27017/myapp',
});

// Existing client
const myClient = new MongoClient('mongodb://localhost:27017');
const { client, db } = await resolveConnection({
  client: myClient,
  database: 'myapp',
});

disconnectAll()

Close all cached MongoDB connections:

async function disconnectAll(): Promise<void>

Example

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('Shutting down...');
  await disconnectAll();
  process.exit(0);
});

setDebug()

Enable or configure debug logging:

function setDebug(config: boolean | DebugConfig): void

DebugConfig

interface DebugConfig {
  enabled: boolean;
  logger?: (operation: string, collection: string, ...args: any[]) => void;
}

Examples

// Enable with default logger
setDebug(true);

// Disable
setDebug(false);

// Custom logger
setDebug({
  enabled: true,
  logger: (operation, collection, ...args) => {
    console.log(`[DB] ${operation} ${collection}`, args);
  },
});

// Environment-based
setDebug(process.env.NODE_ENV === 'development');

Environment Variables

URI Variables (checked in order)

Variable	Description
MONGODB_URI	Primary connection string
MONGO_URL	Alternative (common in some platforms)
DATABASE_URL	Used only if it starts with mongodb:// or mongodb+srv://

Database Name Variables

Variable	Description
MONGODB_DATABASE	Database name
MONGO_DATABASE	Alternative

Priority

URI resolution:

1. Explicit uri config option
2. MONGODB_URI
3. MONGO_URL
4. DATABASE_URL (if MongoDB URI)

Database name resolution:

1. Explicit database config option
2. Database from URI path (mongodb://host/mydb)
3. MONGODB_DATABASE
4. MONGO_DATABASE

Connection Caching

Monch caches connections by URI to avoid creating multiple connections to the same database:

// First call creates connection
const users = await Users.find().toArray();

// Subsequent calls reuse the cached connection
const posts = await Posts.find().toArray();

// Same connection is used (if same URI)

Error Handling

import { MonchConnectionError } from '@codician-team/monch';

try {
  const { client, db } = await resolveConnection({});
} catch (error) {
  if (error instanceof MonchConnectionError) {
    console.error('Connection failed:', error.message);
    // Common messages:
    // - 'No MongoDB connection configured...'
    // - 'No database specified...'
    // - 'Failed to connect to MongoDB...'
  }
}