feat(document): add $revert() method to undo unsaved changes

[gourabsingha1]

What does this PR do?

Closes #8714

Adds a new public $revert(paths?) method to documents. This method allows discarding any unsaved modifications and restoring the document to its original state (either when it was last loaded from the database or after a successful save).

Why?

Currently, there is no straightforward way to discard unsaved modifications to a document. Users who wanted to undo edits had to manually query the DB again, clone the object, or manually track and reset every property. This is especially useful in failure/retry/transaction rollback logic.

---

API Signature: doc.$revert(paths?)

Parameter	Type	Description
paths (optional)	string | string[]	If specified, only the specified path(s) (and their subpaths) are reverted. If omitted, the entire document is reverted.

Example

const doc = await UserModel.findOne({ name: 'Alice', age: 30 });

// Edit some paths
doc.name = 'Bob';
doc.age = 45;
doc.$isModified('name'); // true

// Revert specific paths:
doc.$revert('name');
doc.name; // 'Alice' (reverted)
doc.age;  // 45 (not reverted)

// Revert all paths:
doc.name = 'Bob';
doc.$revert();
doc.name; // 'Alice' (reverted)
doc.age;  // 30 (reverted)
doc.$isModified(); // false (modified paths cleared)

Implementation Details

1. DB Hydration Snapshot: Inside $__init() (the hydration path), we store a deep clone of the initial _doc onto this.$__._originalDoc.
2. Post-Save Refresh: Inside $__reset() (which runs after a successful save), we refresh the snapshot of _originalDoc using clone(this._doc).
3. $revert() Execution:
   • If paths is omitted: We restore this._doc from the _originalDoc snapshot and clear all modified paths with this.$clearModifiedPaths().
   • If paths is specified: We restore only those specific paths from _originalDoc onto this._doc and unmark those paths as modified.
4. TypeScript Declarations: Added type signature for $revert() in types/document.d.ts.

Tests

Added a new test file test/document.revert.test.js containing 10 passing tests verifying:

• Full document revert
• Specific path revert (accepting both a single string and array of strings)
• Restores original value from DB and unmarks modification tracking
• Refreshing snapshot on save so subsequent reverts undo to the last-saved state
• Non-interference with other documents
• Graceful no-op handling for newly constructed (unsaved) documents
• Reverting nested object paths

[vkarpov15]

Why setValue() rather than simply this._doc = clone(originalDoc)? setValue() doesn't cast values anyway, so this set is redundant.

[gourabsingha1]

you're right. it was unnecessary. I've replaced the entire $revert() body to use this.$set(key, clone(savedState[key])) instead, which additionally runs Mongoose's schema casting/rehydration correctly

[vkarpov15]

I'd strongly prefer this to be a method where you can take a snapshot of the current document and later restore the snapshot. clone() can be expensive on large documents, and init() is one of the most performance sensitive parts of Mongoose.

[gourabsingha1]

gott it! I've removed clone(this._doc) entirely from both $__init() and $__reset(). now it piggybacks on Mongoose's existing $__savedState lazy-capture mechanism. $__init() now just does a single O(1) this.$__.savedState = {} assignment.

the first time a user modifies any path, $__saveInitialState() clones only that top-level path, not the whole document. $revert() restores those lazily-captured values.

[vkarpov15]

I have a few comments here and I did some digging into savedState - on my original review I didn't even remember we had savedState as a property.

TBH, I don't want to turn on savedState for all documents, I worry that will be too much performance overhead for not enough benefit. If you want to store the original state of the document and later revert it, you could do the following:

const docSnapshot = doc.toObject({ getters: false });

// Later
doc.overwrite(docSnapshot);
doc.$clearModifiedPaths();
// `doc` now has the exact same properties as docSnapshot with nothing modified

WDYT about this @gourabsingha1 ?

[vkarpov15]

Cost isn't zero here, creating a new property on $__ and creating a new object is fast but still comes with a cost. The other big tradeoff is that this triggers savedState storage even on newly created documents, which seems incorrect and unnecessary for this PR's stated goal of undoing unsaved changes - $revert() on a new MyModel() would leave current changes. Might be better to move this to init?

[gourabsingha1]

yeah right. moved it

[gourabsingha1]

I have a few comments here and I did some digging into savedState - on my original review I didn't even remember we had savedState as a property.

TBH, I don't want to turn on savedState for all documents, I worry that will be too much performance overhead for not enough benefit. If you want to store the original state of the document and later revert it, you could do the following:

const docSnapshot = doc.toObject({ getters: false });

// Later
doc.overwrite(docSnapshot);
doc.$clearModifiedPaths();
// `doc` now has the exact same properties as docSnapshot with nothing modified

WDYT about this @gourabsingha1 ?

Hey Valeri! Thanks for the suggestion.

While using toObject({ getters: false }) + doc.overwrite() works as a workaround, a native $revert() has a few major advantages:

1. Performance (Eager vs. Lazy): toObject() is eager and copies the entire document tree, which is expensive for larger documents. The lazy savedState approach only captures the specific paths that are modified, which makes the upfront cost practically zero (especially now that it's moved out of the constructor).
2. Avoiding Side-Effects: overwrite() replaces all paths, which forces Mongoose to re-run setters, validation, and default generators on untouched fields. A targeted $revert() only restores the modified paths, avoiding any unintended side-effects on unmodified fields.
3. DX: $revert() is a standard API pattern in state tracking and much cleaner than having developers write three lines of boilerplate for a common query undo task.