rfc6902-mongodb

library2.0.0jsnpmunverified

A Node.js library (v2.0.0, 2024) that converts RFC 6902 JSON Patch operations into a sequence of MongoDB update operations. It builds on rfc6902 and the standard mongodb driver, producing commands suitable for collection.updateOne(). Differs from similar tools by explicitly not supporting full-document replacement, array root targets, or empty keys; it also coalesces operations when safe but errs on correctness. Requires Node >=20 and is ESM-only. Low monthly downloads; niche utility for developers applying JSON Patches to MongoDB documents.

database

npm install rfc6902-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RFC6902-MONGODB

rfc6902-mongodb

databasejavascriptv2.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.

updatesForPatch

✓ import { updatesForPatch } from 'rfc6902-mongodb'

✗ const updatesForPatch = require('rfc6902-mongodb')

ESM-only since v2; CommonJS require() will fail on Node >=20. Use dynamic import() if needed.

default import (nonexistent)

✓ import { updatesForPatch } from 'rfc6902-mongodb'

✗ import updatesForPatch from 'rfc6902-mongodb'

This package only exports the named function `updatesForPatch`. There is no default export.

type imports

✓ import { updatesForPatch } from 'rfc6902-mongodb'

✗ import type { updatesForPatch } from 'rfc6902-mongodb'

The package does not export TypeScript types; import is runtime-only. Use `import` not `import type`.

Connects to MongoDB, inserts a document, applies a JSON Patch via updatesForPatch() using async iteration, and performs each MongoDB update in order.

import { MongoClient } from 'mongodb'; import { updatesForPatch } from 'rfc6902-mongodb'; const client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017'); await client.connect(); const collection = client.db('test').collection('samples'); const originalDocument = { biscuits: [{ name: 'Digestive' }, { name: 'Choco Leibniz' }] }; const insertResult = await collection.insertOne(originalDocument); const fetchedDoc = await collection.findOne({ _id: insertResult.insertedId }); const patch = [ { op: 'add', path: '/biscuits/1', value: { name: 'Ginger Nut' } }, { op: 'copy', from: '/biscuits/0', path: '/best_biscuit' }, { op: 'remove', path: '/biscuits' } ]; const updates = updatesForPatch(patch, fetchedDoc); for await (const update of updates) { await collection.updateOne({ _id: insertResult.insertedId }, update); } await client.close();

Debug

Known issues

breakingPackage is ESM-only since v2 (2024). CommonJS require() will throw ERR_REQUIRE_ESM.

fix

Use import statement or dynamic import(). Ensure package.json has 'type': 'module' if needed.

affects: >=2.0

breakingDropped support for Node <20 in v2.0.0.

fix

Upgrade Node.js to v20 or newer.

affects: >=2.0

deprecatedThe package does not support replaceOne operations. Patches that replace the entire root document (empty path) throw an Error.

fix

Avoid patches with {'path': ''} for replace operations; instead use MongoDB replaceOne directly.

affects: *

gotchaThe original document passed to updatesForPatch must exactly match the MongoDB document at the time of patch generation. Any divergence leads to incorrect updates.

fix

Fetch the document immediately before calling updatesForPatch; consider using transactions or optimistic locking.

affects: *

gotchaPatch operations that contain '$', '.', or null characters in paths or values will throw an Error because MongoDB does not support them.

fix

Validate or sanitize patch paths and values to avoid these characters before calling updatesForPatch.

affects: *

gotchaArray indexes in paths assume the MongoDB document's array state is known; concurrent modifications can cause off-by-one errors.

fix

Use the library in a controlled environment or apply updates sequentially on a single connection.

affects: *

Errors

Common errors & fixes

TypeError: updatesForPatch is not a function

Using CommonJS require() on v2 which is ESM-only.

fix

Change to 'import { updatesForPatch } from 'rfc6902-mongodb';' or use dynamic import: 'const { updatesForPatch } = await import('rfc6902-mongodb');'

SyntaxError: The requested module 'rfc6902-mongodb' does not provide an export named 'default'

Trying to default-import from a package that only exports named exports.

fix

Use named import: import { updatesForPatch } from 'rfc6902-mongodb';

Error: Unsupported operation: path must target an object, not an array or primitive

Patch operation path '/' (root) given, but root document is not an object (e.g., array or string).

fix

Ensure the MongoDB document at the root is an object (nested arrays are fine). Pass an object document to updatesForPatch.

Error: Unsupported operation: cannot replace the entire document

A patch operation with path '' (empty string) attempts to replace the entire document.

fix

Use MongoDB's replaceOne() instead of updatesForPatch for full-document replacement. Remove such patch operations.

Error: Invalid MongoDB path: keys cannot contain '$', '.', or null characters

One of the patch paths or values includes prohibited characters for MongoDB field names.

fix

Remove or escape '$', '.', '\0' from paths/values before creating the patch. For example, use '\$' as a literal if needed.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

rfc6902requiredCore dependency for applying JSON Patch operations; this library generates MongoDB update operations from the patching logic.

mongodboptionalPeer dependency; the library produces update documents expected by the official MongoDB driver. Not bundled.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mrcranky/rfc6902-mongodb ↗

packagerfc6902-mongodb ↗

homepagehttps://github.com/mrcranky/rfc6902-mongodb#readme ↗