ts-patch-mongoose

Patch history (audit log) & events plugin for mongoose

Motivation

ts-patch-mongoose is a plugin for mongoose
I need to track changes of mongoose models and save them as patch history (audit log) in separate collection. Changes must also emit events that I can subscribe to and react in other parts of my application. I also want to omit some fields from patch history.

Supports and tested with

1{
2  "node": "18.x || 20.x || 22.x",
3  "mongoose": ">=6.6.x || 7.x || 8.x",
4}

Features

• Track changes in mongoose models
• Save changes in a separate collection as a patch history
• Emit events when a model is created, updated or deleted
• Omit fields that you don't want to track in patch history
• Subscribe to one/many types of event
• Use events or patch history or both
• Supports ESM and CommonJS

Installation

• Locally inside your project

1npm install ts-patch-mongoose
2pnpm add ts-patch-mongoose
3yarn add ts-patch-mongoose
4bun add ts-patch-mongoose

• This plugin requires mongoose >=6.6.x || 7.x || 8.x to be installed as a peer dependency

1# For latest mongoose 6
2npm install mongoose@6
3pnpm add mongoose@6
4yarn add mongoose@6
5bun add mongoose@6
6# For latest mongoose 7
7npm install mongoose@7
8pnpm add mongoose@7
9yarn add mongoose@7
10bun add mongoose@7
11# For latest mongoose 8
12npm install mongoose@8
13pnpm add mongoose@8
14yarn add mongoose@8
15bun add mongoose@8

Example

How to use it with express ts-express-tsx

Create your event constants events.ts

1export const BOOK_CREATED = 'book-created'
2export const BOOK_UPDATED = 'book-updated'
3export const BOOK_DELETED = 'book-deleted'

Create your type Book in types.ts

1import type { Types } from 'mongoose'
2
3export type Book = {
4  title: string
5  description?: string
6  authorId: Types.ObjectId
7  createdAt?: Date
8  updatedAt?: Date
9}

Setup your mongoose model Book.ts

1import { Schema, model } from 'mongoose'
2
3import type { HydratedDocument, Types } from 'mongoose'
4import type { Book } from '../types'
5
6import { patchHistoryPlugin, setPatchHistoryTTL } from 'ts-patch-mongoose'
7import { BOOK_CREATED, BOOK_UPDATED, BOOK_DELETED } from '../constants/events'
8
9// You can set patch history TTL in plain english or in milliseconds as you wish.
10// This will determine how long you want to keep patch history.
11// You don't need to use this global config in case you want to keep patch history forever.
12// Execute this method after you connected to you database somewhere in your application.
13setPatchHistoryTTL('1 month')
14
15const BookSchema = new Schema<Book>({
16  name: {
17    title: String,
18    required: true
19  },
20  description: {
21    type: String,
22  },
23  authorId: {
24    type: Types.ObjectId,
25    required: true
26  }
27}, { timestamps: true })
28
29BookSchema.plugin(patchHistoryPlugin, { 
30  // Provide your event constants to plugin
31  eventCreated: BOOK_CREATED,
32  eventUpdated: BOOK_UPDATED,
33  eventDeleted: BOOK_DELETED,
34  
35  // You can omit some properties in case you don't want to save them to patch history
36  omit: ['__v', 'createdAt', 'updatedAt'],
37
38  // Addition options for patchHistoryPlugin plugin
39  // Everything bellow is optional and just shows you what you can do:
40
41  // Code bellow is abstract example, you can use any other way to get user, reason, metadata
42  // These three properties will be added to patch history document automatically and give you flexibility to track who, why and when made changes to your documents
43  getUser: async (doc: HydratedDocument<Book>) => {
44    // For example: get user from http context
45    // You should return an object, in case you want to save user to patch history
46    return httpContext.get('user') as Record<string, unknown>
47  },
48
49  // Reason of document (create/update/delete) like: 'Excel upload', 'Manual update', 'API call', etc.
50  getReason: async (doc: HydratedDocument<Book>) => {
51    // For example: get reason from http context, or any other place of your application
52    // You shout return a string, in case you want to save reason to patch history
53    return httpContext.get('reason') as string
54  },
55
56  // You can provide any information you want to save in along with patch history
57  getMetadata: async (doc: HydratedDocument<Book>) => {
58    // For example: get metadata from http context, or any other place of your application
59    // You should return an object, in case you want to save metadata to patch history
60    return httpContext.get('metadata') as Record<string, unknown>
61  },
62
63  // Do something before deleting documents
64  // This method will be executed before deleting document or documents and always returns a nonempty array of documents
65  preDelete: async (docs) => {
66    const bookIds = docs.map((doc) => doc._id)
67    await SomeOtherModel.deleteMany({ bookId: { $in: bookIds } })
68  },
69
70  // In case you just want to track changes in your models using events below.
71  // And don't want to save changes to patch history collection
72  patchHistoryDisabled: true, 
73})
74
75const Book = model('Book', BookSchema)
76
77export default Book

Subscribe

You can subscribe to events using patchEventEmitter anywhere in your application handlers/BookHandler.ts

1import { patchEventEmitter } from 'ts-patch-mongoose'
2import { BOOK_CREATED, BOOK_UPDATED, BOOK_DELETED } from '../constants/events'
3
4patchEventEmitter.on(BOOK_CREATED, ({ doc }) => {
5  try {
6    console.log('Event - book created', doc)
7    // Do something with doc here
8  } catch (error) {
9    console.error(error)
10  }
11})
12
13patchEventEmitter.on(BOOK_UPDATED, ({ doc, oldDoc, patch }) => {
14  try {
15    console.log('Event - book updated', doc, oldDoc, patch)
16    // Do something with doc, oldDoc and patch here
17  } catch (error) {
18    console.error(error)
19  }
20})
21
22patchEventEmitter.on(BOOK_DELETED, ({ oldDoc }) => {
23  try {
24    console.log('Event - book deleted', oldDoc)
25    // Do something with doc here
26  } catch (error) {
27    console.error(error)
28  }
29})

Check my other projects

• ts-migrate-mongoose - Migration framework for mongoose
• ts-cache-mongoose - Cache plugin for mongoose Queries and Aggregate (in-memory, redis)