ts-patch-mongoose 2.7.0 → 2.8.0

package/src/patch.ts

@@ -3,20 +3,16 @@ import { chunk, isEmpty, isFunction } from 'lodash'
 import omit from 'omit-deep'
 
 import type { HydratedDocument, MongooseError, Types } from 'mongoose'
-
-import type IContext from './interfaces/IContext'
-import type IEvent from './interfaces/IEvent'
-import type IPluginOptions from './interfaces/IPluginOptions'
-import type { Metadata, User } from './interfaces/IPluginOptions'
+import type { Metadata, PatchContext, PatchEvent, PluginOptions, User } from './types'
 
 import em from './em'
-import History from './models/History'
+import { HistoryModel } from './models/History'
 
-function isPatchHistoryEnabled<T>(opts: IPluginOptions<T>, context: IContext<T>): boolean {
+function isPatchHistoryEnabled<T>(opts: PluginOptions<T>, context: PatchContext<T>): boolean {
   return !opts.patchHistoryDisabled && !context.ignorePatchHistory
 }
 
-export function getJsonOmit<T>(opts: IPluginOptions<T>, doc: HydratedDocument<T>): Partial<T> {
+export function getJsonOmit<T>(opts: PluginOptions<T>, doc: HydratedDocument<T>): Partial<T> {
   const object = JSON.parse(JSON.stringify(doc)) as Partial<T>
 
   if (opts.omit) {
@@ -26,7 +22,7 @@ export function getJsonOmit<T>(opts: IPluginOptions<T>, doc: HydratedDocument<T>
   return object
 }
 
-export function getObjectOmit<T>(opts: IPluginOptions<T>, doc: HydratedDocument<T>): Partial<T> {
+export function getObjectOmit<T>(opts: PluginOptions<T>, doc: HydratedDocument<T>): Partial<T> {
   if (opts.omit) {
     return omit(isFunction(doc?.toObject) ? doc.toObject() : doc, opts.omit)
   }
@@ -34,21 +30,21 @@ export function getObjectOmit<T>(opts: IPluginOptions<T>, doc: HydratedDocument<
   return doc
 }
 
-export async function getUser<T>(opts: IPluginOptions<T>): Promise<User | undefined> {
+export async function getUser<T>(opts: PluginOptions<T>): Promise<User | undefined> {
   if (isFunction(opts.getUser)) {
     return await opts.getUser()
   }
   return undefined
 }
 
-export async function getReason<T>(opts: IPluginOptions<T>): Promise<string | undefined> {
+export async function getReason<T>(opts: PluginOptions<T>): Promise<string | undefined> {
   if (isFunction(opts.getReason)) {
     return await opts.getReason()
   }
   return undefined
 }
 
-export async function getMetadata<T>(opts: IPluginOptions<T>): Promise<Metadata | undefined> {
+export async function getMetadata<T>(opts: PluginOptions<T>): Promise<Metadata | undefined> {
   if (isFunction(opts.getMetadata)) {
     return await opts.getMetadata()
   }
@@ -59,19 +55,19 @@ export function getValue<T>(item: PromiseSettledResult<T>): T | undefined {
   return item.status === 'fulfilled' ? item.value : undefined
 }
 
-export async function getData<T>(opts: IPluginOptions<T>): Promise<[User | undefined, string | undefined, Metadata | undefined]> {
+export async function getData<T>(opts: PluginOptions<T>): Promise<[User | undefined, string | undefined, Metadata | undefined]> {
   return Promise.allSettled([getUser(opts), getReason(opts), getMetadata(opts)]).then(([user, reason, metadata]) => {
     return [getValue(user), getValue(reason), getValue(metadata)]
   })
 }
 
-export function emitEvent<T>(context: IContext<T>, event: string | undefined, data: IEvent<T>): void {
+export function emitEvent<T>(context: PatchContext<T>, event: string | undefined, data: PatchEvent<T>): void {
   if (event && !context.ignoreEvent) {
     em.emit(event, data)
   }
 }
 
-export async function bulkPatch<T>(opts: IPluginOptions<T>, context: IContext<T>, eventKey: 'eventCreated' | 'eventDeleted', docsKey: 'createdDocs' | 'deletedDocs'): Promise<void> {
+export async function bulkPatch<T>(opts: PluginOptions<T>, context: PatchContext<T>, eventKey: 'eventCreated' | 'eventDeleted', docsKey: 'createdDocs' | 'deletedDocs'): Promise<void> {
   const history = isPatchHistoryEnabled(opts, context)
   const event = opts[eventKey]
   const docs = context[docsKey]
@@ -108,18 +104,18 @@ export async function bulkPatch<T>(opts: IPluginOptions<T>, context: IContext<T>
     }
 
     if (history && !isEmpty(bulk)) {
-      await History.bulkWrite(bulk, { ordered: false }).catch((error: MongooseError) => {
+      await HistoryModel.bulkWrite(bulk, { ordered: false }).catch((error: MongooseError) => {
         console.error(error.message)
       })
     }
   }
 }
 
-export async function createPatch<T>(opts: IPluginOptions<T>, context: IContext<T>): Promise<void> {
+export async function createPatch<T>(opts: PluginOptions<T>, context: PatchContext<T>): Promise<void> {
   await bulkPatch(opts, context, 'eventCreated', 'createdDocs')
 }
 
-export async function updatePatch<T>(opts: IPluginOptions<T>, context: IContext<T>, current: HydratedDocument<T>, original: HydratedDocument<T>): Promise<void> {
+export async function updatePatch<T>(opts: PluginOptions<T>, context: PatchContext<T>, current: HydratedDocument<T>, original: HydratedDocument<T>): Promise<void> {
   const history = isPatchHistoryEnabled(opts, context)
 
   const currentObject = getJsonOmit(opts, current)
@@ -134,7 +130,7 @@ export async function updatePatch<T>(opts: IPluginOptions<T>, context: IContext<
   if (history) {
     let version = 0
 
-    const lastHistory = await History.findOne({ collectionId: original._id as Types.ObjectId })
+    const lastHistory = await HistoryModel.findOne({ collectionId: original._id as Types.ObjectId })
       .sort('-version')
       .exec()
 
@@ -144,7 +140,7 @@ export async function updatePatch<T>(opts: IPluginOptions<T>, context: IContext<
 
     const [user, reason, metadata] = await getData(opts)
 
-    await History.create({
+    await HistoryModel.create({
       op: context.op,
       modelName: context.modelName,
       collectionName: context.collectionName,
@@ -158,6 +154,6 @@ export async function updatePatch<T>(opts: IPluginOptions<T>, context: IContext<
   }
 }
 
-export async function deletePatch<T>(opts: IPluginOptions<T>, context: IContext<T>): Promise<void> {
+export async function deletePatch<T>(opts: PluginOptions<T>, context: PatchContext<T>): Promise<void> {
   await bulkPatch(opts, context, 'eventDeleted', 'deletedDocs')
 }

package/src/plugin.ts

@@ -10,31 +10,38 @@ import { saveHooksInitialize } from './hooks/save-hooks'
 import { updateHooksInitialize } from './hooks/update-hooks'
 
 import type { HydratedDocument, Model, Schema } from 'mongoose'
-import type IContext from './interfaces/IContext'
-import type IPluginOptions from './interfaces/IPluginOptions'
+import type { PatchContext, PluginOptions } from './types'
 
 const remove = isMongooseLessThan7 ? 'remove' : 'deleteOne'
 
 /**
- * @description Patch patch event emitter
+ * @description Event emitter for patch operations.
  */
 export const patchEventEmitter = em
 
 export { setPatchHistoryTTL } from './helpers'
 
 /**
- * @description Patch history plugin
- * @param {Schema} schema
- * @param {IPluginOptions} opts
+ * @description Mongoose plugin to track and manage patch history for documents.
+ * This plugin initializes hooks for save, update, and delete operations to create
+ * and manage patches.
+ *
+ * @template T
+ * @param {Schema<T>} schema - The Mongoose schema to apply the plugin to.
+ * @param {PluginOptions<T>} opts - Options for configuring the plugin.
  * @returns {void}
  */
-export const patchHistoryPlugin = function plugin<T>(schema: Schema<T>, opts: IPluginOptions<T>): void {
+export const patchHistoryPlugin = function plugin<T>(schema: Schema<T>, opts: PluginOptions<T>): void {
   // Initialize hooks
   saveHooksInitialize(schema, opts)
   updateHooksInitialize(schema, opts)
   deleteHooksInitialize(schema, opts)
 
-  // Corner case for insertMany()
+  /**
+   * @description Corner case for insertMany()
+   * @param {Array<HydratedDocument<T>>} docs - The documents being inserted.
+   * @returns {Promise<void>}
+   */
   schema.post('insertMany', async function (docs) {
     const context = {
       op: 'create',
@@ -49,6 +56,10 @@ export const patchHistoryPlugin = function plugin<T>(schema: Schema<T>, opts: IP
   // In Mongoose 7, doc.deleteOne() returned a promise that resolved to doc.
   // In Mongoose 8, doc.deleteOne() returns a query for easier chaining, as well as consistency with doc.updateOne().
   if (isMongooseLessThan8) {
+    /**
+     * @description Pre-delete hook for Mongoose 7 and below
+     * @returns {Promise<void>}
+     */
     // @ts-expect-error - Mongoose 7 and below
     schema.pre(remove, { document: true, query: false }, async function () {
       // @ts-expect-error - Mongoose 7 and below
@@ -59,12 +70,17 @@ export const patchHistoryPlugin = function plugin<T>(schema: Schema<T>, opts: IP
       }
     })
 
+    /**
+     * @description Post-delete hook for Mongoose 7 and below
+     * @param {HydratedDocument<T>} this - The document being deleted.
+     * @returns {Promise<void>}
+     */
     // @ts-expect-error - Mongoose 7 and below
     schema.post(remove, { document: true, query: false }, async function (this: HydratedDocument<T>) {
       const original = this.toObject(toObjectOptions) as HydratedDocument<T>
       const model = this.constructor as Model<T>
 
-      const context: IContext<T> = {
+      const context: PatchContext<T> = {
         op: 'delete',
         modelName: opts.modelName ?? model.modelName,
         collectionName: opts.collectionName ?? model.collection.collectionName,

package/src/types.ts

@@ -0,0 +1,52 @@
+import type { Operation } from 'fast-json-patch'
+import type { HydratedDocument, Query, Types } from 'mongoose'
+
+export interface History {
+  op: string
+  modelName: string
+  collectionName: string
+  collectionId: Types.ObjectId
+  version: number
+  doc?: object
+  user?: object
+  reason?: string
+  metadata?: object
+  patch?: Operation[]
+}
+
+export interface PatchEvent<T> {
+  oldDoc?: HydratedDocument<T>
+  doc?: HydratedDocument<T>
+  patch?: Operation[]
+}
+
+export interface PatchContext<T> {
+  op: string
+  modelName: string
+  collectionName: string
+  isNew?: boolean
+  createdDocs?: HydratedDocument<T>[]
+  deletedDocs?: HydratedDocument<T>[]
+  ignoreEvent?: boolean
+  ignorePatchHistory?: boolean
+}
+
+export type HookContext<T> = Query<T, T> & { op: string; _context: PatchContext<T> }
+
+export type User = Record<string, unknown>
+
+export type Metadata = Record<string, unknown>
+
+export interface PluginOptions<T> {
+  modelName?: string
+  collectionName?: string
+  eventUpdated?: string
+  eventCreated?: string
+  eventDeleted?: string
+  getUser?: () => Promise<User> | User
+  getReason?: () => Promise<string> | string
+  getMetadata?: () => Promise<Metadata> | Metadata
+  omit?: string[]
+  patchHistoryDisabled?: boolean
+  preDelete?: (docs: HydratedDocument<T>[]) => Promise<void>
+}

package/tests/helpers.test.ts

@@ -1,14 +1,13 @@
 import ms from 'ms'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import History from '../src/models/History'
-
 import { setPatchHistoryTTL } from '../src/helpers'
+import { HistoryModel } from '../src/models/History'
 
 import type { Mock, MockInstance } from 'vitest'
 
 vi.mock('../src/models/History', () => ({
-  default: {
+  HistoryModel: {
     collection: {
       indexes: vi.fn(),
       dropIndex: vi.fn(),
@@ -22,12 +21,12 @@ const name = 'createdAt_1_TTL'
 describe('useTTL', () => {
   let dropIndexSpy: MockInstance
   let createIndexSpy: MockInstance
-  const indexes = History.collection.indexes as Mock
+  const indexes = HistoryModel.collection.indexes as Mock
 
   beforeEach(() => {
     vi.clearAllMocks()
-    dropIndexSpy = vi.spyOn(History.collection, 'dropIndex')
-    createIndexSpy = vi.spyOn(History.collection, 'createIndex')
+    dropIndexSpy = vi.spyOn(HistoryModel.collection, 'dropIndex')
+    createIndexSpy = vi.spyOn(HistoryModel.collection, 'createIndex')
   })
 
   afterEach(() => {

package/tests/patch.test.ts

@@ -1,23 +1,18 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import mongoose, { model } from 'mongoose'
+import mongoose from 'mongoose'
 
 import { bulkPatch, getData, getJsonOmit, getMetadata, getReason, getUser, getValue, updatePatch } from '../src/patch'
 import { patchHistoryPlugin } from '../src/plugin'
 
-import UserSchema from './schemas/UserSchema'
-
 import { USER_DELETED } from './constants/events'
+import { type User, UserSchema } from './schemas/User'
 
 import type { HydratedDocument } from 'mongoose'
-import type IContext from '../src/interfaces/IContext'
-import type { User } from '../src/interfaces/IPluginOptions'
-import type IPluginOptions from '../src/interfaces/IPluginOptions'
-import type IUser from './interfaces/IUser'
 
 import { afterEach } from 'node:test'
-import { update } from 'lodash'
 import em from '../src/em'
+import type { PatchContext, PluginOptions } from '../src/types'
 import server from './mongo/server'
 
 vi.mock('../src/em', () => ({ default: { emit: vi.fn() } }))
@@ -30,7 +25,7 @@ describe('patch tests', () => {
     patchHistoryDisabled: true,
   })
 
-  const User = model('User', UserSchema)
+  const UserModel = mongoose.model<User>('User', UserSchema)
 
   beforeAll(async () => {
     await instance.create()
@@ -51,8 +46,8 @@ describe('patch tests', () => {
 
   describe('getObjects', () => {
     it('should omit properties from currentObject and originalObject based on the opts', async () => {
-      const original = await User.create({ name: 'John', role: 'user' })
-      const current = await User.create({ name: 'John', role: 'admin' })
+      const original = await UserModel.create({ name: 'John', role: 'user' })
+      const current = await UserModel.create({ name: 'John', role: 'admin' })
 
       const pluginOptions = {
         omit: ['createdAt'],
@@ -71,8 +66,8 @@ describe('patch tests', () => {
     })
 
     it('should not omit properties from currentObject and originalObject if opts is empty', async () => {
-      const original = await User.create({ name: 'John', role: 'user' })
-      const current = await User.create({ name: 'John', role: 'admin' })
+      const original = await UserModel.create({ name: 'John', role: 'user' })
+      const current = await UserModel.create({ name: 'John', role: 'admin' })
 
       const pluginOptions = {}
 
@@ -91,14 +86,14 @@ describe('patch tests', () => {
 
   describe('bulkPatch', () => {
     it('should emit eventDeleted if opts.patchHistoryDisabled is false', async () => {
-      const doc = new User({ name: 'John', role: 'user' })
+      const doc = new UserModel({ name: 'John', role: 'user' })
 
-      const pluginOptions: IPluginOptions<IUser> = {
+      const pluginOptions: PluginOptions<User> = {
         eventDeleted: USER_DELETED,
         patchHistoryDisabled: false,
       }
 
-      const context: IContext<IUser> = {
+      const context: PatchContext<User> = {
         op: 'deleteOne',
         modelName: 'User',
         collectionName: 'users',
@@ -110,14 +105,14 @@ describe('patch tests', () => {
     })
 
     it('should emit eventDeleted if opts.patchHistoryDisabled is true', async () => {
-      const doc = new User({ name: 'John', role: 'user' })
+      const doc = new UserModel({ name: 'John', role: 'user' })
 
-      const pluginOptions: IPluginOptions<IUser> = {
+      const pluginOptions: PluginOptions<User> = {
         eventDeleted: USER_DELETED,
         patchHistoryDisabled: true,
       }
 
-      const context: IContext<IUser> = {
+      const context: PatchContext<User> = {
         op: 'deleteOne',
         modelName: 'User',
         collectionName: 'users',
@@ -131,27 +126,27 @@ describe('patch tests', () => {
 
   describe('updatePatch', () => {
     it('should return if one object is empty', async () => {
-      const current = await User.create({ name: 'John', role: 'user' })
+      const current = await UserModel.create({ name: 'John', role: 'user' })
 
-      const pluginOptions: IPluginOptions<IUser> = {
+      const pluginOptions: PluginOptions<User> = {
         eventDeleted: USER_DELETED,
         patchHistoryDisabled: true,
       }
 
-      const context: IContext<IUser> = {
+      const context: PatchContext<User> = {
         op: 'updateOne',
         modelName: 'User',
         collectionName: 'users',
       }
 
-      await updatePatch(pluginOptions, context, current, {} as HydratedDocument<IUser>)
+      await updatePatch(pluginOptions, context, current, {} as HydratedDocument<User>)
       expect(em.emit).toHaveBeenCalled()
     })
   })
 
   describe('should getUser()', () => {
     it('should return user, reason, metadata', async () => {
-      const opts: IPluginOptions<IUser> = {
+      const opts: PluginOptions<User> = {
         getUser: () => ({ name: 'test' }),
         getReason: () => 'test',
         getMetadata: () => ({ test: 'test' }),
@@ -165,7 +160,7 @@ describe('patch tests', () => {
 
   describe('should getData()', () => {
     it('should return user, reason, metadata', async () => {
-      const opts: IPluginOptions<IUser> = {
+      const opts: PluginOptions<User> = {
         getUser: () => ({ name: 'test' }),
         getReason: () => 'test',
         getMetadata: () => ({ test: 'test' }),
@@ -175,7 +170,7 @@ describe('patch tests', () => {
     })
 
     it('should return user, reason, metadata undefined', async () => {
-      const opts: IPluginOptions<IUser> = {
+      const opts: PluginOptions<User> = {
         getUser: () => ({ name: 'test' }),
         getReason: () => 'test',
         getMetadata: () => {