{"id":44097,"library":"uuid-mongodb","title":"uuid-mongodb","description":"uuid-mongodb (v2.6.0) generates and parses BSON UUIDs for MongoDB, providing better performance than string UUIDs. It supports UUID v1 and v4, offers canonical and relaxed JSON serialization modes, and plays nicely with the native MongoDB driver and Mongoose. TypeScript types are included. The library uses the `uuid` package internally and focuses on binary UUIDs (SUBTYPE_UUID) for efficient storage and querying. Release cadence is irregular. Key differentiators: simple API, mode switching for JSON output, and direct integration with MongoDB's Binary type.","status":"active","version":"2.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/cdimascio/uuid-mongodb","tags":["javascript","uuid","mongodb","typescript"],"install":[{"cmd":"npm install uuid-mongodb","lang":"bash","label":"npm"},{"cmd":"yarn add uuid-mongodb","lang":"bash","label":"yarn"},{"cmd":"pnpm add uuid-mongodb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"core UUID generation (v1 and v4)","package":"uuid","optional":false},{"reason":"for BSON Binary type handling","package":"bson","optional":false}],"imports":[{"note":"ESM default import; also CommonJS require works in Node","wrong":"const MUUID = require('uuid-mongodb')","symbol":"MUUID","correct":"import MUUID from 'uuid-mongodb'"},{"note":"v1 is a method on the default export, not a named export","wrong":"import { v1 } from 'uuid-mongodb'","symbol":"MUUID","correct":"import MUUID from 'uuid-mongodb'; MUUID.v1()"},{"note":"mode is a static method on the default export","wrong":"import { mode } from 'uuid-mongodb'","symbol":"mode","correct":"import MUUID from 'uuid-mongodb'; MUUID.mode('relaxed')"}],"quickstart":{"code":"import MUUID from 'uuid-mongodb';\nimport { MongoClient } from 'mongodb';\n\nconst uri = process.env.MONGO_URI || 'mongodb://localhost:27017';\nconst client = new MongoClient(uri);\n\nasync function main() {\n  await client.connect();\n  const db = client.db('test');\n  const collection = db.collection('uuids');\n  \n  const uuid = MUUID.v1();\n  await collection.insertOne({ _id: uuid, name: 'example' });\n  \n  const doc = await collection.findOne({ _id: uuid });\n  console.log('Found:', MUUID.from(doc._id).toString());\n  \n  await client.close();\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Connects to MongoDB, inserts a binary UUID document, retrieves it, and prints the UUID string."},"warnings":[{"fix":"Always ensure Binary is of SUBTYPE_UUID (0x04). Use `MUUID.from(binary)` only for Binary with subtype UUID.","message":"`MUUID.from()` accepts both a string and a MongoDB Binary. When passing a Buffer or Binary that is not SUBTYPE_UUID, it may throw or produce unexpected results.","severity":"gotcha","affected_versions":"*"},{"fix":"Avoid changing mode after initialization, or use a single consistent mode throughout the app.","message":"The global mode setting affects `JSON.stringify()` behavior, which can lead to subtle bugs if different parts of the application set different modes.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider using `v4()` for non-predictable UUIDs if privacy is a concern.","message":"`MUUID.v1()` uses the `uuid` package's v1 which generates time-based UUIDs with clock sequence; these can be traced to MAC address in some environments.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"search_vec":"'api':74 'better':16 'binari':58,86 'bson':11 'cadenc':68 'canon':28 'differenti':72 'direct':81 'driver':41 'effici':63 'focus':56 'generat':8 'includ':47 'integr':82 'intern':54 'irregular':70 'javascript':88 'json':31,78 'key':71 'librari':49 'mode':33,75 'mongodb':3,6,14,40,84,90 'mongoos':43 'nativ':39 'nice':36 'offer':27 'output':79 'packag':53 'pars':10 'perform':17 'play':35 'provid':15 'queri':66 'relax':30 'releas':67 'serial':32 'simpl':73 'storag':64 'string':19 'subtyp':60 'support':22 'switch':76 'type':45,87 'typescript':44,91 'use':50 'uuid':2,5,12,20,23,52,59,61,89 'uuid-mongodb':1,4 'v1':24 'v2.6.0':7 'v4':26","created_at":"2026-06-05T17:02:58.181544+00:00","updated_at":"2026-06-05T17:02:58.181544+00:00","problems":[{"fix":"Use `import MUUID from 'uuid-mongodb'` (default import) instead of `import { from } from 'uuid-mongodb'`.","cause":"Importing named exports instead of default export.","error":"TypeError: MUUID.from is not a function"},{"fix":"Run `npm install uuid` to install the missing dependency.","cause":"The required peer dependency 'uuid' is not installed.","error":"Error: Cannot find module 'uuid'"},{"fix":"Use `new Binary(buffer, Binary.SUBTYPE_UUID)` before passing to `MUUID.from()`.","cause":"Passing a plain Buffer or ArrayBuffer to `MUUID.from()` when it expects a BSON Binary object.","error":"TypeError: buffer is not a valid Binary"},{"fix":"Ensure Mongoose schema field type is set to 'object' with value: { type: 'Buffer' } as shown in the documentation.","cause":"UUID mode mismatch when using Mongoose schema with 'object' type for _id.","error":"MongoError: unknown type for _id: binary"}],"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/cdimascio/uuid-mongodb#readme","github":"https://github.com/cdimascio/uuid-mongodb","docs":null,"changelog":null,"pypi":null,"npm":"uuid-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}}