nx-mongo

library4.0.1jsnpmunverified

A lightweight, feature-rich MongoDB helper library for Node.js and TypeScript (v4.0.1). Provides a simple API for CRUD operations, pagination, transactions, aggregation, index management, and more. Supports zero-config initialization via environment variables (ERC 2.0 using nx-config2), automatic connection retry with exponential backoff, config-driven ref mapping, and signature-based deduplication. Fully typed with TypeScript, actively maintained, and distributed as an ES module package. Differentiates from Mongoose by offering a lighter, non-ODM approach with built-in pipeline-friendly features.

database

npm install nx-mongo

package ↗

INSTALL

IMPORT

SIG · NX-MONGO

nx-mongo

databasejavascriptv4.0.1

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.

SimpleMongoHelper

✓ import { SimpleMongoHelper } from 'nx-mongo'

✗ const { SimpleMongoHelper } = require('nx-mongo')

Package is ESM-only since v4. For CommonJS, use dynamic import() or upgrade to Node >=16.

default

✓ import { SimpleMongoHelper } from 'nx-mongo'

✗ import SimpleMongoHelper from 'nx-mongo'

nx-mongo only provides named exports; there is no default export.

type SimpleMongoHelper

✓ import type { SimpleMongoHelper } from 'nx-mongo'

For type-only imports, use import type. This avoids bundling the runtime code.

Shows zero-config initialization, document insertion, and paginated query with metadata.

import { SimpleMongoHelper } from 'nx-mongo'; // Zero-config mode (requires MONGO_CONNECTION_STRING or MONGODB_URI env var) const helper = new SimpleMongoHelper(); await helper.initialize(); // Insert a document const result = await helper.insert('users', { name: 'John Doe', email: 'john@example.com', age: 30 }); console.log('Inserted:', result.insertedId); // Paginated query const { data, metadata } = await helper.find('users', { filter: { age: { $gt: 20 } }, page: 1, limit: 10 }); console.log('Page metadata:', metadata); // Clean up await helper.close();

Debug

Known issues

breakingPackage converted to ESM-only in v4; CommonJS require() will fail.

fix

Migrate to ES modules or use dynamic import() (e.g., const { SimpleMongoHelper } = await import('nx-mongo')).

affects: >=4.0.0

deprecatedThe constructor signature changed: SimpleMongoHelper(connectionString, options) is deprecated in favor of passing a config object or using zero-config.

fix

Use new SimpleMongoHelper({ connectionString: '...', retryOptions: {...} }) for explicit configuration.

affects: >=4.0.0

gotchaThe database name from the connection string is ignored; always use 'admin' by default or specify database in insert/find calls.

fix

Either rely on the default 'admin' database or pass the database name as the last parameter to methods like insert(data, options, dbName).

affects: *

gotchaRequires environment variables MONGO_CONNECTION_STRING or MONGODB_URI when using zero-config; missing env var throws at runtime.

fix

Set the required environment variable or pass configuration explicitly to the constructor.

affects: >=4.0.0

gotchaRetry logic applies only on initial connection; not per operation. Calls may fail if connection drops later.

fix

Implement application-level retry for individual operations or use a connection pool with automatic reconnection.

affects: *

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported.

Using require() on an ESM package in a CommonJS project.

fix

Switch to ES modules (set "type": "module" in package.json) or use dynamic import(): const { SimpleMongoHelper } = await import('nx-mongo').

MongoNotConnectedError: MongoClient must be connected to perform this operation

Calling helper methods before await helper.initialize() completes.

fix

Ensure you await initialize() before any CRUD operations: await helper.initialize(); await helper.insert(...).

TypeError: SimpleMongoHelper is not a constructor

Using default import instead of named import.

fix

Use import { SimpleMongoHelper } from 'nx-mongo'.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

mongodbrequiredCore MongoDB driver for database operations

nx-config2optionalZero-config environment-based initialization (ERC 2.0)

Agent activity

9 hits · last 30 days

node

Resources

packagenx-mongo ↗