Mongoose Archiver Plugin

A Mongoose plugin that archives documents before deletion or updates. This plugin automatically saves a versioned history of modified or deleted documents to a separate collection.

Features

• Archives documents before update or delete operations.
• Saves a versioned history of each document.
• Allows tracking of users who performed the operation.
• Custom Update/Delete Function: Optionally, execute a custom function after each document update/delete, giving you additional flexibility.

Installation

Install the plugin with npm:

npm install mongoose-archiver

Usage

To use the Mongoose Archiver plugin, import it and add it to your schema:

1. Import the plugin and the necessary Mongoose modules:

   import mongooseArchiver from 'mongoose-archiver';
   import { Schema } from 'mongoose';

2. Define your schema and apply the plugin:

   const yourSchema = new Schema({
       name: String,
       updatedBy: { type: Schema.Types.ObjectId, ref: 'User' },
       // Add other fields as needed
   });
   
   // Apply the plugin, optionally specifying a `userField`, `separator` for the collection name like: "users_history" (default is -) and a custom `onUpdate`, `onDelete` function
   yourSchema.plugin(mongooseArchiver, { 
       userField: 'updatedBy',
       separator: '_',
       onUpdate: async (doc) => {
           console.log(`Document with ID ${doc._id} was archived.`);
       },
       onDelete: async (doc) => {
           console.log(`Document with ID ${doc._id} was deleted.`);
       }
   });

3. Create a model and use it in your application:

   const YourModel = mongoose.model('YourModel', yourSchema);
   
   // Example usage
   YourModel.updateOne({ name: 'Example' }, { name: 'Updated Example' }, { user : '5d762323246cd34367f6af8c' })
     .then(() => console.log('Document updated and archived!'))
     .catch(err => console.error(err));
   
   YourModel.deleteOne({ name: 'Example' }, { user : '5d762323246cd34367f6af8c' })
     .then(() => console.log('Document deleted and archived!'))
     .catch(err => console.error(err));

With the plugin applied, every update and delete operation will create a corresponding history document in a separate collection (yourModelName_history). This document will retain the previous version and metadata about the update or deletion. If you pass in the mongoose options the parameter user it will register who update or delete the document.

Options

• userField (optional): Specifies the field in the document to track the user who performed the update or delete action. By default, the plugin will attempt to use this field to store user information in the history record.
• separator (optional): Defines the separator for naming history collections (default: '-').
• onUpdate (optional): A custom function that is executed after archiving a document on an update operation. This function receives the document being updated as a parameter and can perform additional actions if needed.
• onDelete (optional): A custom function that is executed after archiving a document on a delete operation. This function receives the document being deleted as a parameter and can perform additional actions if needed.

How It Works

The plugin performs the following operations:

1. On Update: Before executing an update, it clones the document's current state and saves it as a history record in a separate collection.
2. On Delete: Before deleting a document, it saves the document’s state with deleted.at and deleted.by fields in a history collection.

Each history document includes:

• origin: A reference to the original document.
• version: The version number for tracking document changes.
• archived: Contains the date and user who archived the document.
• deleted: Contains the date and user who deleted the document (only for delete operations).

Code Overview

Core Code

This plugin uses the following methods:

• Update Methods: findOneAndUpdate, updateMany, updateOne
• Delete Methods: deleteOne, deleteMany, findOneAndDelete

The plugin sets up pre hooks for each method, creating a clone of the document in a history collection (yourModelName_history) whenever an update or delete operation is performed.

Types

IOptions Interface

interface IOptions {
    userField?: string;
    separator?: string;
    onUpdate?: (doc: any) => Promise<void> | void; // Custom function executed after update
    onDelete?: (doc: any) => Promise<void> | void; // Custom function executed after delete
}

Defines the optional settings for the plugin, allowing you to specify a field to track the user who performs the operation, and custom functions to execute after each update or delete.

License

MIT