{"id":45636,"library":"nx-mongo","title":"nx-mongo","description":"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.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","mongodb","helper","typescript","database","orm","odm","pagination","transactions"],"install":[{"cmd":"npm install nx-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add nx-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add nx-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core MongoDB driver for database operations","package":"mongodb","optional":false},{"reason":"Zero-config environment-based initialization (ERC 2.0)","package":"nx-config2","optional":true}],"imports":[{"note":"Package is ESM-only since v4. For CommonJS, use dynamic import() or upgrade to Node >=16.","wrong":"const { SimpleMongoHelper } = require('nx-mongo')","symbol":"SimpleMongoHelper","correct":"import { SimpleMongoHelper } from 'nx-mongo'"},{"note":"nx-mongo only provides named exports; there is no default export.","wrong":"import SimpleMongoHelper from 'nx-mongo'","symbol":"default","correct":"import { SimpleMongoHelper } from 'nx-mongo'"},{"note":"For type-only imports, use import type. This avoids bundling the runtime code.","wrong":"","symbol":"type SimpleMongoHelper","correct":"import type { SimpleMongoHelper } from 'nx-mongo'"}],"quickstart":{"code":"import { SimpleMongoHelper } from 'nx-mongo';\n\n// Zero-config mode (requires MONGO_CONNECTION_STRING or MONGODB_URI env var)\nconst helper = new SimpleMongoHelper();\nawait helper.initialize();\n\n// Insert a document\nconst result = await helper.insert('users', {\n  name: 'John Doe',\n  email: 'john@example.com',\n  age: 30\n});\nconsole.log('Inserted:', result.insertedId);\n\n// Paginated query\nconst { data, metadata } = await helper.find('users', {\n  filter: { age: { $gt: 20 } },\n  page: 1,\n  limit: 10\n});\nconsole.log('Page metadata:', metadata);\n\n// Clean up\nawait helper.close();\n","lang":"typescript","description":"Shows zero-config initialization, document insertion, and paginated query with metadata."},"warnings":[{"fix":"Migrate to ES modules or use dynamic import() (e.g., const { SimpleMongoHelper } = await import('nx-mongo')).","message":"Package converted to ESM-only in v4; CommonJS require() will fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use new SimpleMongoHelper({ connectionString: '...', retryOptions: {...} }) for explicit configuration.","message":"The constructor signature changed: SimpleMongoHelper(connectionString, options) is deprecated in favor of passing a config object or using zero-config.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Either rely on the default 'admin' database or pass the database name as the last parameter to methods like insert(data, options, dbName).","message":"The database name from the connection string is ignored; always use 'admin' by default or specify database in insert/find calls.","severity":"gotcha","affected_versions":"*"},{"fix":"Set the required environment variable or pass configuration explicitly to the constructor.","message":"Requires environment variables MONGO_CONNECTION_STRING or MONGODB_URI when using zero-config; missing env var throws at runtime.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Implement application-level retry for individual operations or use a connection pool with automatic reconnection.","message":"Retry logic applies only on initial connection; not per operation. Calls may fail if connection drops later.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"search_vec":"'2.0':40 'activ':65 'aggreg':26 'api':20 'approach':84 'automat':45 'backoff':50 'base':59 'built':87 'built-in':86 'config':34,52 'config-driven':51 'config2':44 'connect':46 'crud':22 'databas':97 'dedupl':60 'differenti':74 'distribut':68 'driven':53 'environ':37 'erc':39 'es':71 'exponenti':49 'featur':7,92 'feature-rich':6 'friend':91 'fulli':61 'helper':10,95 'index':27 'initi':35 'javascript':93 'librari':11 'lighter':80 'lightweight':5 'maintain':66 'manag':28 'map':55 'modul':72 'mongo':3 'mongodb':9,94 'mongoos':76 'node.js':13 'non':82 'non-odm':81 'nx':2,43 'nx-config2':42 'nx-mongo':1 'odm':83,99 'offer':78 'oper':23 'orm':98 'packag':73 'pagin':24,100 'pipelin':90 'pipeline-friend':89 'provid':17 'ref':54 'retri':47 'rich':8 'signatur':58 'signature-bas':57 'simpl':19 'support':31 'transact':25,101 'type':62 'typescript':15,64,96 'use':41 'v4.0.1':16 'variabl':38 'via':36 'zero':33 'zero-config':32","created_at":"2026-06-07T12:55:58.848261+00:00","updated_at":"2026-06-07T12:55:58.848261+00:00","problems":[{"fix":"Switch to ES modules (set \"type\": \"module\" in package.json) or use dynamic import(): const { SimpleMongoHelper } = await import('nx-mongo').","cause":"Using require() on an ESM package in a CommonJS project.","error":"ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported."},{"fix":"Ensure you await initialize() before any CRUD operations: await helper.initialize(); await helper.insert(...).","cause":"Calling helper methods before await helper.initialize() completes.","error":"MongoNotConnectedError: MongoClient must be connected to perform this operation"},{"fix":"Use import { SimpleMongoHelper } from 'nx-mongo'.","cause":"Using default import instead of named import.","error":"TypeError: SimpleMongoHelper is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"nx-mongo","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}