mongoose-version-handler

A Mongoose plugin to manage document versioning and history with JSON Patch diffs, now featuring rollback functionality and full support for NestJS.

---

Installation

Install the plugin via npm:

1npm install mongoose-version-handler

---

Purpose

The mongoose-version-handler plugin allows you to:

1. Track changes made to documents over time.
2. Maintain a version history using JSON Patch format.
3. Retrieve any version of a document easily.
4. Rollback documents to previous versions.
5. Seamlessly integrate with NestJS.

---

Basic Usage

Add the plugin to your schema:

1import { Schema } from 'mongoose';
2import mongooseVersionHandler from 'mongoose-version-handler';
3
4const UserSchema = new Schema({
5    name: {
6        firstname: String,
7        lastname: String,
8    },
9});
10
11// Add versioning plugin
12UserSchema.plugin(mongooseVersionHandler);

The plugin will:

• Add a version field (documentVersion by default) to your schema.
• Maintain a separate history collection storing JSON Patch diffs for each change.
• Automatically increment the version number on each save/update.

---

Metadata in save() Method

You can pass metadata during a document save operation to associate it with the history document.

Example

1const doc = await User.findOne({ ... });
2await doc.save({ metadata: { updatedBy: '6762be74ff14f3257509c4c3' } });

The metadata object will be saved alongside the JSON Patch changes in the history collection.

History Collection Schema (with Metadata)

1const ChangeSet = new mongoose.Schema({
2    parent: mongoose.SchemaTypes.ObjectId, // Source document ID
3    version: Number,                      // Version number
4    patches: [{                           // JSON Patch changes
5        op: String,
6        path: String,
7        value: mongoose.SchemaTypes.Mixed,
8    }],
9    metadata: mongoose.SchemaTypes.Mixed, // Metadata associated with this change
10    date: Date, // Available if 'trackDate' is enabled
11});

---

Options

versionKey

Specifies the version field name added to the schema. Default: documentVersion.

---

collection

Sets the name of the history collection. Default: <original_collection>_h.

---

connection

Passes a specific database connection for version tracking. This is required when using mongoose.createConnection.

Example:

1import mongoose, { Schema } from 'mongoose';
2import mongooseVersionHandler from 'mongoose-version-handler';
3
4const db = mongoose.createConnection('mongodb://localhost/my-database');
5
6const UserSchema = new Schema({
7    name: {
8        first: String,
9        last: String,
10    },
11});
12
13UserSchema.plugin(mongooseVersionHandler, { connection: db });

---

trackDate

Tracks the creation date for each version. Adds a date field to the history collection when enabled.

---

addDateToDocument

Stores the version creation date redundantly in the main document. Requires trackDate: true.

---

versionDateKey

Specifies the name of the date field added to the document when addDateToDocument is enabled. Default: documentVersionDate.

---

Retrieving a Specific Document Version

You can retrieve any version of a document using the getVersion() method:

1const user = await User.findOne({ ... });
2const version2 = await user.getVersion(2);

getVersion() returns a Promise resolving to the document version.

---

Rolling Back a Document

Rollback to a previous version using the rollback() method:

1const user = await User.findOne({ ... });
2await user.rollback();

• If a previous version exists, the document rolls back to that version.
• If no previous version exists, the document will be deleted.

---

Accessing the History Collection

To query the history collection directly, use the getHistoryModel() method:

1const UserHistory = User.getHistoryModel();
2const history = await UserHistory.find({ parent: user._id });

---

NestJS Integration

The plugin includes support for NestJS applications.

Example: Using the Plugin in a NestJS Module

1import { Module } from '@nestjs/common';
2import { MongooseModule, getConnectionToken } from '@nestjs/mongoose';
3import { Connection } from 'mongoose';
4import mongooseVersionHandler from 'mongoose-version-handler';
5
6import { CatSchema, Cat } from './cat.schema';
7import { CatController } from './cat.controller';
8import { CatService } from './cat.service';
9
10@Module({
11    imports: [
12        MongooseModule.forFeatureAsync([
13            {
14                name: Cat.name,
15                inject: [getConnectionToken()],
16                useFactory: (connection: Connection) => {
17                    const schema = CatSchema;
18                    schema.plugin(mongooseVersionHandler, { connection });
19                    return schema;
20                },
21            },
22        ]),
23    ],
24    controllers: [CatController],
25    providers: [CatService],
26})
27export class CatModule {}

---

Key Features Recap

• Automatic Version Tracking: Tracks document changes with JSON Patch diffs.
• Rollback Support: Revert documents to previous versions with ease.
• Customizable Options: Configure version keys, history collections, and connection settings.
• NestJS Ready: Works seamlessly with NestJS and dependency injection.

---

Feel free to explore the plugin, contribute, or report any issues.