MongoDB Connector

A high-performance, singleton MongoDB connection manager for Node.js microservices, built with Mongoose and TypeScript.

Features

• Singleton Pattern: Ensures a single active database connection per process.
• Connection Pooling: Optimized default settings for pool size, timeouts, and keep-alive.
• Graceful Shutdown: Automatically handles SIGINT and SIGTERM to close connections properly.
• Flexible Configuration: Connect via a full URI or individual parameters (host, port, dbName, etc.).
• TypeScript Support: Full type definitions included.

Installation

Since this is a local package, you can install it in other repositories using one of the following methods: or when deployed

npm install mongo-connector

Option 1: Install via Local Path (Recommended)

Refer to the package directory directly in your npm install command:

npm install /path/to/mongo-connector

Note: You must rebuild this package (npm run build) for changes to take effect in consuming projects.

Option 2: NPM Link (For Development)

1. In this directory (mongo-connector):

   npm link

2. In your target project:

   npm link mongodb-connector

Usage

1. Initialization

Initialize the connection at the start of your application. You must provide a configuration object(Example given below).

import { MongoConnection } from 'mongodb-connector';

async function bootstrap() {
  await MongoConnection.getInstance({
    // Option A: URI
    uri: "mongodb://localhost:27017/my-database",
    options: {
        appName: "my-service"
    }
  });
  

2. Accessing the Connection

Once initialized, you can retrieve the active connection instance anywhere in your app:

const connection = MongoConnection.getInstance();
// returns Promise<MongoConnection>

To get the raw Mongoose connection object:

const conn = (await MongoConnection.getInstance()).getConnection();

Configuration Options

The MongoConfig interface supports the following:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | uri | string | Yes | Full MongoDB connection string. | | options.appName | string | Yes | Identifier for the application (for monitoring). | | options.maxPoolSize | number | No | Max number of connections in the pool. Default: 5. | | options.minPoolSize | number | No | Min number of connections in the pool. Default: 0. | | options.maxIdleTimeMS | number | No | Close idle connections after this time (ms). Default: 30000. | | options.connectTimeoutMS | number | No | Fail if initial connection takes longer than this (ms). Default: 10000. | | options.socketTimeoutMS | number | No | Socket inactivity timeout (ms). Default: 10000. | | options.serverSelectionTimeoutMS | number | No | Max wait to find a working server (ms). Default: 15000. | | options.tls | boolean | No | Enable TLS for secure connections. Default: true. | | options.directConnection | boolean | No | Use direct connection instead of replica discovery. Default: false. |

Default Optimization

The connector comes with production-ready defaults:

• Pool Size: Max 5, Min 0 (configurable).
• Timeouts: optimized for fail-fast behavior.
• TLS: Enabled by default (set tls: false if needed for local dev without SSL).
• Compression: snappy/zstd enabled if available.

Build

To compile the TypeScript source:

npm run build