mutent-mongodb

library1.0.0jsnpmunverified

MongoDB adapter for Mutent, an entity management library. Version 1.0.0 is the latest stable release, with ongoing active development. It integrates with MongoDB driver v6+ and Mutent v6+. Key differentiators include built-in lost update/delete protection and bulk update optimization. It supports both ESM and CommonJS modules, and ships TypeScript declarations. The adapter wraps core MongoDB operations (find, insert, replace, update, delete) and exposes mutent-specific errors for lost modifications.

database

npm install mutent-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MUTENT-MONGODB

mutent-mongodb

databasejavascriptv1.0.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.

MongoAdapter

✓ import { MongoAdapter } from 'mutent-mongodb'

✗ const MongoAdapter = require('mutent-mongodb').MongoAdapter

ESM import preferred; default export is not available, only named export.

MONGODB_LOST_UPDATE

✓ import { MONGODB_LOST_UPDATE } from 'mutent-mongodb'

✗ import { MongodbLostUpdate } from 'mutent-mongodb'

Error code is exported as a constant string; check the MutentError codes for handling.

MONGODB_LOST_DELETE

✓ import { MONGODB_LOST_DELETE } from 'mutent-mongodb'

✗ require('mutent-mongodb').MONGODB_LOST_DELETE

Named import works in both ESM and CJS, but CJS require is also valid.

MONGODB_LOST_UPDATES

✓ import { MONGODB_LOST_UPDATES } from 'mutent-mongodb'

Error code for bulk write lost updates.

Connects to MongoDB, creates a mutent adapter, and performs basic create and update operations.

import { MongoClient } from 'mongodb'; import { MongoAdapter } from 'mutent-mongodb'; import { createMutent } from 'mutent'; const client = new MongoClient(process.env.MONGO_URL ?? 'mongodb://localhost:27017'); await client.connect(); const db = client.db('test'); const adapter = new MongoAdapter({ db, collectionName: 'users' }); const mutent = createMutent(adapter); // Create an entity const entity = mutent.create({ name: 'Alice', age: 30 }); await entity.save(); console.log('Saved entity id:', entity.get('_id')); // Find and update const found = await mutent.findOne({ name: 'Alice' }); if (found) { found.set('age', 31); await found.save(); } await client.close();

Debug

Known issues

breakingRequires mongodb driver >=6.0.0 and mutent ^6.0.1 — incompatible with older versions.

fix

Upgrade mongodb and mutent to required peer versions.

affects: <1.0.0

gotchaLost update/delete detection is ON by default; operations will throw MutentError if a document was modified/deleted externally.

fix

Set allowLostUpdates or allowLostDeletes to true to silently orphan entities instead of throwing.

affects: >=0.0.0

deprecatedThe `diffDocuments` option is currently undocumented in behavior; may be deprecated in future releases.

fix

Avoid using diffDocuments until clarification; use default behavior.

affects: >=1.0.0

gotchaThe adapter only works with Mutent's entity model; raw MongoDB operations (e.g., insertOne) are not directly exposed, but accessible via adapter.raw.

fix

Use adapter.raw property to access the underlying Collection for unsupported operations.

affects: >=0.0.0

gotchaBulk update optimization happens automatically; ensure your operations are compatible with bulkWrite (e.g., avoid dynamic collection switching).

fix

No fix needed, but be aware of bulkWrite behavior when mixing operations.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mutent-mongodb'

Package not installed or not in node_modules.

fix

Run: npm install mutent-mongodb

TypeError: (intermediate value) is not iterable

Using mutent-mongodb with an incompatible older version of mutent.

fix

Upgrade mutent to ^6.0.1 and mongodb to >=6.0.0

MutentError: MONGODB_LOST_UPDATE

A document was updated externally between read and save. Lost update protection triggered.

fix

Set allowLostUpdates: true in MongoAdapter options to suppress and orphan the entity, or reconcile manually.

TypeError: client.connect is not a function

Using mongodb v5 or lower with mutent-mongodb v1 which requires mongodb v6+.

fix

Upgrade mongodb to v6+: npm install mongodb@6

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

mongodbrequiredMongoDB driver peer dependency; version >=6.0.0 required

mutentrequiredMutent peer dependency; version ^6.0.1 required

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/greguz/mutent-mongodb ↗

packagemutent-mongodb ↗

homepagehttps://github.com/greguz/mutent-mongodb#readme ↗