{"id":45780,"library":"pip-services3-mongodb-nodex","title":"Pip.Services MongoDB Components for Node.js","description":"Provides MongoDB persistence components for the Pip.Services microservice toolkit. Current stable version is 1.1.3, part of the Pip.Services NodeX ecosystem. It offers abstract base classes like IdentifiableMongoDbPersistence for CRUD operations, connection management via MongoDbConnection, and factory patterns for building persistence. Supports ES2017+ and TypeScript. Release cycle tied to Pip.Services updates. Differentiates by providing a standardized, configurable persistence layer for microservices with built-in filtering, paging, and indexing support.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/pip-services3-nodex/pip-services3-mongodb-nodex","tags":["javascript","pip.services","microservice","mongodb","library","typescript"],"install":[{"cmd":"npm install pip-services3-mongodb-nodex","lang":"bash","label":"npm"},{"cmd":"yarn add pip-services3-mongodb-nodex","lang":"bash","label":"yarn"},{"cmd":"pnpm add pip-services3-mongodb-nodex","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Pip.Services types (IIdentifiable, FilterParams, PagingParams, DataPage) required for persistence implementations.","package":"pip-services3-commons-nodex","optional":false},{"reason":"Official MongoDB Node.js driver, version 4.x or 5.x compatible.","package":"mongodb","optional":false}],"imports":[{"note":"This is a named export, not default. Must use named import syntax.","wrong":"import IdentifiableMongoDbPersistence from 'pip-services3-mongodb-nodex'","symbol":"IdentifiableMongoDbPersistence","correct":"import { IdentifiableMongoDbPersistence } from 'pip-services3-mongodb-nodex'"},{"note":"Used for configuring and managing MongoDB connections via Pip.Services connection parameters.","symbol":"MongoDbConnection","correct":"import { MongoDbConnection } from 'pip-services3-mongodb-nodex'"},{"note":"Factory class to register MongoDB persistence components in Pip.Services container.","symbol":"DefaultMongoDbFactory","correct":"import { DefaultMongoDbFactory } from 'pip-services3-mongodb-nodex'"},{"note":"Variant that stores documents as JSON strings, useful for versioning.","symbol":"IdentifiableJsonMongoDbPersistence","correct":"import { IdentifiableJsonMongoDbPersistence } from 'pip-services3-mongodb-nodex'"}],"quickstart":{"code":"import { IdentifiableMongoDbPersistence } from 'pip-services3-mongodb-nodex';\nimport { IIdentifiable } from 'pip-services3-commons-nodex';\nimport { FilterParams, PagingParams, DataPage } from 'pip-services3-commons-nodex';\n\ninterface MyObject extends IIdentifiable {\n  key: string;\n  value: number;\n}\n\nclass MyMongoDbPersistence extends IdentifiableMongoDbPersistence<MyObject> {\n  constructor() {\n    super('myobjects');\n    this.ensureIndex({ key: 1 }, { unique: true });\n  }\n\n  private composeFilter(filter: FilterParams): any {\n    filter = filter || new FilterParams();\n    const criteria: any[] = [];\n    const id = filter.getAsNullableString('id');\n    if (id != null) criteria.push({ _id: id });\n    const ids = filter.getAsNullableString('ids');\n    if (ids != null) criteria.push({ _id: { $in: ids.split(',') } });\n    const key = filter.getAsNullableString('key');\n    if (key != null) criteria.push({ key: key });\n    return criteria.length > 0 ? { $and: criteria } : null;\n  }\n\n  public getPageByFilter(correlationId: string, filter: FilterParams, paging: PagingParams, callback: (err: any, page: DataPage<MyObject>) => void): void {\n    super.getPageByFilter(correlationId, this.composeFilter(filter), paging, '_id', null, callback);\n  }\n\n  public getOneByKey(correlationId: string, key: string, callback: (err: any, item: MyObject) => void): void {\n    const filter = { key: key };\n    this.getCollection((err, collection) => {\n      if (err) return callback(err, null);\n      collection.findOne(filter, (err, item) => callback(err, item));\n    });\n  }\n}\n\n// Usage example (requires configured component context)\n// persistence.setReferences(references);\n// persistence.open(null, (err) => {\n//   persistence.create(null, { id: '1', key: 'foo', value: 123 }, (err, item) => console.log(item));\n// });","lang":"typescript","description":"Demonstrates creating a custom MongoDB persistence class extending IdentifiableMongoDbPersistence with filtering and custom methods."},"warnings":[{"fix":"Use promisify from utils or wrap calls in new Promise. Consider using MongoDbPersistence which returns promises in newer versions.","message":"Base class methods use callbacks, not Promises. Async/await may require wrapping.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide callbacks to base methods even if you ignore errors.","message":"IdentifiableMongoDbPersistence expects callback parameters; some derived classes may not pass them correctly.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Override ensureIndex() method or call it after open() callback.","message":"Index creation in constructor may fail if called before database is open. ensureIndex must be called after connection is established.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update to work with mongodb driver 4.x, which uses new types (e.g., Collection, Db).","message":"Switched from MongoDB driver v3 to v4 in version 1.0.0, breaking some internal type expectations.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"}],"env_vars":null,"search_vec":"'1.1.3':19 'abstract':28 'base':29 'build':44 'built':68 'built-in':67 'class':30 'compon':3,9 'configur':61 'connect':36 'crud':34 'current':15 'cycl':51 'differenti':56 'ecosystem':25 'es2017':47 'factori':41 'filter':70 'identifiablemongodbpersist':32 'index':73 'javascript':75 'layer':63 'librari':79 'like':31 'manag':37 'microservic':13,65,77 'mongodb':2,7,78 'mongodbconnect':39 'node.js':5 'nodex':24 'offer':27 'oper':35 'page':71 'part':20 'pattern':42 'persist':8,45,62 'pip.services':1,12,23,54,76 'provid':6,58 'releas':50 'stabl':16 'standard':60 'support':46,74 'tie':52 'toolkit':14 'typescript':49,80 'updat':55 'version':17 'via':38","created_at":"2026-06-07T12:56:41.356639+00:00","updated_at":"2026-06-07T12:56:41.356639+00:00","problems":[{"fix":"Always use getCollection callback pattern: this.getCollection((err, collection) => { if (err) return; ... })","cause":"getCollection() returns null or error not handled before using collection","error":"TypeError: collection.findOne is not a function"},{"fix":"npm install pip-services3-commons-nodex","cause":"Missing runtime dependency","error":"Error: Cannot find module 'pip-services3-commons-nodex'"},{"fix":"Check for null before using result: const key = filter.getAsNullableString('key') ?? '';","cause":"FilterParams methods return null for missing keys, not empty string","error":"TypeError: (intermediate value).(...) is not iterable"}],"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":"https://github.com/pip-services3-nodex/pip-services3-mongodb-nodex#readme","github":"ssh://git@github.com/pip-services3-nodex/pip-services3-mongodb-nodex","docs":null,"changelog":null,"pypi":null,"npm":"pip-services3-mongodb-nodex","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}}