mongodb-uri

library0.9.7jsnpmunverified

The `mongodb-uri` library provides utilities for parsing and formatting MongoDB connection URIs in Node.js environments. It takes a URI string and converts it into a structured JavaScript object, and vice-versa, allowing programmatic manipulation of connection parameters. A key differentiator is its `formatMongoose` function, designed to transform multi-host MongoDB URIs into a format compatible with Mongoose's `connect()` method, which expects individual host/port pairs. This is particularly useful for environments like PaaS providers (e.g., Heroku with MongoLab) where a single URI might need adaptation. The current stable version is 0.9.7, indicating a pre-1.0 status, and the package has seen no updates since early 2017, suggesting it is no longer actively maintained. It handles URL encoding for special characters within usernames, passwords, and database names.

database

npm install mongodb-uri

github ↗package ↗

INSTALL

IMPORT

SIG · MONGODB-URI

mongodb-uri

databasejavascriptv0.9.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongodbUri

✓ const mongodbUri = require('mongodb-uri');

This package is CommonJS-only, reflecting its age. There are no ESM exports.

parse

✓ const { parse } = require('mongodb-uri');

Named destructuring for specific functions is common, but the primary export is the module object.

formatMongoose

✓ const { formatMongoose } = require('mongodb-uri');

This specific function is for adapting URIs for Mongoose's connection string format.

Demonstrates parsing a MongoDB URI string, formatting a URI object back to a string, and generating a Mongoose-compatible connection string from a multi-host URI.

const mongodbUri = require('mongodb-uri'); const uri = 'mongodb://user%3An%40me:p%40ssword@host:1234,host2:5678/d%40tabase?authSource=%40dmin&replicaSet=myReplicaSet'; // Parse the URI into an object const uriObject = mongodbUri.parse(uri); console.log('Parsed URI Object:'); console.log(JSON.stringify(uriObject, null, 2)); // Format the object back into a URI string const formattedUri = mongodbUri.format(uriObject); console.log('\nFormatted URI String:'); console.log(formattedUri); // Example for Mongoose compatibility (if multiple hosts are present) const mongooseConnectString = mongodbUri.formatMongoose(uri); console.log('\nMongoose Compatible URI String:'); console.log(mongooseConnectString);

Debug

Known issues

breakingThe package has not been updated since January 2017 (version 0.9.7). It may not support newer MongoDB URI features, options, or authentication mechanisms (e.g., `mongodb+srv` SRV records) introduced in modern MongoDB versions and drivers.

fix

Consider using the native MongoDB Node.js driver's `MongoClient` connection string parsing or actively maintained alternatives like `mongodb-url` or `mongo-uri-builder` if modern MongoDB features are required.

affects: <=0.9.7

gotchaThe library notes two minor differences from the standard MongoDB connection string URI format: passwords are optional even with a username, and the slash before the database is not required when specifying options without a database. While this might not prevent parsing standard URIs, it highlights potential deviations.

fix

Always test parsing results against expected standard MongoDB URI structures, especially for edge cases involving missing passwords or database paths.

affects: >=0.6.0

gotchaThis package is CommonJS-only and does not provide ESM exports. This means it cannot be directly imported using `import ... from 'mongodb-uri'` in pure ESM Node.js projects, requiring `require()` or bundling solutions.

fix

For ESM projects, use `const mongodbUri = require('mongodb-uri');` or consider transpilation/bundling. Alternatively, use a modern alternative that supports ESM.

affects: >=0.6.0

gotchaThe package does not inherently handle IPv6 addresses, which has been reported as an open issue.

fix

Avoid using this package for MongoDB URIs involving IPv6 addresses, or manually parse and format IPv6 host portions if absolutely necessary.

affects: >=0.6.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'split')

Input URI string is `undefined` or `null` when passed to `parse` or `formatMongoose`.

fix

Ensure the URI variable is a valid string before passing it to `mongodbUri.parse()` or `mongodbUri.formatMongoose()`. For example, `const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/test';`

Error: Invalid URI: '...'

The input string does not conform to the expected MongoDB URI format or contains unescaped special characters.

fix

Review the URI format against the MongoDB connection string specification. Ensure special characters in username, password, or database name are properly URL-encoded (e.g., `@` becomes `%40`, `:` becomes `%3A`).

Upgrade

Version history

0.9.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mongolab/mongodb-uri-node ↗

packagehttps://www.npmjs.com/package/mongodb-uri ↗