uuid-mongodb

library2.6.0jsnpmunverified

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.

database

npm install uuid-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UUID-MONGODB

uuid-mongodb

databasejavascriptv2.6.0

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.

MUUID

✓ import MUUID from 'uuid-mongodb'

✗ const MUUID = require('uuid-mongodb')

ESM default import; also CommonJS require works in Node

MUUID

✓ import MUUID from 'uuid-mongodb'; MUUID.v1()

✗ import { v1 } from 'uuid-mongodb'

v1 is a method on the default export, not a named export

mode

✓ import MUUID from 'uuid-mongodb'; MUUID.mode('relaxed')

✗ import { mode } from 'uuid-mongodb'

mode is a static method on the default export

Connects to MongoDB, inserts a binary UUID document, retrieves it, and prints the UUID string.

import MUUID from 'uuid-mongodb'; import { MongoClient } from 'mongodb'; const uri = process.env.MONGO_URI || 'mongodb://localhost:27017'; const client = new MongoClient(uri); async function main() { await client.connect(); const db = client.db('test'); const collection = db.collection('uuids'); const uuid = MUUID.v1(); await collection.insertOne({ _id: uuid, name: 'example' }); const doc = await collection.findOne({ _id: uuid }); console.log('Found:', MUUID.from(doc._id).toString()); await client.close(); } main().catch(console.error);

Debug

Known issues

gotcha`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.

fix

Always ensure Binary is of SUBTYPE_UUID (0x04). Use `MUUID.from(binary)` only for Binary with subtype UUID.

affects: *

gotchaThe global mode setting affects `JSON.stringify()` behavior, which can lead to subtle bugs if different parts of the application set different modes.

fix

Avoid changing mode after initialization, or use a single consistent mode throughout the app.

affects: >=1.0.0

deprecated`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.

fix

Consider using `v4()` for non-predictable UUIDs if privacy is a concern.

affects: *

Errors

Common errors & fixes

TypeError: MUUID.from is not a function

Importing named exports instead of default export.

fix

Use `import MUUID from 'uuid-mongodb'` (default import) instead of `import { from } from 'uuid-mongodb'`.

Error: Cannot find module 'uuid'

The required peer dependency 'uuid' is not installed.

fix

Run `npm install uuid` to install the missing dependency.

TypeError: buffer is not a valid Binary

Passing a plain Buffer or ArrayBuffer to `MUUID.from()` when it expects a BSON Binary object.

fix

Use `new Binary(buffer, Binary.SUBTYPE_UUID)` before passing to `MUUID.from()`.

MongoError: unknown type for _id: binary

UUID mode mismatch when using Mongoose schema with 'object' type for _id.

fix

Ensure Mongoose schema field type is set to 'object' with value: { type: 'Buffer' } as shown in the documentation.

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

uuidrequiredcore UUID generation (v1 and v4)

bsonrequiredfor BSON Binary type handling

Agent activity

24 hits · last 30 days

node