Mongoose User History Plugin

The Mongoose User History Plugin is designed to provide an extensive and detailed log of all modifications made to documents within a MongoDB collection managed by Mongoose.

This functionality is crucial for applications that require an audit trail or version control of document changes over time. By capturing a comprehensive history of each document's evolution, the plugin facilitates better data management, accountability, and traceability.

Getting Started

Installation

1yarn add mongoose-user-history-plugin

or

1npm install mongoose-user-history-plugin

Alternatively, you can manually add it to your project's package.json.

Usage

To begin tracking changes on your collections, simply integrate the mongoose-history plugin into your schema:

1import mongooseHistory from 'mongoose-user-history-plugin';
2import mongoose, { Schema } from 'mongoose';
3
4var PostSchema = new Schema({
5  title: String,
6  message: String,
7});
8
9PostSchema.plugin(mongooseHistory);

This integration automatically logs all changes made to the schema.

Tracking User Modifications

To track the user responsible for changes, first, establish a context in any middleware:

For NestJS:

1// /src/main.ts
2import contextService from 'request-context';
3
4// Creating a NestJS application instance
5const app = await NestFactory.create(AppModule);
6app.use(contextService.middleware('request'));
7
8// In user.guard.ts or a similar guard
9import contextService from 'request-context';
10
11@Injectable()
12export class AuthGuard implements CanActivate {
13  async canActivate(context: ExecutionContext): Promise<boolean> {
14    const request = context.switchToHttp().getRequest();
15    // Assuming you get the user information here
16    contextService.set('request:userInfo', user._id);
17  }
18}

For Express:

1import contextService from 'request-context';
2
3// wrap requests in the 'request' namespace
4app.use(contextService.middleware('request'));
5
6// set some object from the request object on the context
7// to automatically save it when a document changes
8app.use(function (req, res, next) {
9  contextService.setContext('request:userInfo', req.user._id);
10  next();
11});

Configure the modifiedBy field in your schema to reflect the user making the change. This can be a direct reference or an entire user object:

1import mongoose, { Types } from 'mongoose';
2
3PostSchema.plugin(mongooseHistory, {
4  modifiedBy: {
5    schemaType: Types.ObjectId, // Can be String, ObjectId, etc.
6    contextPath: 'request:userInfo',
7  },
8});

Storing Additional Metadata

To include extra data, utilize the metadata option. It accepts an array of objects with key and value parameters. The schema parameter (default {type: mongoose.Schema.Types.Mixed}) can also be specified for mongoose schema options. The value can be a string (extracted from the updated document) or a (sync/async) function:

1import mongoose, { Types } from 'mongoose';
2
3PostSchema.plugin(mongooseHistory, {
4  metadata: [
5    { key: 'title', value: 'title' },
6    {
7      key: 'titleFunc',
8      value: function (original, newObject) {
9        return newObject.title;
10      },
11    },
12    {
13      key: 'titleAsync',
14      value: function (original, newObject, cb) {
15        cb(null, newObject.title);
16      },
17    },
18  ],
19});

Indexes for Enhanced Query Performance

Define indexes to enhance query performance in the history collection:

1PostSchema.plugin(mongooseHistory, {
2  indexes: [{ collectionName: 1, action: 1, documentId: 1, modifiedBy: 1 }],
3});

History Record Format

The plugin automatically stores history records for each operation performed on the documents within your collections. The format of these history records is determined by the plugin's configuration and the type of operation (create, update, delete). Below is an explanation of how history records are stored, using default settings:

• Create Operation: When a new document is created, a history record is generated capturing the initial state of the document. The action field is set to "created" and the currentDocument field contains the snapshot of the document at the time of creation.
• Update Operation: Updates to a document result in a history record that includes both the previous (oldDocument) and updated (currentDocument) states of the document. The changes field details the modifications made, providing a before-and-after comparison.
• Delete Operation: Deletion of a document leads to a history record with the action field set to "deleted". The oldDocument field stores the last known state of the document before it was removed.

Here's an example of what history records might look like for different operations:

Each history record includes a timestamp (createdAt) indicating when the change was made. Depending on the plugin options used, additional information such as the user who made the change (modifiedBy) and any extra metadata can also be stored.

By default, history records are stored in a collection named 'History', but this can be customized via the plugin's configuration options.

Use Cases

• Audit Logs: For applications that need to maintain a record of who changed what and when, the plugin provides a straightforward solution for generating audit logs.
• Version Control: In scenarios where it's important to revert documents to previous states or view their evolution over time, the plugin's detailed history records can serve as a version control system.
• Regulatory Compliance: For businesses subject to regulatory requirements around data management and change logging, the plugin helps in maintaining compliance by ensuring that all document modifications are recorded and attributable to specific users.
• Collaborative Editing: In applications where documents are collaboratively edited by multiple users, the plugin enables tracking of individual contributions and changes, simplifying the process of reviewing and managing edits.

Key Features

• Document Change Tracking: Every time a document is updated, created, or deleted, the plugin records the changes in a separate history collection. This includes modifications to document fields, addition or removal of fields, and changes to nested objects within the document.
• User Attribution: In addition to tracking changes, the plugin can also store information about the user responsible for each modification. This is particularly useful for applications with multiple users or editors, where understanding who made specific changes is critical for accountability and auditing purposes.
• Customizable History Storage: The plugin allows for customization of how and where the history data is stored. Developers can specify the structure of the history records, including which fields are recorded and how user information is captured. This flexibility ensures that the history data can be tailored to meet the specific needs of the application.
• Seamless Integration: Designed to work seamlessly with Mongoose, the plugin can be easily added to existing schemas with minimal configuration. Once integrated, it operates in the background, automatically capturing document changes without requiring additional code for each CRUD operation.
• Support for Complex Documents: The plugin is capable of handling complex documents, including those with nested objects and arrays. It intelligently tracks changes at all levels of the document structure, ensuring that even granular modifications are captured accurately.

LICENSE

This project is licensed under the BSD 3-Clause "New" or "Revised" License. See the LICENSE file for more details.