itlab-internal-services 2.16.0 → 2.16.1

package/dist/classes/document-merger.class.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocumentMerger = void 0;
 const common_1 = require("@nestjs/common");
+const itlab_functions_1 = require("itlab-functions");
 /**
  * DocumentMerger
  *
@@ -75,7 +76,7 @@ class DocumentMerger {
         });
         const elapsedTime = Date.now() - startTime;
         // Log completion with fields merged and time taken
-        this.logger.log(`Successfully merged fields: ${this.fields.join(', ')} (took ${elapsedTime} ms)`);
+        this.logger.log(`Successfully merged fields: ${(0, itlab_functions_1.formatList)(this.fields)} (took ${elapsedTime} ms)`);
     }
 }
 exports.DocumentMerger = DocumentMerger;

package/dist/classes/index.d.ts

@@ -1,3 +1,5 @@
 export { DocumentMerger } from './document-merger.class';
-export { DocumentUpdater } from './document-updater.class';
 export { ReportCategory } from './report-category.class';
+export { SchemaBuilder } from './schema-builder.class';
+export type { SchemaBuilderDocument, SchemaBuilderModel, SchemaBuilderOptions } from './schema-builder.class';
+export { TaskManager } from './task-manager.class';

package/dist/classes/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReportCategory = exports.DocumentUpdater = exports.DocumentMerger = void 0;
+exports.TaskManager = exports.SchemaBuilder = exports.ReportCategory = exports.DocumentMerger = void 0;
 var document_merger_class_1 = require("./document-merger.class");
 Object.defineProperty(exports, "DocumentMerger", { enumerable: true, get: function () { return document_merger_class_1.DocumentMerger; } });
-var document_updater_class_1 = require("./document-updater.class");
-Object.defineProperty(exports, "DocumentUpdater", { enumerable: true, get: function () { return document_updater_class_1.DocumentUpdater; } });
 var report_category_class_1 = require("./report-category.class");
 Object.defineProperty(exports, "ReportCategory", { enumerable: true, get: function () { return report_category_class_1.ReportCategory; } });
+var schema_builder_class_1 = require("./schema-builder.class");
+Object.defineProperty(exports, "SchemaBuilder", { enumerable: true, get: function () { return schema_builder_class_1.SchemaBuilder; } });
+var task_manager_class_1 = require("./task-manager.class");
+Object.defineProperty(exports, "TaskManager", { enumerable: true, get: function () { return task_manager_class_1.TaskManager; } });

package/dist/classes/schema-builder.class.d.ts

@@ -0,0 +1,75 @@
+import { Type } from '@nestjs/common';
+import { Document, Model, Schema } from 'mongoose';
+import { Likeable, Viewable } from '../types';
+/**
+ * Options that determine how the schema should be extended.
+ *
+ * @template TClass - The document type for the schema.
+ */
+export type SchemaBuilderOptions<TClass extends Document> = {
+    /** Whether this schema should support view tracking. */
+    viewable?: boolean;
+    /** Whether this schema should support like tracking. */
+    likeable?: boolean;
+    /**
+     * A set of keys that uniquely identify the document.
+     * These keys are used when checking for duplicates.
+     */
+    criticalKeys?: (keyof Omit<TClass, keyof Document>)[];
+};
+/**
+ * Computes the augmented document type based on SchemaOptions.
+ */
+export type SchemaBuilderDocument<TClass extends Document, TOptions extends SchemaBuilderOptions<TClass>> = TClass & (TOptions['viewable'] extends true ? Viewable : object) & (TOptions['likeable'] extends true ? Likeable : object);
+/**
+ * Extends a standard Mongoose model with custom static methods
+ * injected by the SchemaBuilder.
+ */
+export type SchemaBuilderModel<TClass extends Document> = Model<TClass> & {
+    /**
+     * Checks if the given object is a duplicate of an existing document.
+     *
+     * @param dto - Partial object with properties to check for duplicates.
+     * @param updateTarget - The document being updated, if applicable.
+     * @returns {Promise<boolean>} - True if a duplicate exists, false otherwise.
+     */
+    isDuplicate(dto: Partial<TClass>, updateTarget?: TClass): Promise<boolean>;
+};
+/**
+ * Generic builder for creating extended Mongoose schemas.
+ *
+ * This class wraps Nest's SchemaFactory and automatically injects common
+ * behaviors such as:
+ * - View tracking (who viewed, view counts)
+ * - Like tracking (who liked, like counts)
+ * - Duplicate checking based on critical keys
+ *
+ * @template TClass - A class extending Mongoose Document.
+ */
+export declare class SchemaBuilder<TClass extends Document> {
+    private schema;
+    readonly options: SchemaBuilderOptions<TClass>;
+    constructor(target: Type<TClass>, options?: SchemaBuilderOptions<TClass>);
+    /**
+     * Adds interaction tracking (likes or views) to a schema.
+     * This method generalizes the shared logic between "viewable" and "likeable".
+     *
+     * @param field - The internal array field storing account IDs. (e.g. _viewedBy or _likedBy)
+     * @param counter - The numeric counter field tracking totals. (e.g. views or likes)
+     */
+    provideInteraction(field: string, counter: string): this;
+    /**
+     * Adds a duplicate-checking static method to the schema.
+     * This method compares critical keys to detect conflicts.
+     */
+    private provideDuplicateChecker;
+    /**
+     * Finalizes the schema and injects any selected behaviors (viewable, likeable, duplicate checking).
+     *
+     * @returns An object containing:
+     * - `schema`: The Mongoose schema.
+     * - `modelType`: A strongly typed model with additional static methods.
+     * - `documentType`: The inferred document type with injected properties.
+     */
+    build(): Schema;
+}

package/dist/classes/schema-builder.class.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaBuilder = void 0;
+const mongoose_1 = require("@nestjs/mongoose");
+const class_validator_1 = require("class-validator");
+/**
+ * Generic builder for creating extended Mongoose schemas.
+ *
+ * This class wraps Nest's SchemaFactory and automatically injects common
+ * behaviors such as:
+ * - View tracking (who viewed, view counts)
+ * - Like tracking (who liked, like counts)
+ * - Duplicate checking based on critical keys
+ *
+ * @template TClass - A class extending Mongoose Document.
+ */
+class SchemaBuilder {
+    constructor(target, options = {}) {
+        this.schema = mongoose_1.SchemaFactory.createForClass(target);
+        this.options = options;
+        /**
+         * Create a wildcard index required for CosmosDB to support sorting on all fields.
+         *
+         * This is a workaround for CosmosDB's partial MongoDB API compatibility.
+         * See: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/indexing#wildcard-indexes
+         */
+        this.schema.index({ '$**': 1 }, { name: 'Sort Index' });
+        this.provideDuplicateChecker();
+    }
+    /**
+     * Adds interaction tracking (likes or views) to a schema.
+     * This method generalizes the shared logic between "viewable" and "likeable".
+     *
+     * @param field - The internal array field storing account IDs. (e.g. _viewedBy or _likedBy)
+     * @param counter - The numeric counter field tracking totals. (e.g. views or likes)
+     */
+    provideInteraction(field, counter) {
+        // Add fields to the schema
+        this.schema.add({ [field]: { type: [String], default: [] }, [counter]: { type: Number, default: 0 } });
+        // Expose a virtual property (without underscore) for convenience
+        this.schema.virtual(field.replace(/^_/, ''));
+        // Add method to increment counter
+        this.schema.methods[`add${counter[0].toUpperCase() + counter.slice(1)}`] = async function (accountId) {
+            if (!(0, class_validator_1.isMongoId)(accountId))
+                return Number(this[counter]);
+            // Ensure uniqueness by converting to a Set
+            this[field] = Array.from(new Set([...this[field], accountId]));
+            this[counter] = this[field].length;
+            await this.save({ timestamps: false });
+            return this[counter];
+        };
+        // Add method to decrement counter
+        this.schema.methods[`remove${counter[0].toUpperCase() + counter.slice(1)}`] = async function (accountId) {
+            if (!(0, class_validator_1.isMongoId)(accountId))
+                return Number(this[counter]);
+            // Remove the accountId from the list
+            this[field] = this[field].filter((id) => id !== accountId);
+            this[counter] = this[field].length;
+            await this.save({ timestamps: false });
+            return this[counter];
+        };
+        return this;
+    }
+    /**
+     * Adds a duplicate-checking static method to the schema.
+     * This method compares critical keys to detect conflicts.
+     */
+    provideDuplicateChecker() {
+        var _a;
+        const criticalKeys = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.criticalKeys) || [];
+        this.schema.statics.isDuplicate = async function (dto, updateTarget) {
+            var _a;
+            if (criticalKeys.length === 0)
+                return false;
+            // Build a filter using the critical keys
+            const filterQuery = criticalKeys.reduce((query, key) => {
+                if (dto && key in dto)
+                    query[String(key)] = dto[key];
+                else if (updateTarget && key in updateTarget)
+                    query[String(key)] = updateTarget[key];
+                return query;
+            }, {});
+            // If a matching document exists, check whether it’s the same entity
+            const potentialDuplicate = await this.findOne(filterQuery);
+            if (!potentialDuplicate)
+                return false;
+            const potentialId = potentialDuplicate._id.toString().toLowerCase();
+            const targetId = (_a = updateTarget === null || updateTarget === void 0 ? void 0 : updateTarget._id) === null || _a === void 0 ? void 0 : _a.toString().toLowerCase();
+            return potentialId !== targetId;
+        };
+    }
+    /**
+     * Finalizes the schema and injects any selected behaviors (viewable, likeable, duplicate checking).
+     *
+     * @returns An object containing:
+     * - `schema`: The Mongoose schema.
+     * - `modelType`: A strongly typed model with additional static methods.
+     * - `documentType`: The inferred document type with injected properties.
+     */
+    build() {
+        var _a, _b;
+        if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.viewable)
+            this.provideInteraction('_viewedBy', 'views');
+        if ((_b = this.options) === null || _b === void 0 ? void 0 : _b.likeable)
+            this.provideInteraction('_likedBy', 'likes');
+        return this.schema;
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;

package/dist/classes/task-manager.class.d.ts

@@ -0,0 +1,71 @@
+import { Account, User } from '../models';
+import { AccountsService } from '../modules';
+/**
+ * TaskManager is a utility class that collects asynchronous tasks
+ * and executes them in parallel.
+ *
+ * This is especially useful for orchestrating optional async operations
+ * where not all tasks need to be executed every time.
+ *
+ * Example:
+ * ```ts
+ * const taskManager = new TaskManager();
+ * taskManager.add(async () => { ... });
+ * taskManager.add(async () => { ... });
+ * await taskManager.run();
+ * ```
+ */
+export declare class TaskManager {
+    private tasks;
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param userIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static fetchAndMapUsers(userIdGroups: string[][], accountsService: AccountsService): Promise<Map<string, User>>;
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param accountIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static fetchAndMapAccounts(accountIdGroups: string[][], accountsService: AccountsService): Promise<Map<string, Account>>;
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param userIds Array of user IDs to map
+     * @param userMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToUsers(userIds: string[], userMap: Map<string, User>): any[];
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param accountIds Array of user IDs to map
+     * @param accountMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToAccounts(accountIds: string[], accountMap: Map<string, Account>): any[];
+    /**
+     * Adds a new asynchronous task to the queue.
+     *
+     * @param task - A function that returns a Promise.
+     *               It should contain the actual async logic to be executed.
+     */
+    add(task: () => Promise<void>): void;
+    /**
+     * Executes all queued tasks in parallel and waits for their completion.
+     *
+     * - Tasks are executed concurrently using `Promise.all`.
+     * - If one task fails, the error will propagate and stop execution.
+     */
+    run(): Promise<void>;
+    /**
+     * Clears all tasks from the queue without executing them.
+     * Useful if you want to reset and reuse the TaskManager instance.
+     */
+    clear(): void;
+}

package/dist/classes/task-manager.class.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskManager = void 0;
+/**
+ * TaskManager is a utility class that collects asynchronous tasks
+ * and executes them in parallel.
+ *
+ * This is especially useful for orchestrating optional async operations
+ * where not all tasks need to be executed every time.
+ *
+ * Example:
+ * ```ts
+ * const taskManager = new TaskManager();
+ * taskManager.add(async () => { ... });
+ * taskManager.add(async () => { ... });
+ * await taskManager.run();
+ * ```
+ */
+class TaskManager {
+    constructor() {
+        this.tasks = [];
+    }
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param userIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static async fetchAndMapUsers(userIdGroups, accountsService) {
+        // Collect all unique user IDs across all groups
+        const uniqueUserIds = new Set(userIdGroups.flat());
+        // Fetch all users once
+        const userCollection = await accountsService.getUserCollection(Array.from(uniqueUserIds));
+        // Build a map for quick lookup
+        return new Map(userCollection.map((user) => [user.id, user]));
+    }
+    /**
+     * Fetches all users for the given ID groups and returns a mapping.
+     * Ensures each user is fetched only once.
+     * @param accountIdGroups Array of arrays of user IDs (e.g., authors, likedBy, viewedBy)
+     * @param accountsService Service responsible for fetching users
+     * @returns Map of userId -> user
+     */
+    static async fetchAndMapAccounts(accountIdGroups, accountsService) {
+        // Collect all unique user IDs across all groups
+        const uniqueAccountIds = new Set(accountIdGroups.flat());
+        // Fetch all users once
+        const accountCollection = await accountsService.getAccountCollection(Array.from(uniqueAccountIds));
+        // Build a map for quick lookup
+        return new Map(accountCollection.map((account) => [account.id, account]));
+    }
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param userIds Array of user IDs to map
+     * @param userMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToUsers(userIds, userMap) {
+        return userIds.map((userId) => userMap.get(userId)).filter(Boolean);
+    }
+    /**
+     * Maps an array of IDs to user objects using a userMap.
+     * Filters out any IDs that don’t have a corresponding user.
+     * @param accountIds Array of user IDs to map
+     * @param accountMap Map of userId -> user object
+     * @returns Array of user objects
+     */
+    static mapIdsToAccounts(accountIds, accountMap) {
+        return accountIds.map((accountId) => accountMap.get(accountId)).filter(Boolean);
+    }
+    /**
+     * Adds a new asynchronous task to the queue.
+     *
+     * @param task - A function that returns a Promise.
+     *               It should contain the actual async logic to be executed.
+     */
+    add(task) {
+        this.tasks.push(task);
+    }
+    /**
+     * Executes all queued tasks in parallel and waits for their completion.
+     *
+     * - Tasks are executed concurrently using `Promise.all`.
+     * - If one task fails, the error will propagate and stop execution.
+     */
+    async run() {
+        await Promise.all(this.tasks.map((task) => task()));
+    }
+    /**
+     * Clears all tasks from the queue without executing them.
+     * Useful if you want to reset and reuse the TaskManager instance.
+     */
+    clear() {
+        this.tasks = [];
+    }
+}
+exports.TaskManager = TaskManager;

package/dist/exceptions/bad-parameter.exception.js

@@ -4,6 +4,7 @@ exports.BadParameterException = void 0;
 exports.ApiBadParameterResponse = ApiBadParameterResponse;
 const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
+const itlab_functions_1 = require("itlab-functions");
 /**
  * BadParameterException
  *
@@ -56,7 +57,7 @@ function ApiBadParameterResponse(...params) {
         // Format description with proper pluralization.
         const pluralized = params.length > 1 ? 's' : '';
         const newDescription = params.length
-            ? `Invalid parameter${pluralized}: ${params.join(', ')}`
+            ? `Invalid parameter${pluralized}: ${(0, itlab_functions_1.formatList)(params, 'or')}`
             : 'One or more request parameters are invalid.';
         // Merge with existing description if needed.
         const mergedDescription = existingDescription ? `${existingDescription}<br />${newDescription}` : newDescription;

package/dist/index.d.ts

@@ -3,13 +3,13 @@ export * from './controllers';
 export * from './decorators';
 export * from './exceptions';
 export * from './functions';
+export * from './interceptors';
+export * from './middleware';
 export * from './models';
 export * from './modules';
 export * from './pipes';
 export * from './properties';
 export * from './swagger';
 export * from './transform';
-export * from './http-logger.middleware';
+export * from './types';
 export * from './hub-resource.enum';
-export * from './likeable.interface';
-export * from './viewable.interface';

package/dist/index.js

@@ -19,13 +19,13 @@ __exportStar(require("./controllers"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./exceptions"), exports);
 __exportStar(require("./functions"), exports);
+__exportStar(require("./interceptors"), exports);
+__exportStar(require("./middleware"), exports);
 __exportStar(require("./models"), exports);
 __exportStar(require("./modules"), exports);
 __exportStar(require("./pipes"), exports);
 __exportStar(require("./properties"), exports);
 __exportStar(require("./swagger"), exports);
 __exportStar(require("./transform"), exports);
-__exportStar(require("./http-logger.middleware"), exports);
+__exportStar(require("./types"), exports);
 __exportStar(require("./hub-resource.enum"), exports);
-__exportStar(require("./likeable.interface"), exports);
-__exportStar(require("./viewable.interface"), exports);

package/dist/interceptors/attribute-sanitizer.interceptor.d.ts

@@ -0,0 +1,68 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+/**
+ * AttributeSanitizerInterceptor
+ *
+ * This interceptor removes specified attributes from response objects.
+ * It works with plain objects, arrays, sets, maps and also with Mongoose
+ * documents by normalizing them to plain objects before sanitization.
+ *
+ * This is especially useful for removing sensitive fields (e.g., passwords,
+ * tokens, SSNs) consistently across deeply nested response structures.
+ */
+export declare class AttributeSanitizerInterceptor implements NestInterceptor {
+    private readonly keys;
+    private readonly mongooseToObjectOptions;
+    /**
+     * @param keys - One or more property names to remove from every object.
+     * @param mongooseToObjectOptions - Options forwarded to Mongoose `.toObject()`
+     *                                  when normalizing documents.
+     */
+    constructor(keys: string | string[], mongooseToObjectOptions?: Record<string, unknown>);
+    /**
+     * Intercepts the response and removes the targeted attributes.
+     *
+     * @param _context - Execution context (unused here).
+     * @param next - Next handler in the pipeline.
+     * @returns Sanitized response data.
+     */
+    intercept(_context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /**
+     * Recursively removes targeted keys from objects, arrays, and nested structures.
+     *
+     * @param value - Any response value.
+     * @returns A sanitized value without the targeted attributes.
+     */
+    private sanitizeRecursively;
+    /**
+     * Converts a Mongoose document to a plain object if needed.
+     *
+     * @param value - Possible Mongoose document.
+     * @returns A plain object if conversion is possible, otherwise the value itself.
+     */
+    private normalizeIfMongooseDocument;
+    /**
+     * Checks whether a value is a plain object (and not a class instance, Date, etc.).
+     *
+     * @param value - Any value.
+     * @returns True if the value is a plain object.
+     */
+    private isPlainObject;
+    /**
+     * Converts the user-provided keys into a Set for O(1) lookup.
+     *
+     * @param keys - String or array of strings.
+     * @returns A Set of keys.
+     */
+    private ensureKeySet;
+}
+/**
+ * @UseAttributeSanitizer
+ *
+ * Convenience decorator that applies the AttributeSanitizerInterceptor
+ * to a route or controller.
+ *
+ * @param keys - One or more keys to remove from all response objects.
+ * @param mongooseToObjectOptions - Options for Mongoose `.toObject()` normalization.
+ */
+export declare function UseAttributeSanitizer(keys: string | string[], mongooseToObjectOptions?: Record<string, unknown>): MethodDecorator & ClassDecorator;

package/dist/interceptors/attribute-sanitizer.interceptor.js

@@ -0,0 +1,154 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttributeSanitizerInterceptor = void 0;
+exports.UseAttributeSanitizer = UseAttributeSanitizer;
+const common_1 = require("@nestjs/common");
+const operators_1 = require("rxjs/operators");
+/**
+ * AttributeSanitizerInterceptor
+ *
+ * This interceptor removes specified attributes from response objects.
+ * It works with plain objects, arrays, sets, maps and also with Mongoose
+ * documents by normalizing them to plain objects before sanitization.
+ *
+ * This is especially useful for removing sensitive fields (e.g., passwords,
+ * tokens, SSNs) consistently across deeply nested response structures.
+ */
+let AttributeSanitizerInterceptor = class AttributeSanitizerInterceptor {
+    /**
+     * @param keys - One or more property names to remove from every object.
+     * @param mongooseToObjectOptions - Options forwarded to Mongoose `.toObject()`
+     *                                  when normalizing documents.
+     */
+    constructor(keys, mongooseToObjectOptions = {
+        virtuals: true,
+        getters: true,
+        versionKey: false,
+    }) {
+        this.keys = keys;
+        this.mongooseToObjectOptions = mongooseToObjectOptions;
+    }
+    /**
+     * Intercepts the response and removes the targeted attributes.
+     *
+     * @param _context - Execution context (unused here).
+     * @param next - Next handler in the pipeline.
+     * @returns Sanitized response data.
+     */
+    intercept(_context, next) {
+        return next.handle().pipe((0, operators_1.map)((data) => this.sanitizeRecursively(data)));
+    }
+    /**
+     * Recursively removes targeted keys from objects, arrays, and nested structures.
+     *
+     * @param value - Any response value.
+     * @returns A sanitized value without the targeted attributes.
+     */
+    sanitizeRecursively(value) {
+        const normalized = this.normalizeIfMongooseDocument(value);
+        if (normalized === null || typeof normalized !== 'object') {
+            return normalized;
+        }
+        // Handle arrays
+        if (Array.isArray(normalized)) {
+            return normalized.map((item) => this.sanitizeRecursively(item));
+        }
+        // Handle Set → array
+        if (normalized instanceof Set) {
+            return Array.from(normalized).map((item) => this.sanitizeRecursively(item));
+        }
+        // Handle Map → plain object
+        if (normalized instanceof Map) {
+            const obj = {};
+            for (const [k, v] of normalized.entries()) {
+                obj[String(k)] = this.sanitizeRecursively(v);
+            }
+            return obj;
+        }
+        // Handle plain objects
+        if (this.isPlainObject(normalized)) {
+            const forbidden = this.ensureKeySet(this.keys);
+            const result = {};
+            for (const [prop, nested] of Object.entries(normalized)) {
+                if (forbidden.has(prop))
+                    continue;
+                result[prop] = this.sanitizeRecursively(nested);
+            }
+            return result;
+        }
+        // Other complex types (Date, Buffer, etc.) → leave unchanged
+        return normalized;
+    }
+    /**
+     * Converts a Mongoose document to a plain object if needed.
+     *
+     * @param value - Possible Mongoose document.
+     * @returns A plain object if conversion is possible, otherwise the value itself.
+     */
+    normalizeIfMongooseDocument(value) {
+        // Heuristic: Mongoose documents expose `.toObject()` and an internal `$__`.
+        // We avoid importing `mongoose` to keep this interceptor framework-agnostic.
+        const maybeDoc = value;
+        if (maybeDoc &&
+            typeof maybeDoc === 'object' &&
+            (typeof maybeDoc.toObject === 'function' || typeof maybeDoc.toJSON === 'function') &&
+            '$__' in maybeDoc) {
+            try {
+                if (typeof maybeDoc.toObject === 'function')
+                    return maybeDoc.toObject(this.mongooseToObjectOptions);
+                if (typeof maybeDoc.toJSON === 'function')
+                    return maybeDoc.toJSON(this.mongooseToObjectOptions);
+            }
+            catch (_a) {
+                // If normalization fails, fall back to the original value—better to
+                // return data than to throw at the last step.
+                return value;
+            }
+        }
+        return value;
+    }
+    /**
+     * Checks whether a value is a plain object (and not a class instance, Date, etc.).
+     *
+     * @param value - Any value.
+     * @returns True if the value is a plain object.
+     */
+    isPlainObject(value) {
+        return Object.prototype.toString.call(value) === '[object Object]';
+    }
+    /**
+     * Converts the user-provided keys into a Set for O(1) lookup.
+     *
+     * @param keys - String or array of strings.
+     * @returns A Set of keys.
+     */
+    ensureKeySet(keys) {
+        return Array.isArray(keys) ? new Set(keys) : new Set([keys]);
+    }
+};
+exports.AttributeSanitizerInterceptor = AttributeSanitizerInterceptor;
+exports.AttributeSanitizerInterceptor = AttributeSanitizerInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Object])
+], AttributeSanitizerInterceptor);
+/**
+ * @UseAttributeSanitizer
+ *
+ * Convenience decorator that applies the AttributeSanitizerInterceptor
+ * to a route or controller.
+ *
+ * @param keys - One or more keys to remove from all response objects.
+ * @param mongooseToObjectOptions - Options for Mongoose `.toObject()` normalization.
+ */
+function UseAttributeSanitizer(keys, mongooseToObjectOptions) {
+    return (0, common_1.UseInterceptors)(new AttributeSanitizerInterceptor(keys, mongooseToObjectOptions));
+}