mongoist

library4.0.2jsnpmunverified

MongoDB driver for Node.js that wraps the official MongoDB driver with a lazy connection management pattern and async/await-friendly API. Current stable version is 4.0.2, requires Node >=16.20.1, and is released infrequently (last release 2023). Key differentiators vs mongojs: promise-only (no callbacks), lazy connection (supports async connection info via Promises), proxy-based collection access (db.collectionName instead of db.collection('name')). Compared to the official mongodb driver, mongoist automatically manages connections internally, eliminating boilerplate connection code and enabling easy module export of a not-yet-connected db instance.

database

npm install mongoist

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOIST

mongoist

databasejavascriptv4.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

mongoist

✓ import mongoist from 'mongoist'

✗ const mongoist = require('mongoist').default

Default export; used to create a database instance. ESM import works if using TypeScript with esModuleInterop.

mongoist

✓ const mongoist = require('mongoist')

✗ const { mongoist } = require('mongoist')

CJS: default export is the function itself.

db (instance)

✓ const db = mongoist(connectionString)

✗ const db = new mongoist(connectionString)

mongoist is a factory function, not a constructor. Do not use 'new'.

Connects to a MongoDB database using a connection string, performs find, insert, and count operations with async/await.

import mongoist from 'mongoist'; const db = mongoist('mongodb://localhost:27017/mydb'); async function run() { const docs = await db.mycollection.find({ age: { $gte: 18 } }); console.log(docs); // Insert a document await db.mycollection.insert({ name: 'Alice', age: 30 }); // Count documents const count = await db.mycollection.count(); console.log(`Total documents: ${count}`); // Close connection when done await db.close(); } run().catch(console.error);

Debug

Known issues

breakingmongoist v4 drops support for Node.js <16.20.1. If you use an older Node version, upgrade to Node 16+ or stay on v3.

fix

Upgrade Node.js to version >=16.20.1

affects: >=4.0.0

deprecatedThe method `db.collection('name')` is deprecated. Use the proxy-based collection access `db.name` instead.

fix

Replace `db.collection('foo')` with `db.foo`

affects: >=3.0.0

gotchaNever use `new mongoist()`; mongoist is a factory function. Using `new` will cause a runtime error.

fix

Use `const db = mongoist(connectionString)` without `new`.

affects: all

gotchaCollection names with special characters (e.g., `foo.bar`) cannot be accessed via proxy; use `db.collection('foo.bar')` instead.

fix

Use the explicit `db.collection('name')` method for collection names containing dots, dashes, or other special characters.

affects: all

gotchaMongoist does not support callbacks; all operations return promises. Using callback-style `.then()` or `await` is required.

fix

Use `await` or `.then()` to handle results; remove callback parameters.

affects: >=1.0.0

breakingAs of mongoist v2, `db.close()` returns a promise. Previously it returned undefined.

fix

Use `await db.close()` or `.then()` to ensure connection is closed.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: mongoist is not a function

Using named import instead of default import in ESM.

fix

Use `import mongoist from 'mongoist'` (default import) instead of `import { mongoist } from 'mongoist'`.

MongoError: not authorized for query on system.indexes

Connection string does not include authentication credentials, or user lacks permissions.

fix

Include credentials in the connection string: `mongoist('mongodb://user:pass@host:port/db')`

Error: Cannot find module 'mongodb'

The underlying `mongodb` package is not installed.

fix

Run `npm install mongodb` (mongoist lists `mongodb` as a peer dependency).

TypeError: db.collection is not a function

Using `db` variable before mongoist has resolved its connection (e.g., if connection info is a promise).

fix

Ensure you call `await db;` or use `db` inside an async function after the promise resolves.

MongoNetworkError: failed to connect to server [localhost:27017] on first connect

MongoDB server is not running or connection string is incorrect.

fix

Verify MongoDB is running (`mongod`) and the connection string is correct: `mongodb://localhost:27017/mydb`

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

mongodbrequiredUnderlying MongoDB driver; mongoist wraps the official Node.js MongoDB driver

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mongoist/mongoist ↗

packagemongoist ↗

homepagehttps://github.com/mongoist/mongoist#readme ↗