@palmetto/nestjs-log-history 0.0.1

package/README.md

@@ -0,0 +1,186 @@
+# @palmetto/nestjs-log-history
+
+Works with @palmetto/mongoose-log-history to create log history audits for changes via the mongoose library.
+
+1. Provides a method to automatically build TrackedFields for your schema
+2. Provides a nestjs `HistoryModule` and `HistoryService` that automatically saves audit histories into a mongodb collection.
+3. Provides a `HistoryDto` to help map audit entities into an API response.
+
+## Installation
+
+```sh
+yarn add @palmetto/nestjs-log-history @palmetto/mongoose-log-history
+```
+
+## Usage for automatic field binding
+
+The `@palmetto/mongoose-log-history` plugin requires that you provide a list of fields to track. This can be tedious for larger schemas.
+You can use the `applyLogHistoryPlugin` or call `getLogHistoryPluginOptions` to manage the options more directly.
+
+- getLogHistoryPluginOptions - reflects on the mongoose Schema to build a list of TrackedFields for the mongoose-log-history to track.
+- applyLogHistoryPlugin
+  - adds the log history to your schema, calling getLogHistoryPluginOptions to build the list of tracked fields.
+  - sets the logger to a `@nestjs/common` Logger instance
+  - sets the logHistorySaver that you can provide later via the `setLogHistorySaver` method.
+
+1. Setup the mongoose schema to support history by adding the mongoose-log-history plugin
+
+   Define your mongo schema and know your mongodb collection name:
+
+   ```ts
+   export const CustomerEntitySchema = z.object({ ... });
+   export const CustomerMongoCollection = "customers";
+   ```
+
+   Build your schema using schemaBuilder:
+
+   ```ts
+   export const CustomerMongooseSchema = schemaBuilder.build(
+     CustomerEntitySchema,
+     {
+       versionKey: false,
+     },
+   );
+   ```
+
+   Define a model definition that can be used by the `MongooseModule.forFeature` call, and for configuring the history plugin:
+
+   ```ts
+   export const CustomerModelDefinition = {
+     name: "Customer",
+     schema: CustomerMongooseSchema,
+     collection: CustomerMongoCollection,
+   };
+   ```
+
+   Apply the plugin to the mongoose schema object:
+
+   ```ts
+   import { applyLogHistoryPlugin } from "@palmetto/nestjs-log-history";
+
+   // assign the mongoose-log-history plugin to the schema and collection
+   applyLogHistoryPlugin({
+     schema: CustomerModelDefinition.schema,
+     collection: CustomerModelDefinition.collection,
+     skipFields: new Set<string>(["status", "address.coordinates"]), // don't track changes to these fields [dot-notation supported for nested schemas]
+     maskedFields: {
+       ssn: "***-**-****", // mask the SSN value with asterisks
+       dob: (dob) =>
+         dob instanceof Date
+           ? dob.toISOString().replace(/\d{4}/, "YYYY").split("T")[0]
+           : "****", // replace year of the date-of-birth with YYYY, if it's isn't a date, just use ****
+     },
+   });
+   ```
+
+   At this point, the mongoose schema is setup to track changes to entities, but still needs a saver method configured.
+   Set the saver method using `setLogHistorySaver`.
+
+   ```ts
+   import { setLogHistorySaver } from "@palmetto/nestjs-log-history";
+
+   async function mySaveHistoriesMethod(
+     plugin: LogHistoryPlugin,
+     histories: LogHistoryEntry[],
+   ) {
+     // transform and store the histories
+   }
+
+   setLogHistorySaver(
+     CustomerModelDefinition.collection,
+     mySaveHistoriesMethod,
+   );
+   ```
+
+### Nestjs module
+
+You can use the `HistoryModule` to provide a fully automatic log history service. This module provides a service that saves the histories to a schema that more closely aligns with Palmetto standards.
+
+You must first apply the plugin to your mongoose schema as shown ealier. Next you can use the HistoryModule to configure the HistoryService for your schema.
+
+1. Configure the HistoryModule in your Module
+
+   ```ts
+   import { HistoryModule } from "@palmetto/nestjs-log-history";
+
+   @Module({
+     imports: [
+       MongooseModule.forFeature([
+         {
+           name: CustomerModelDefinition.name, // name for the mongoose model
+           schema: CustomerModelDefinition.schema, // mongoose schema to use
+           collection: CustomerModelDefinition.collection, // name of the collection to use
+         },
+       ]),
+       HistoryModule.forFeature({
+         schema: CustomerModelDefinition.schema, // provide the same schema here as in the call to MongooseModule
+         collection: CustomerModelDefinition.name, // provide the same collection name here as in the call to MongooseModule
+       }),
+     ],
+     providers: [CustomerService],
+   })
+   export class CustomerModule {}
+   ```
+
+2. Inject the HistoryService into the CustomerService
+
+   Access the HistoryService instance exported from the HistoryModule. The HistoryService extends `BaseMongooseService<LogHistoryEntity>` so you can work with the mongoose collection however you prefer.
+
+   ```ts
+   import {
+     HistoryFindAllOptions,
+     HistoryService,
+   } from "@palmetto/nestjs-log-history";
+
+   @Injectable()
+   export class CustomerService extends MongooseService<
+     CustomerEntity,
+     NewCustomerEntity
+   > {
+     private readonly logger = new Logger(CustomerService.name);
+     private readonly allowedPatchFields: Set<keyof CustomerEntity> = new Set(
+       Object.keys(NewCustomerEntityObject) as Array<keyof CustomerEntity>,
+     );
+
+     constructor(
+       @InjectModel(CustomerModelDefinition.name)
+       model: PaginatedMetaModel<CustomerEntity>,
+       private readonly historyService: HistoryService,
+     ) {
+       super(model);
+       this.logger.debug("CustomerService initialized");
+     }
+
+     /**
+      * Get the history for an entity by _id, the most recent entries are returned first.
+      */
+     async getHistory(
+       id: string | Types.ObjectId,
+       options?: HistoryFindAllOptions,
+     ) {
+       return await this.historyService.findAllById(id, options);
+     }
+   }
+
+   // gets the first page of 20 history records for January 2024 UTC [start <= createdAt < end]
+   const historyPagedResult = await PaginatedListDto.fromPageResult(
+     await service.getHistory(id, {
+       limit: 20,
+       page: 0,
+       start: new Date("2024-01-01T00:00:00Z"),
+       end: new Date("2024-02-01T00:00:00Z"),
+     }),
+     HistoryDto.fromEntity,
+   );
+   ```
+
+3. Dealing with compressed documents
+
+   When using the HistoryService and compressed documents (`{ saveWholeDocs: true, compressDocs: true }`) in the log history, you can use the `HistoryDto.fromEntity` method to transform and decompress the `originalDocument` and `updatedDocument` properties.
+   Or, use the `HistoryDto.tryDecompress` to uncompress the document field.
+
+   ```ts
+   const updatedDocument = HistoryDto.tryDecompress(
+     parsedEntity.updatedDocument,
+   );
+   ```

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+import { MaskedFields } from "@palmetto/mongoose-log-history";
+import { Schema } from "mongoose";
+export interface HistoryConfigBase {
+    /**
+     * The Mongoose schema to which the log history plugin will be applied.
+     */
+    schema: Schema;
+    /**
+     * The name of the MongoDB collection for the model being tracked.
+     */
+    collection: string;
+    /**
+     * The name of the MongoDB collection for storing history entries.  Default: `${collection}_histories`
+     */
+    historyCollection?: string;
+}
+export interface HistoryPluginConfig extends HistoryConfigBase {
+    /**
+     * If true, compresses the stored document snapshots to save space.
+     */
+    compressDocs?: boolean;
+    /**
+     * If true, saves the entire document snapshot on changes. Default: true.
+     */
+    saveWholeDoc?: boolean;
+    /**
+     * Fields to skip from tracking changes.
+     */
+    skipFields?: Set<string>;
+    /**
+     * Fields to mask when storing history (e.g., for PII data).
+     */
+    maskedFields?: MaskedFields;
+}
+export declare function isHistoryPluginConfig(obj: unknown): obj is HistoryPluginConfig;

package/dist/config.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHistoryPluginConfig = isHistoryPluginConfig;
+const mongoose_1 = require("mongoose");
+function isHistoryPluginConfig(obj) {
+    return (obj !== undefined &&
+        typeof obj === "object" &&
+        obj !== null &&
+        "schema" in obj &&
+        obj.schema instanceof mongoose_1.Schema &&
+        "collection" in obj &&
+        typeof obj.collection === "string");
+}

package/dist/dto.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { LogHistoryEntity } from "./entities/log-history.js";
+export declare const HistoryDtoSchema: z.ZodObject<{
+    modelId: z.ZodCodec<z.ZodString, z.ZodCustom<import("mongoose").Types.ObjectId, import("mongoose").Types.ObjectId>>;
+    createdAt: z.ZodCodec<z.ZodCustomStringFormat<"date-time">, z.ZodDate>;
+    createdBy: z.ZodString;
+    isDeleted: z.ZodOptional<z.ZodBoolean>;
+    changeType: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        delete: "delete";
+    }>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    updatedDocument: z.ZodOptional<z.ZodUnknown>;
+    originalDocument: z.ZodOptional<z.ZodUnknown>;
+    logs: z.ZodArray<z.ZodObject<{
+        fieldName: z.ZodString;
+        oldValue: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+        newValue: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+        changeType: z.ZodEnum<{
+            add: "add";
+            edit: "edit";
+            remove: "remove";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type History = z.infer<typeof HistoryDtoSchema>;
+declare const HistoryDto_base: import("nestjs-zod").ZodDto<z.ZodObject<{
+    modelId: z.ZodCodec<z.ZodString, z.ZodCustom<import("mongoose").Types.ObjectId, import("mongoose").Types.ObjectId>>;
+    createdAt: z.ZodCodec<z.ZodCustomStringFormat<"date-time">, z.ZodDate>;
+    createdBy: z.ZodString;
+    isDeleted: z.ZodOptional<z.ZodBoolean>;
+    changeType: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        delete: "delete";
+    }>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    updatedDocument: z.ZodOptional<z.ZodUnknown>;
+    originalDocument: z.ZodOptional<z.ZodUnknown>;
+    logs: z.ZodArray<z.ZodObject<{
+        fieldName: z.ZodString;
+        oldValue: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+        newValue: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+        changeType: z.ZodEnum<{
+            add: "add";
+            edit: "edit";
+            remove: "remove";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+export declare class HistoryDto extends HistoryDto_base {
+    static fromEntity(parsedEntity: LogHistoryEntity): HistoryDto;
+    static tryDecompress(doc: unknown): unknown;
+}
+export {};

package/dist/dto.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistoryDto = exports.HistoryDtoSchema = void 0;
+const mongoose_log_history_1 = require("@palmetto/mongoose-log-history");
+const nestjs_zod_dto_1 = require("@palmetto/nestjs-zod-dto");
+const nestjs_toolbelt_1 = require("@palmetto/nestjs-toolbelt");
+const zod_1 = require("zod");
+exports.HistoryDtoSchema = zod_1.z.strictObject({
+    modelId: nestjs_toolbelt_1.HexStringToObjectIdCodec,
+    createdAt: nestjs_zod_dto_1.DateStringToDateCodec,
+    createdBy: zod_1.z.string(),
+    isDeleted: zod_1.z.boolean().optional(),
+    changeType: zod_1.z.enum(["create", "update", "delete"]),
+    context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    updatedDocument: zod_1.z.unknown().optional(),
+    originalDocument: zod_1.z.unknown().optional(),
+    logs: zod_1.z.array(zod_1.z.strictObject({
+        fieldName: zod_1.z.string(),
+        oldValue: zod_1.z.any().nullish(),
+        newValue: zod_1.z.any().nullish(),
+        changeType: zod_1.z.enum(["add", "edit", "remove"]),
+    })),
+});
+class HistoryDto extends (0, nestjs_zod_dto_1.createDtoFromZodSchema)(exports.HistoryDtoSchema, {
+    title: "History",
+}) {
+    static fromEntity(parsedEntity) {
+        return {
+            modelId: parsedEntity.modelId,
+            createdAt: parsedEntity.createdAt,
+            createdBy: parsedEntity.createdBy,
+            isDeleted: parsedEntity.isDeleted,
+            changeType: parsedEntity.changeType,
+            context: parsedEntity.context || undefined,
+            logs: parsedEntity.logs.map((change) => ({
+                fieldName: change.fieldName,
+                fromValue: change.fromValue,
+                toValue: change.toValue,
+                changeType: change.changeType,
+            })),
+            updatedDocument: HistoryDto.tryDecompress(parsedEntity.updatedDocument),
+            originalDocument: HistoryDto.tryDecompress(parsedEntity.originalDocument),
+        };
+    }
+    static tryDecompress(doc) {
+        if ((0, mongoose_log_history_1.isMongoBinary)(doc) || Buffer.isBuffer(doc)) {
+            return (0, mongoose_log_history_1.decompressObject)(doc);
+        }
+        return doc;
+    }
+}
+exports.HistoryDto = HistoryDto;

package/dist/entities/field-log.d.ts

@@ -0,0 +1,15 @@
+import { FieldLog as LogHistoryFieldLog } from "@palmetto/mongoose-log-history";
+import { z } from "zod";
+export declare const FieldLogSchema: z.ZodObject<{
+    fieldName: z.ZodString;
+    changeType: z.ZodEnum<{
+        add: "add";
+        edit: "edit";
+        remove: "remove";
+    }>;
+    fromValue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    toValue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type FieldLog = z.infer<typeof FieldLogSchema>;
+export declare function fieldLogFromEntry(entry: LogHistoryFieldLog): FieldLog;

package/dist/entities/field-log.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldLogSchema = void 0;
+exports.fieldLogFromEntry = fieldLogFromEntry;
+const zod_1 = require("zod");
+exports.FieldLogSchema = zod_1.z.object({
+    fieldName: zod_1.z
+        .string()
+        .meta({ description: "The name of the field that was changed" }),
+    changeType: zod_1.z
+        .enum(["add", "edit", "remove"])
+        .meta({ description: "The type of change made to the field" }),
+    fromValue: zod_1.z
+        .string()
+        .nullish()
+        .meta({ description: "The previous value of the field" }),
+    toValue: zod_1.z
+        .string()
+        .nullish()
+        .meta({ description: "The new value of the field" }),
+    context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullish().meta({
+        description: "Additional context specific to this field change",
+    }),
+});
+function fieldLogFromEntry(entry) {
+    return {
+        fieldName: entry.field_name,
+        changeType: entry.change_type,
+        fromValue: entry.from_value,
+        toValue: entry.to_value,
+        context: entry.context,
+    };
+}

package/dist/entities/log-history.d.ts

@@ -0,0 +1,31 @@
+import { SchemaWithId } from "@palmetto/zod-mongoose-schema";
+import { LogHistoryEntry } from "@palmetto/mongoose-log-history";
+import { Types } from "mongoose";
+import { z } from "zod";
+export declare const LogHistoryEntitySchema: z.ZodObject<{
+    modelId: z.ZodCustom<Types.ObjectId, Types.ObjectId>;
+    changeType: z.ZodEnum<{
+        create: "create";
+        update: "update";
+        delete: "delete";
+    }>;
+    logs: z.ZodArray<z.ZodObject<{
+        fieldName: z.ZodString;
+        changeType: z.ZodEnum<{
+            add: "add";
+            edit: "edit";
+            remove: "remove";
+        }>;
+        fromValue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        toValue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    originalDocument: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    updatedDocument: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    isDeleted: z.ZodBoolean;
+    createdBy: z.ZodString;
+    createdAt: z.ZodDate;
+}, z.core.$strip>;
+export type LogHistoryEntity = SchemaWithId<typeof LogHistoryEntitySchema>;
+export declare function entryToEntity(entry: LogHistoryEntry): LogHistoryEntity;

package/dist/entities/log-history.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogHistoryEntitySchema = void 0;
+exports.entryToEntity = entryToEntity;
+const zod_mongoose_schema_1 = require("@palmetto/zod-mongoose-schema");
+const mongoose_1 = require("mongoose");
+const zod_1 = require("zod");
+const field_log_js_1 = require("./field-log.js");
+exports.LogHistoryEntitySchema = zod_1.z.object({
+    modelId: zod_mongoose_schema_1.ObjectIdSchema,
+    changeType: zod_1.z
+        .enum(["create", "update", "delete"])
+        .meta({ description: "The type of change operation" }),
+    logs: zod_1.z
+        .array(field_log_js_1.FieldLogSchema)
+        .meta({ description: "Array of individual field changes" }),
+    context: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .nullish()
+        .meta({ description: "Global context information for this change" }),
+    originalDocument: zod_1.z.unknown().nullish().meta({
+        description: "Complete original document snapshot (if saveWholeDoc is enabled)",
+    }),
+    updatedDocument: zod_1.z.unknown().nullish().meta({
+        description: "Complete updated document snapshot (if saveWholeDoc is enabled)",
+    }),
+    isDeleted: zod_1.z.boolean().meta({
+        description: "Whether this log entry represents a deleted document",
+    }),
+    createdBy: zod_1.z
+        .string()
+        .meta({ description: "Information about who made the change" }),
+    createdAt: zod_1.z
+        .date()
+        .meta({ description: "Timestamp when the log entry was created" }),
+});
+function entryToEntity(entry) {
+    return {
+        _id: new mongoose_1.Types.ObjectId(),
+        modelId: new mongoose_1.Types.ObjectId(entry.model_id),
+        changeType: entry.change_type,
+        logs: entry.logs.map(field_log_js_1.fieldLogFromEntry),
+        context: entry.context,
+        originalDocument: entry.original_doc,
+        updatedDocument: entry.updated_doc,
+        isDeleted: entry.is_deleted,
+        createdBy: typeof entry.created_by === "string" ? entry.created_by : "unknown",
+        createdAt: entry.created_at,
+    };
+}

package/dist/history-model.d.ts

@@ -0,0 +1,10 @@
+import { Connection, PaginateModel } from "mongoose";
+import { HistoryPluginConfig } from "./config.js";
+import { LogHistoryEntity } from "./entities/log-history.js";
+import { createLogHistorySchema } from "./history-schema.js";
+/**
+ * Creates the Mongoose model for log history entries based on the provided options and log history schema.
+ * @param options
+ * @param schema
+ */
+export declare function createLogHistoryModelFromSchema(connection: Connection, options: HistoryPluginConfig, schema: ReturnType<typeof createLogHistorySchema>): PaginateModel<LogHistoryEntity>;

package/dist/history-model.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogHistoryModelFromSchema = createLogHistoryModelFromSchema;
+/**
+ * Creates the Mongoose model for log history entries based on the provided options and log history schema.
+ * @param options
+ * @param schema
+ */
+function createLogHistoryModelFromSchema(connection, options, schema) {
+    const historyCollection = options.historyCollection || `${options.collection}_histories`;
+    return connection.model(historyCollection, schema, historyCollection);
+}

package/dist/history-plugin.d.ts

@@ -0,0 +1,6 @@
+import { HistoryPluginConfig } from "./config.js";
+/**
+ * Adds the log history plugin to a Mongoose schema.
+ * @param options
+ */
+export declare function applyLogHistoryPlugin(options: HistoryPluginConfig): void;

package/dist/history-plugin.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyLogHistoryPlugin = applyLogHistoryPlugin;
+const mongoose_log_history_1 = require("@palmetto/mongoose-log-history");
+const common_1 = require("@nestjs/common");
+const plugin_options_js_1 = require("./plugin-options.js");
+const main_js_1 = require("./main.js");
+//import { saveHistories } from "./history-saver.js";
+/**
+ * Adds the log history plugin to a Mongoose schema.
+ * @param options
+ */
+function applyLogHistoryPlugin(options) {
+    common_1.Logger.debug(`Applying log history plugin to ${options.collection}`, "applyLogHistoryPlugin");
+    const pluginOptions = (0, plugin_options_js_1.getLogHistoryPluginOptions)(options);
+    common_1.Logger.debug(`Log history plugin options for ${options.collection}: ${JSON.stringify(pluginOptions)}`, "applyLogHistoryPlugin");
+    options.schema.plugin(mongoose_log_history_1.changeLoggingPlugin, Object.assign(Object.assign({}, pluginOptions), { logger: new common_1.Logger(`LogHistoryPlugin.${options.collection}`), logHistorySaver: main_js_1.saveHistories }));
+}

package/dist/history-saver.d.ts

@@ -0,0 +1,8 @@
+import { LogHistoryEntry, LogHistoryPlugin, LogHistorySaver } from "@palmetto/mongoose-log-history";
+export declare function saveHistories(plugin: LogHistoryPlugin, histories: LogHistoryEntry[]): Promise<void>;
+/**
+ * Sets the log history saver function for a specific model.
+ * @param modelName
+ * @param saver
+ */
+export declare function setLogHistorySaver(modelName: string, saver: LogHistorySaver): void;

package/dist/history-saver.js

@@ -0,0 +1,34 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveHistories = saveHistories;
+exports.setLogHistorySaver = setLogHistorySaver;
+const common_1 = require("@nestjs/common");
+const lazySavers = new Map();
+function saveHistories(plugin, histories) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const fn = lazySavers.get(plugin.modelName);
+        if (!fn) {
+            common_1.Logger.warn(`No log history saver function set for model ${plugin.modelName}`, "saveHistories");
+            return;
+        }
+        common_1.Logger.debug(`Using log history saver for model ${plugin.modelName} to save ${histories.length} entries`, "saveHistories");
+        yield fn(plugin, histories);
+    });
+}
+/**
+ * Sets the log history saver function for a specific model.
+ * @param modelName
+ * @param saver
+ */
+function setLogHistorySaver(modelName, saver) {
+    lazySavers.set(modelName, saver);
+}

package/dist/history-schema.d.ts

@@ -0,0 +1,126 @@
+import { HistoryPluginConfig } from "./config.js";
+/**
+ * Creates the mongoose schema for log history entries based on the provided options.
+ * @param options
+ */
+export declare function createLogHistorySchema(options: HistoryPluginConfig): import("mongoose").Schema<{
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}, import("mongoose").Model<{
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}, {}, {}, {}, import("mongoose").Document<unknown, {}, {
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}, {}, {}> & {
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+} & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, import("mongoose").DefaultSchemaOptions, {
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<{
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}>, {}, import("mongoose").ResolveSchemaOptions<import("mongoose").DefaultSchemaOptions>> & import("mongoose").FlatRecord<{
+    modelId: import("mongoose").Types.ObjectId;
+    changeType: "create" | "update" | "delete";
+    logs: {
+        fieldName: string;
+        changeType: "add" | "edit" | "remove";
+        fromValue?: string | null | undefined;
+        toValue?: string | null | undefined;
+        context?: Record<string, unknown> | null | undefined;
+    }[];
+    isDeleted: boolean;
+    createdBy: string;
+    createdAt: Date;
+    context?: Record<string, unknown> | null | undefined;
+    originalDocument?: unknown;
+    updatedDocument?: unknown;
+}> & {
+    _id: import("mongoose").Types.ObjectId;
+} & {
+    __v: number;
+}>;

package/dist/history-schema.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogHistorySchema = createLogHistorySchema;
+const nestjs_mongoose_1 = require("@palmetto/nestjs-mongoose");
+const zod_mongoose_schema_1 = require("@palmetto/zod-mongoose-schema");
+const log_history_js_1 = require("./entities/log-history.js");
+const schemaBuilder = new zod_mongoose_schema_1.SchemaBuilder();
+/**
+ * Creates the mongoose schema for log history entries based on the provided options.
+ * @param options
+ */
+function createLogHistorySchema(options) {
+    const historyCollection = `${options.collection}_histories`;
+    const schema = schemaBuilder.build(log_history_js_1.LogHistoryEntitySchema, {
+        collection: historyCollection,
+        versionKey: false,
+    });
+    schema.plugin(nestjs_mongoose_1.paginatePlugin);
+    schema.index({ modelId: 1, createdAt: -1 });
+    return schema;
+}

package/dist/main.d.ts

@@ -0,0 +1,9 @@
+export * from "./config.js";
+export * from "./dto.js";
+export * from "./history-model.js";
+export * from "./history-plugin.js";
+export * from "./history-saver.js";
+export * from "./history-schema.js";
+export * from "./module.js";
+export * from "./plugin-options.js";
+export * from "./service.js";

package/dist/main.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config.js"), exports);
+__exportStar(require("./dto.js"), exports);
+__exportStar(require("./history-model.js"), exports);
+__exportStar(require("./history-plugin.js"), exports);
+__exportStar(require("./history-saver.js"), exports);
+__exportStar(require("./history-schema.js"), exports);
+__exportStar(require("./module.js"), exports);
+__exportStar(require("./plugin-options.js"), exports);
+__exportStar(require("./service.js"), exports);

package/dist/module.d.ts

@@ -0,0 +1,9 @@
+import { DynamicModule, FactoryProvider, ModuleMetadata } from "@nestjs/common";
+import { HistoryPluginConfig } from "./config.js";
+export interface HistoryModuleOptions extends Pick<ModuleMetadata, "imports"> {
+    inject?: FactoryProvider["inject"];
+    useFactory: (...args: any[]) => Promise<HistoryPluginConfig> | HistoryPluginConfig;
+}
+export declare class HistoryModule {
+    static forFeature(config: HistoryModuleOptions | HistoryPluginConfig): DynamicModule;
+}

package/dist/module.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistoryModule = void 0;
+const mongoose_1 = require("@nestjs/mongoose");
+const config_js_1 = require("./config.js");
+const service_js_1 = require("./service.js");
+const history_schema_js_1 = require("./history-schema.js");
+const history_model_js_1 = require("./history-model.js");
+const HISTORY_OPTIONS_TOKEN = "HISTORY_OPTIONS";
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+class HistoryModule {
+    static forFeature(config) {
+        var _a;
+        const isConfig = (0, config_js_1.isHistoryPluginConfig)(config);
+        const historyProvider = isConfig
+            ? {
+                provide: HISTORY_OPTIONS_TOKEN,
+                useValue: config,
+            }
+            : Object.assign({ provide: HISTORY_OPTIONS_TOKEN }, config);
+        const providers = [
+            historyProvider,
+            {
+                provide: service_js_1.HistoryService,
+                inject: [HISTORY_OPTIONS_TOKEN, (0, mongoose_1.getConnectionToken)()],
+                useFactory(options, connection) {
+                    const schema = (0, history_schema_js_1.createLogHistorySchema)(options);
+                    const model = (0, history_model_js_1.createLogHistoryModelFromSchema)(connection, options, schema);
+                    return new service_js_1.HistoryService(model, options.collection);
+                },
+            },
+        ];
+        return {
+            global: false,
+            providers,
+            imports: [...(isConfig ? [] : (_a = config.imports) !== null && _a !== void 0 ? _a : [])],
+            module: HistoryModule,
+            exports: [service_js_1.HistoryService],
+        };
+    }
+}
+exports.HistoryModule = HistoryModule;

package/dist/plugin-options.d.ts

@@ -0,0 +1,3 @@
+import { PluginOptions } from "@palmetto/mongoose-log-history";
+import { HistoryPluginConfig } from "./config";
+export declare function getLogHistoryPluginOptions(config: HistoryPluginConfig): PluginOptions;

package/dist/plugin-options.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLogHistoryPluginOptions = getLogHistoryPluginOptions;
+function getLogHistoryPluginOptions(config) {
+    var _a, _b, _c, _d;
+    const skipFields = (_a = config.skipFields) !== null && _a !== void 0 ? _a : new Set();
+    const maskedFields = (_b = config.maskedFields) !== null && _b !== void 0 ? _b : {};
+    const collectionName = config.collection;
+    const schema = config.schema;
+    function getTrackedFields(parentField, schema) {
+        const trackedFields = [];
+        schema.eachPath((path) => {
+            const fullPath = `${parentField}${path}`;
+            if (fullPath === "meta" ||
+                fullPath === "_id" ||
+                fullPath === "__v" ||
+                skipFields.has(fullPath)) {
+                return;
+            }
+            const entry = {
+                value: path,
+            };
+            const pathSchema = schema.path(path);
+            if (fullPath in maskedFields) {
+                entry.mask = maskedFields[fullPath];
+            }
+            else if (pathSchema.options.encryption) {
+                entry.mask = "****";
+            }
+            if (pathSchema.schema) {
+                entry.trackedFields = getTrackedFields(`${fullPath}.`, pathSchema.schema);
+                if (Array.isArray(pathSchema.options.type)) {
+                    entry.arrayType = "custom-key";
+                    entry.arrayKey = "id";
+                }
+            }
+            else if (Array.isArray(pathSchema.options.type)) {
+                entry.arrayType = "simple";
+            }
+            trackedFields.push(entry);
+        });
+        if (schema.discriminators) {
+            for (const discSchema of Object.values(schema.discriminators)) {
+                const discTrackedFields = getTrackedFields(parentField, discSchema);
+                for (const discField of discTrackedFields) {
+                    if (!trackedFields.find((tf) => tf.value === discField.value)) {
+                        trackedFields.push(discField);
+                    }
+                }
+            }
+        }
+        return trackedFields;
+    }
+    const trackedFields = getTrackedFields("", schema);
+    return {
+        modelName: collectionName,
+        saveWholeDoc: (_c = config.saveWholeDoc) !== null && _c !== void 0 ? _c : true,
+        compressDocs: (_d = config.compressDocs) !== null && _d !== void 0 ? _d : false,
+        softDelete: (doc) => isMetaDeleted(doc) ? true : false,
+        userField: "meta.updatedBy",
+        trackedFields,
+    };
+}
+function isMetaDeleted(doc) {
+    if ("meta.deletedAt" in doc && doc["meta.deletedAt"] instanceof Date) {
+        return true;
+    }
+    if ("meta" in doc &&
+        doc.meta !== null &&
+        typeof doc.meta === "object" &&
+        "deletedAt" in doc.meta &&
+        doc.meta.deletedAt instanceof Date) {
+        return true;
+    }
+    return false;
+}

package/dist/service.d.ts

@@ -0,0 +1,18 @@
+import { FilterQuery, PaginateModel, Types } from "mongoose";
+import { BaseMongooseService } from "@palmetto/nestjs-mongoose/dist/services/base-mongoose.service";
+import { LogHistoryEntry, LogHistoryPlugin } from "@palmetto/mongoose-log-history";
+import { LogHistoryEntity } from "./entities/log-history.js";
+export interface HistoryFindAllOptions {
+    start?: Date;
+    end?: Date;
+    limit?: number;
+    page?: number;
+}
+export declare class HistoryService extends BaseMongooseService<LogHistoryEntity> {
+    private readonly logger;
+    constructor(model: PaginateModel<LogHistoryEntity>, modelName: string);
+    saveHistories(_: LogHistoryPlugin, histories: LogHistoryEntry[]): Promise<void>;
+    findAllById(id: string | Types.ObjectId, { limit, page, start, end }?: HistoryFindAllOptions): Promise<import("@palmetto/nestjs-mongoose").PageResult<LogHistoryEntity>>;
+    removeAll(filter?: FilterQuery<LogHistoryEntity>): Promise<number>;
+    removeAllById(id: string | Types.ObjectId): Promise<number>;
+}

package/dist/service.js

@@ -0,0 +1,91 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var HistoryService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistoryService = void 0;
+const mongoose_1 = require("mongoose");
+const common_1 = require("@nestjs/common");
+const base_mongoose_service_1 = require("@palmetto/nestjs-mongoose/dist/services/base-mongoose.service");
+const log_history_js_1 = require("./entities/log-history.js");
+const history_saver_js_1 = require("./history-saver.js");
+let HistoryService = HistoryService_1 = class HistoryService extends base_mongoose_service_1.BaseMongooseService {
+    constructor(model, modelName) {
+        super(model);
+        this.logger = new common_1.Logger(HistoryService_1.name);
+        (0, history_saver_js_1.setLogHistorySaver)(modelName, this.saveHistories.bind(this));
+        this.logger.debug(`HistoryService initialized for ${model.collection.name} for ${modelName}`);
+    }
+    saveHistories(_, histories) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (histories.length === 0) {
+                return;
+            }
+            const bulkOps = histories.map((entry) => {
+                return {
+                    insertOne: {
+                        document: (0, log_history_js_1.entryToEntity)(entry),
+                    },
+                };
+            });
+            yield this.model.bulkWrite(bulkOps);
+            this.logger.debug(`saved ${histories.length} history entries`);
+        });
+    }
+    findAllById(id_1) {
+        return __awaiter(this, arguments, void 0, function* (id, { limit, page, start, end } = {}) {
+            const query = {
+                modelId: new mongoose_1.Types.ObjectId(id),
+            };
+            if (start || end) {
+                const createdAtFilter = [];
+                if (start) {
+                    createdAtFilter.push({ createdAt: { $gte: start } });
+                }
+                if (end) {
+                    createdAtFilter.push({ createdAt: { $lt: end } });
+                }
+                query.$and = createdAtFilter;
+            }
+            return yield this.findAllPaged(query, { limit, page });
+        });
+    }
+    removeAll() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}) {
+            const result = yield this.model.collection.deleteMany(filter);
+            this.logger.debug(`removed ${result.deletedCount} history entries`);
+            return result.deletedCount;
+        });
+    }
+    removeAllById(id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const objectId = new mongoose_1.Types.ObjectId(id);
+            const result = yield this.model.collection.deleteMany({
+                modelId: objectId,
+            });
+            this.logger.debug(`removed ${result.deletedCount} history entries for modelId ${objectId.toHexString()}`);
+            return result.deletedCount;
+        });
+    }
+};
+exports.HistoryService = HistoryService;
+exports.HistoryService = HistoryService = HistoryService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, String])
+], HistoryService);

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@palmetto/nestjs-log-history",
+  "version": "0.0.1",
+  "main": "./dist/main.js",
+  "scripts": {
+    "lint": "yarn run -T eslint --fix ./src",
+    "format": "yarn run -T prettier --write --loglevel warn .",
+    "tc": "tsc --noEmit",
+    "build": "yarn clean && yarn ci:build",
+    "clean": "rm -rf ./dist/",
+    "ci:build": "tsc -p tsconfig.build.json",
+    "ci:lint": "yarn run -T eslint . && yarn run -T prettier --check --loglevel warn .",
+    "ci:tc": "yarn tc",
+    "hook:lint": "eslint --cache --fix",
+    "hook:format": "prettier --write --loglevel warn",
+    "hook:tc": "yarn tc",
+    "prepublishOnly": "yarn build",
+    "test-runner": "../../scripts/test-runner.sh",
+    "test": "yarn run test-runner vitest run",
+    "test:watch": "yarn run test-runner vitest watch"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.6",
+    "@nestjs/mongoose": "^11",
+    "@nestjs/testing": "^11.1.5",
+    "@palmetto/mongoose-log-history": "^1.2.4",
+    "@palmetto/nestjs-mongoose": "^2.2.6",
+    "@palmetto/nestjs-toolbelt": "^1.1.9",
+    "@palmetto/nestjs-zod-dto": "^2.0.1",
+    "@palmetto/zod-mongoose-schema": "^0.2.4",
+    "@swc/core": "^1.13.3",
+    "@types/node": "^24.2.1",
+    "mongodb": "~6.20.0",
+    "mongoose": "^8.19.3",
+    "typescript": "5.7.3",
+    "unplugin-swc": "^1.5.6",
+    "vitest": "^3.2.4",
+    "zod": "^4.0.13"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.6",
+    "@nestjs/mongoose": "^11",
+    "@palmetto/mongoose-log-history": "*",
+    "@palmetto/nestjs-mongoose": "^2.2.6",
+    "@palmetto/nestjs-toolbelt": "^1.1.9",
+    "@palmetto/nestjs-zod-dto": "^2.0.1",
+    "@palmetto/zod-mongoose-schema": "^0.2.4",
+    "mongodb": "~6.20.0",
+    "mongoose": "^8.19.3",
+    "zod": "^4.0.13"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}