{"id":43508,"library":"oors-mongodb","title":"oors MongoDB","description":"oors-mongodb (v4.29.0) is a module for the oors framework that provides MongoDB integration via Store (thin collection wrapper) and Repository (feature-rich CRUD with validation, relations, and aggregation). It supports seeding, data migration, and built-in GraphQL CRUD akin to Prisma. It uses the official MongoDB Node.js driver (v4+) and is published on npm. Release cadence is tied to the oors monorepo, with monthly patch releases. Differentiators: JSON schema validation, relation-based $lookup joins, and out-of-the-box GraphQL schema generation.","status":"active","version":"4.29.0","language":"javascript","source_language":"en","source_url":"https://github.com/viczam/oors/tree/master/packages/oors-mongodb","tags":["javascript"],"install":[{"cmd":"npm install oors-mongodb","lang":"bash","label":"npm"},{"cmd":"yarn add oors-mongodb","lang":"bash","label":"yarn"},{"cmd":"pnpm add oors-mongodb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Official MongoDB driver (peer dependency, v4.x) for database operations.","package":"mongodb","optional":false},{"reason":"Optional peer for GraphQL CRUD integration.","package":"oors-graphql","optional":true}],"imports":[{"note":"Store is a named export, not default. ESM-only, no CJS support.","wrong":"import Store from 'oors-mongodb'","symbol":"Store","correct":"import { Store } from 'oors-mongodb'"},{"note":"Package is ESM-only (type: 'module') since v4. CJS require will fail.","wrong":"const Repository = require('oors-mongodb').Repository","symbol":"Repository","correct":"import { Repository } from 'oors-mongodb'"},{"note":"Seeder is exported from a subpath 'oors-mongodb/seeder' since v4.20.","wrong":"import { Seeder } from 'oors-mongodb'","symbol":"Seeder","correct":"import { Seeder } from 'oors-mongodb/seeder'"}],"quickstart":{"code":"import { Repository } from 'oors-mongodb';\nimport { MongoClient } from 'mongodb';\n\nconst client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017');\nawait client.connect();\nconst db = client.db('test');\n\n// Define a repository with JSON schema validation\nconst usersRepo = new Repository({\n  name: 'users',\n  db,\n  schema: {\n    type: 'object',\n    properties: {\n      name: { type: 'string' },\n      email: { type: 'string', format: 'email' }\n    },\n    required: ['name', 'email']\n  }\n});\n\n// Insert a document\nconst user = await usersRepo.create({ name: 'Alice', email: 'alice@example.com' });\nconsole.log('Created user:', user);\n\n// Find with filter\nconst found = await usersRepo.find({ email: 'alice@example.com' });\nconsole.log('Found:', found);\n\nawait client.close();","lang":"typescript","description":"Connects to MongoDB, defines a Repository with JSON schema, inserts and queries a document."},"warnings":[{"fix":"Use import syntax or ensure your project is configured for ESM.","message":"v4 moved from CJS to ESM. require() calls will fail.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Import Seeder from 'oors-mongodb/seeder'.","message":"Subpath exports like 'oors-mongodb/seeder' were introduced in v4.20. Direct import from main package may be undefined.","severity":"breaking","affected_versions":">=4.20.0"},{"fix":"Migrate to the standalone 'oors-graphql-mongodb' package.","message":"The 'graphql' integration is deprecated in favor of a separate plugin since v4.25.","severity":"deprecated","affected_versions":">=4.25.0"},{"fix":"Ensure you handle missing _id in your application logic.","message":"Repository.create() does not auto-generate _id unless explicitly provided. It uses MongoDB default ObjectId generation.","severity":"gotcha","affected_versions":"*"},{"fix":"Use Repository for validated operations; use Store for raw MongoDB driver access.","message":"Schema validation is only applied on repository methods (create, update), not on raw collection access via store.","severity":"gotcha","affected_versions":"*"},{"fix":"Upgrade your MongoDB driver to v4.x.","message":"MongoDB driver peer dependency changed from v3 to v4 in oors-mongodb v4.0.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'aggreg':33 'akin':45 'base':79 'box':87 'built':41 'built-in':40 'cadenc':62 'collect':21 'crud':28,44 'data':37 'differenti':73 'driver':54 'featur':26 'feature-rich':25 'framework':13 'generat':90 'graphql':43,88 'integr':17 'javascript':91 'join':81 'json':74 'lookup':80 'migrat':38 'modul':9 'mongodb':2,5,16,52 'monorepo':68 'month':70 'node.js':53 'npm':60 'offici':51 'oor':1,4,12,67 'oors-mongodb':3 'out-of-the-box':83 'patch':71 'prisma':47 'provid':15 'publish':58 'relat':31,78 'relation-bas':77 'releas':61,72 'repositori':24 'rich':27 'schema':75,89 'seed':36 'store':19 'support':35 'thin':20 'tie':64 'use':49 'v4':55 'v4.29.0':6 'valid':30,76 'via':18 'wrapper':22","created_at":"2026-06-05T17:00:08.509384+00:00","updated_at":"2026-06-05T17:00:08.509384+00:00","problems":[{"fix":"Use import syntax instead of require. If you must use require, use dynamic import or set NODE_OPTIONS='--experimental-vm-modules'.","cause":"Importing a class from an ESM package using require() without proper interop.","error":"TypeError: Class extends value #<Object> is not a constructor or null"},{"fix":"Change import to: import { Seeder } from 'oors-mongodb/seeder';","cause":"Importing Seeder from the main package path instead of the subpath export.","error":"Cannot find module 'oors-mongodb/seeder' or its corresponding type declarations."},{"fix":"Check the MONGO_URI and ensure the user has readWrite on the target database.","cause":"MongoDB connection URI does not have proper authentication or user lacks permissions.","error":"MongoError: (Unauthorized) not authorized on admin to execute command"}],"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/viczam/oors#readme","github":"https://github.com/viczam/oors/tree/master/packages/oors-mongodb","docs":null,"changelog":null,"pypi":null,"npm":"oors-mongodb","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-05","next_check":"2026-09-03","install_tag":null}}