@cyberskill/shared 3.3.0 → 3.5.0

package/dist/node/mongo/mongo.controller.native.js.map

@@ -1 +1 @@
-{"version":3,"file":"mongo.controller.native.js","names":[],"sources":["../../../src/node/mongo/mongo.controller.native.ts"],"sourcesContent":["import type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { C_Collection, C_Db, C_Document, T_DeleteResult, T_Filter, T_OptionalUnlessRequiredId, T_UpdateResult, T_WithId } from './mongo.type.js';\n\nimport { catchError } from '../log/index.js';\nimport { mongo } from './mongo.util.js';\n\n/**\n * MongoDB native driver controller for direct database operations.\n * This class provides a simplified interface for MongoDB operations using the native driver,\n * with automatic generic field generation and standardized response formatting.\n */\nexport class MongoController<D extends Partial<C_Document>> {\n    private collection: C_Collection<D>;\n\n    /**\n     * Creates a new MongoDB controller instance.\n     *\n     * @param db - The MongoDB database instance.\n     * @param collectionName - The name of the collection to operate on.\n     */\n    constructor(db: C_Db, collectionName: string) {\n        this.collection = db.collection<D>(collectionName);\n    }\n\n    /**\n     * Creates a single document in the collection.\n     * This method adds generic fields (id, isDel, timestamps) to the document before insertion.\n     *\n     * @param document - The document to create, with or without generic fields.\n     * @returns A promise that resolves to a standardized response with the created document.\n     */\n    async createOne(document: D | Partial<D>): Promise<I_Return<D | Partial<D>>> {\n        try {\n            const finalDocument = {\n                ...mongo.createGenericFields(),\n                ...document,\n            };\n\n            const result = await this.collection.insertOne(finalDocument as unknown as T_OptionalUnlessRequiredId<D>);\n\n            if (!result.acknowledged) {\n                return {\n                    success: false,\n                    message: 'Document creation failed',\n                    code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Document created successfully',\n                result: finalDocument,\n            };\n        }\n        catch (error) {\n            return catchError<(D | Partial<D>)>(error);\n        }\n    }\n\n    /**\n     * Creates multiple documents in the collection.\n     * This method adds generic fields to each document before bulk insertion.\n     *\n     * @param documents - An array of documents to create.\n     * @returns A promise that resolves to a standardized response with the created documents.\n     */\n    async createMany(documents: (D | Partial<D>)[]): Promise<I_Return<(D | Partial<D>)[]>> {\n        try {\n            const finalDocuments = documents.map(document => ({\n                ...mongo.createGenericFields(),\n                ...document,\n            }));\n\n            const result = await this.collection.insertMany(finalDocuments as unknown as T_OptionalUnlessRequiredId<D>[]);\n\n            if (result.insertedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents were inserted',\n                    code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: `${result.insertedCount} documents created successfully`,\n                result: finalDocuments,\n            };\n        }\n        catch (error) {\n            return catchError<(D | Partial<D>)[]>(error);\n        }\n    }\n\n    /**\n     * Finds a single document by filter criteria.\n     *\n     * @param filter - The filter criteria to find the document.\n     * @returns A promise that resolves to a standardized response with the found document.\n     */\n    async findOne(filter: T_Filter<D>): Promise<I_Return<T_WithId<D>>> {\n        try {\n            const result = await this.collection.findOne(filter, { maxTimeMS: 30_000 });\n\n            if (!result) {\n                return { success: false, message: 'Document not found', code: RESPONSE_STATUS.NOT_FOUND.CODE };\n            }\n\n            return { success: true, message: 'Document found', result };\n        }\n        catch (error) {\n            return catchError<T_WithId<D>>(error);\n        }\n    }\n\n    /**\n     * Finds all documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents (defaults to empty object for all documents).\n     * @returns A promise that resolves to a standardized response with the found documents.\n     */\n    async findAll(\n        filter: T_Filter<D> = {},\n    ): Promise<I_Return<T_WithId<D>[]>> {\n        try {\n            const result = await this.collection.find(filter).limit(10_000).maxTimeMS(30_000).toArray();\n\n            return {\n                success: true,\n                message: 'Documents retrieved successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_WithId<D>[]>(error);\n        }\n    }\n\n    /**\n     * Counts documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to count documents (defaults to empty object for all documents).\n     * @returns A promise that resolves to a standardized response with the document count.\n     */\n    async count(\n        filter: T_Filter<D> = {},\n    ): Promise<I_Return<number>> {\n        try {\n            const result = await this.collection.countDocuments(filter);\n\n            return {\n                success: true,\n                message: `${result} documents counted successfully`,\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<number>(error);\n        }\n    }\n\n    /**\n     * Updates a single document matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find the document to update.\n     * @param update - The update data to apply to the document.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateOne(\n        filter: T_Filter<D>,\n        update: Partial<D>,\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const result = await this.collection.updateOne(filter, {\n                $set: update,\n            });\n\n            if (result.matchedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n            return {\n                success: true,\n                message: 'Document updated successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Updates multiple documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents to update.\n     * @param update - The update data to apply to the documents.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateMany(\n        filter: T_Filter<D>,\n        update: Partial<D>,\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const result = await this.collection.updateMany(filter, {\n                $set: update,\n            });\n\n            if (result.matchedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Documents updated successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Deletes a single document matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find the document to delete.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteOne(\n        filter: T_Filter<D>,\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const result = await this.collection.deleteOne(filter);\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n            return {\n                success: true,\n                message: 'Document deleted successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n\n    /**\n     * Deletes multiple documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents to delete.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteMany(\n        filter: T_Filter<D>,\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const result = await this.collection.deleteMany(filter);\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Documents deleted successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"mongo.controller.native.js","names":[],"sources":["../../../src/node/mongo/mongo.controller.native.ts"],"sourcesContent":["import type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { C_Collection, C_Db, C_Document, T_DeleteResult, T_Filter, T_OptionalUnlessRequiredId, T_UpdateResult, T_WithId } from './mongo.type.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { mongo } from './mongo.util.js';\n\n/**\n * MongoDB native driver controller for direct database operations.\n * This class provides a simplified interface for MongoDB operations using the native driver,\n * with automatic generic field generation and standardized response formatting.\n *\n * @see I_MongoController for the shared polymorphic interface (use via type assertion when needed).\n */\nexport class MongoController<D extends Partial<C_Document>> {\n    private collection: C_Collection<D>;\n    private defaultLimit: number;\n    private collectionName: string;\n\n    /**\n     * Creates a new MongoDB controller instance.\n     *\n     * @param db - The MongoDB database instance.\n     * @param collectionName - The name of the collection to operate on.\n     * @param options - Optional configuration for the controller.\n     * @param options.defaultLimit - Maximum documents returned by findAll when no limit is specified (default: 10,000).\n     */\n    constructor(db: C_Db, collectionName: string, options?: { defaultLimit?: number }) {\n        this.collection = db.collection<D>(collectionName);\n        this.collectionName = collectionName;\n        this.defaultLimit = options?.defaultLimit ?? 10_000;\n    }\n\n    /**\n     * Creates a single document in the collection.\n     * This method adds generic fields (id, isDel, timestamps) to the document before insertion.\n     *\n     * @param document - The document to create, with or without generic fields.\n     * @returns A promise that resolves to a standardized response with the created document.\n     */\n    async createOne(document: D | Partial<D>): Promise<I_Return<D | Partial<D>>> {\n        try {\n            const finalDocument = {\n                ...mongo.createGenericFields(),\n                ...document,\n            };\n\n            const result = await this.collection.insertOne(finalDocument as unknown as T_OptionalUnlessRequiredId<D>);\n\n            if (!result.acknowledged) {\n                return {\n                    success: false,\n                    message: 'Document creation failed',\n                    code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Document created successfully',\n                result: finalDocument,\n            };\n        }\n        catch (error) {\n            return catchError<(D | Partial<D>)>(error);\n        }\n    }\n\n    /**\n     * Creates multiple documents in the collection.\n     * This method adds generic fields to each document before bulk insertion.\n     *\n     * @param documents - An array of documents to create.\n     * @returns A promise that resolves to a standardized response with the created documents.\n     */\n    async createMany(documents: (D | Partial<D>)[]): Promise<I_Return<(D | Partial<D>)[]>> {\n        try {\n            const finalDocuments = documents.map(document => ({\n                ...mongo.createGenericFields(),\n                ...document,\n            }));\n\n            const result = await this.collection.insertMany(finalDocuments as unknown as T_OptionalUnlessRequiredId<D>[]);\n\n            if (result.insertedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents were inserted',\n                    code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: `${result.insertedCount} documents created successfully`,\n                result: finalDocuments,\n            };\n        }\n        catch (error) {\n            return catchError<(D | Partial<D>)[]>(error);\n        }\n    }\n\n    /**\n     * Finds a single document by filter criteria.\n     *\n     * @param filter - The filter criteria to find the document.\n     * @returns A promise that resolves to a standardized response with the found document.\n     */\n    async findOne(filter: T_Filter<D>): Promise<I_Return<T_WithId<D>>> {\n        try {\n            const result = await this.collection.findOne(filter, { maxTimeMS: 30_000 });\n\n            if (!result) {\n                return { success: false, message: 'Document not found', code: RESPONSE_STATUS.NOT_FOUND.CODE };\n            }\n\n            return { success: true, message: 'Document found', result };\n        }\n        catch (error) {\n            return catchError<T_WithId<D>>(error);\n        }\n    }\n\n    /**\n     * Finds all documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents (defaults to empty object for all documents).\n     * @returns A promise that resolves to a standardized response with the found documents.\n     */\n    async findAll(\n        filter: T_Filter<D> = {},\n    ): Promise<I_Return<T_WithId<D>[]>> {\n        try {\n            const result = await this.collection.find(filter).limit(this.defaultLimit).maxTimeMS(30_000).toArray();\n\n            if (result.length === this.defaultLimit) {\n                log.warn(`[${this.collectionName}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`);\n            }\n\n            return {\n                success: true,\n                message: 'Documents retrieved successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_WithId<D>[]>(error);\n        }\n    }\n\n    /**\n     * Counts documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to count documents (defaults to empty object for all documents).\n     * @returns A promise that resolves to a standardized response with the document count.\n     */\n    async count(\n        filter: T_Filter<D> = {},\n    ): Promise<I_Return<number>> {\n        try {\n            const result = await this.collection.countDocuments(filter);\n\n            return {\n                success: true,\n                message: `${result} documents counted successfully`,\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<number>(error);\n        }\n    }\n\n    /**\n     * Updates a single document matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find the document to update.\n     * @param update - The update data to apply to the document.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateOne(\n        filter: T_Filter<D>,\n        update: Partial<D>,\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const result = await this.collection.updateOne(filter, {\n                $set: update,\n            });\n\n            if (result.matchedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n            return {\n                success: true,\n                message: 'Document updated successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Updates multiple documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents to update.\n     * @param update - The update data to apply to the documents.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateMany(\n        filter: T_Filter<D>,\n        update: Partial<D>,\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const result = await this.collection.updateMany(filter, {\n                $set: update,\n            });\n\n            if (result.matchedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Documents updated successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Deletes a single document matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find the document to delete.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteOne(\n        filter: T_Filter<D>,\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const result = await this.collection.deleteOne(filter);\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n            return {\n                success: true,\n                message: 'Document deleted successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n\n    /**\n     * Deletes multiple documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to find documents to delete.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteMany(\n        filter: T_Filter<D>,\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const result = await this.collection.deleteMany(filter);\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: 'No documents matched the filter',\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return {\n                success: true,\n                message: 'Documents deleted successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n}\n"],"mappings":"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"}

package/dist/node/mongo/mongo.controller.type.d.ts

@@ -0,0 +1,76 @@
+import { I_Return } from '../../typescript/index.js';
+import { T_DeleteResult, T_UpdateResult, T_WithId } from './mongo.type.js';
+/**
+ * Shared controller interface for MongoDB operations.
+ * Both `MongooseController` and `MongoController` implement this interface,
+ * enabling polymorphic usage and dependency injection.
+ *
+ * @template T - The document type for the collection.
+ */
+export interface I_MongoController<T> {
+    /**
+     * Creates a single document in the collection.
+     *
+     * @param document - The document to create.
+     * @returns A standardized response with the created document.
+     */
+    createOne: (document: T | Partial<T>) => Promise<I_Return<T | Partial<T>>>;
+    /**
+     * Creates multiple documents in the collection.
+     *
+     * @param documents - The documents to create.
+     * @returns A standardized response with the created documents.
+     */
+    createMany: (documents: (T | Partial<T>)[]) => Promise<I_Return<(T | Partial<T>)[]>>;
+    /**
+     * Finds a single document matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @returns A standardized response with the found document.
+     */
+    findOne: (filter?: unknown) => Promise<I_Return<T | T_WithId<T>>>;
+    /**
+     * Finds all documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @returns A standardized response with the found documents.
+     */
+    findAll: (filter?: unknown) => Promise<I_Return<T[] | T_WithId<T>[]>>;
+    /**
+     * Counts documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @returns A standardized response with the document count.
+     */
+    count: (filter?: unknown) => Promise<I_Return<number>>;
+    /**
+     * Updates a single document matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @param update - The update data.
+     * @returns A standardized response with the update result.
+     */
+    updateOne: (filter: unknown, update: unknown) => Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Updates multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @param update - The update data.
+     * @returns A standardized response with the update result.
+     */
+    updateMany: (filter: unknown, update: unknown) => Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Deletes a single document matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @returns A standardized response with the delete result.
+     */
+    deleteOne: (filter: unknown) => Promise<I_Return<T_DeleteResult>>;
+    /**
+     * Deletes multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria.
+     * @returns A standardized response with the delete result.
+     */
+    deleteMany: (filter: unknown) => Promise<I_Return<T_DeleteResult>>;
+}

package/dist/node/mongo/mongo.dynamic-populate.d.ts

@@ -1,4 +1,5 @@
 import { default as mongooseRaw } from 'mongoose';
+import { I_ModelWithSchema } from './mongo.internal-types.js';
 import { I_DynamicVirtualConfig, I_DynamicVirtualOptions, T_Input_Populate } from './mongo.type.js';
 /**
  * Checks if value is object-like (e.g., objects, arrays, etc.), not null.
@@ -58,4 +59,4 @@ export declare function isMongooseDoc(obj: unknown): obj is {
  * @param {Record<string, 0 | 1>} [projection] - Optional projection for population queries
  * @returns {Promise<object[]>} The array of documents with dynamic virtuals populated
  */
-export declare function populateDynamicVirtuals<T extends object, R extends string = string>(mongoose: typeof mongooseRaw, documents: T[], virtualConfigs: I_DynamicVirtualConfig<T, R>[], populate?: T_Input_Populate, projection?: Record<string, 0 | 1>, startModel?: any): Promise<T[]>;
+export declare function populateDynamicVirtuals<T extends object, R extends string = string>(mongoose: typeof mongooseRaw, documents: T[], virtualConfigs: I_DynamicVirtualConfig<T, R>[], populate?: T_Input_Populate, projection?: Record<string, 0 | 1>, startModel?: I_ModelWithSchema): Promise<T[]>;

package/dist/node/mongo/mongo.dynamic-populate.js

@@ -69,22 +69,22 @@ async function c(t, n, i, a, c, l) {
 		return !1;
 	});
 	if (u.length === 0) return n;
-	let d = e(n.map((e) => s(e) ? e.toObject() : e));
-	d.forEach((e) => {
+	let d = n.map((e) => s(e) ? e.toObject() : e), f = d.some((e) => s(e)) ? d : e(d);
+	f.forEach((e) => {
 		u.forEach(({ name: t, options: n }) => {
 			t in e || (e[t] = n.count ? 0 : n.justOne ? null : []);
 		});
 	});
-	let f = /* @__PURE__ */ new Map();
+	let p = /* @__PURE__ */ new Map();
 	for (let e of u) {
-		let { name: t, options: n } = e, r = o(d, t, n);
+		let { name: t, options: n } = e, r = o(f, t, n);
 		for (let i of r) {
-			f.has(i.model) || f.set(i.model, {
+			p.has(i.model) || p.set(i.model, {
 				virtuals: [],
 				localValueSets: /* @__PURE__ */ new Map(),
 				docsByLocalValue: /* @__PURE__ */ new Map()
 			});
-			let r = f.get(i.model);
+			let r = p.get(i.model);
 			r.virtuals.some((e) => e.name === t) || (r.virtuals.push(e), r.localValueSets.set(t, /* @__PURE__ */ new Set()));
 			let a = r.localValueSets.get(t);
 			i.docs.forEach((e) => {
@@ -93,12 +93,12 @@ async function c(t, n, i, a, c, l) {
 					let n = String(t);
 					a.add(n);
 					let i = -1, o = e;
-					o.id === void 0 ? o._id !== void 0 && (i = d.findIndex((e) => e._id?.toString?.() === o._id?.toString?.())) : i = d.findIndex((e) => e.id === o.id), i !== -1 && (r.docsByLocalValue.has(n) || r.docsByLocalValue.set(n, []), r.docsByLocalValue.get(n).push(i));
+					o.id === void 0 ? o._id !== void 0 && (i = f.findIndex((e) => e._id?.toString?.() === o._id?.toString?.())) : i = f.findIndex((e) => e.id === o.id), i !== -1 && (r.docsByLocalValue.has(n) || r.docsByLocalValue.set(n, []), r.docsByLocalValue.get(n).push(i));
 				}
 			});
 		}
 	}
-	return await Promise.all(Array.from(f.entries(), async ([e, n]) => {
+	return await Promise.all(Array.from(p.entries(), async ([e, n]) => {
 		let r = t.models[e];
 		if (!r) return;
 		let i = /* @__PURE__ */ new Set();
@@ -121,7 +121,7 @@ async function c(t, n, i, a, c, l) {
 				}), n.localValueSets.get(t).forEach((r) => {
 					let i = n.docsByLocalValue.get(r) || [], a = e.get(r) || 0;
 					i.forEach((e) => {
-						let n = d[e];
+						let n = f[e];
 						n[t] === void 0 && (n[t] = a);
 					});
 				});
@@ -133,13 +133,13 @@ async function c(t, n, i, a, c, l) {
 				}), n.localValueSets.get(t).forEach((i) => {
 					let a = n.docsByLocalValue.get(i) || [], o = e.get(i) || [], s = r.justOne ? o[0] || null : o;
 					a.forEach((e) => {
-						let n = d[e];
+						let n = f[e];
 						n[t] = s;
 					});
 				});
 			}
 		}
-	})), a && await r(t, d, ((e) => {
+	})), a && await r(t, f, ((e) => {
 		let t = Array.isArray(e) ? e : [e], n = /* @__PURE__ */ new Map(), r = [];
 		for (let e of t) if (typeof e == "string") if (e.includes(".")) {
 			let t = e.split("."), r = t[0] || "", i = t.slice(1).join(".");
@@ -161,7 +161,7 @@ async function c(t, n, i, a, c, l) {
 				populate: n
 			} : t);
 		}), i;
-	})(a), i, l), d;
+	})(a), i, l), f;
 }
 //#endregion
 export { a as filterDynamicVirtualsFromPopulate, s as isMongooseDoc, i as isObject, c as populateDynamicVirtuals, o as remapDynamicPopulate };

package/dist/node/mongo/mongo.dynamic-populate.js.map

@@ -1 +1 @@
-{"version":3,"file":"mongo.dynamic-populate.js","names":[],"sources":["../../../src/node/mongo/mongo.dynamic-populate.ts"],"sourcesContent":["import type mongooseRaw from 'mongoose';\n\nimport { deepClone } from '#util/index.js';\n\nimport type { I_DynamicVirtualConfig, I_DynamicVirtualOptions, T_Input_Populate } from './mongo.type.js';\n\nimport { catchError } from '../log/index.js';\nimport { applyNestedPopulate } from './mongo.populate.js';\nimport { convertEnumToModelName } from './mongo.util.js';\n\n/**\n * Checks if value is object-like (e.g., objects, arrays, etc.), not null.\n */\nexport function isObject(value: unknown): value is object {\n    return value != null && typeof value === 'object';\n}\n\n/**\n * Filters out dynamic virtuals from populate options to prevent Mongoose from trying to populate them.\n * This function creates a new populate configuration that only includes regular virtuals.\n *\n * @template T - The document type\n * @param populate - The original populate options\n * @param dynamicVirtuals - Array of dynamic virtual configurations\n * @returns Filtered populate options excluding dynamic virtuals\n */\nexport function filterDynamicVirtualsFromPopulate<T>(\n    populate: T_Input_Populate | undefined,\n    dynamicVirtuals: I_DynamicVirtualConfig<T>[] | undefined,\n): T_Input_Populate | undefined {\n    if (!populate || !dynamicVirtuals || dynamicVirtuals.length === 0) {\n        return populate;\n    }\n\n    const dynamicVirtualNames = new Set(dynamicVirtuals.map(v => v.name));\n\n    if (Array.isArray(populate)) {\n        const filtered = populate.filter((p) => {\n            if (typeof p === 'string') {\n                return ![...dynamicVirtualNames].some(virtualName =>\n                    p === virtualName || p.startsWith(`${virtualName}.`),\n                );\n            }\n\n            if (typeof p === 'object' && p !== null) {\n                const popObj = p as { path?: string; populate?: string };\n                const path = popObj.path || popObj.populate || '';\n\n                return ![...dynamicVirtualNames].some(virtualName =>\n                    path === virtualName || path.startsWith(`${virtualName}.`),\n                );\n            }\n\n            return true;\n        });\n\n        return filtered.length > 0 ? (filtered as T_Input_Populate) : undefined;\n    }\n\n    if (typeof populate === 'string') {\n        return [...dynamicVirtualNames].some(virtualName =>\n            populate === virtualName || populate.startsWith(`${virtualName}.`),\n        )\n            ? undefined\n            : populate;\n    }\n\n    if (typeof populate === 'object' && populate !== null) {\n        const popObj = populate as { path?: string; populate?: string };\n        const path = popObj.path || popObj.populate || '';\n\n        return [...dynamicVirtualNames].some(virtualName =>\n            path === virtualName || path.startsWith(`${virtualName}.`),\n        )\n            ? undefined\n            : populate;\n    }\n\n    return populate;\n}\n\n/**\n * Groups documents by the resolved model name for a dynamic virtual field.\n * Used to batch population queries for dynamic virtuals.\n *\n * @template T - The document type\n * @template R - The model name type (usually string or enum)\n * @param {T[]} documents - The array of documents to process\n * @param {string} virtualName - The name of the dynamic virtual field\n * @param {I_DynamicVirtualOptions<T, R>} virtualOptions - The dynamic virtual options (must include a ref function)\n * @returns {Array<{ model: string; docs: T[] }>} An array of groups, each with a model name and the docs for that model\n */\nexport function remapDynamicPopulate<T, R extends string = string>(\n    documents: T[],\n    virtualName: string,\n    virtualOptions: I_DynamicVirtualOptions<T, R>,\n): Array<{ model: string; docs: T[] }> {\n    if (!documents.length || !virtualName || !virtualOptions?.ref) {\n        return [];\n    }\n\n    const modelGroups = new Map<string, T[]>();\n    documents.forEach((doc) => {\n        try {\n            const modelName = virtualOptions.ref(doc);\n\n            if (modelName === undefined || modelName === null) {\n                return;\n            }\n\n            const modelNameString = typeof modelName === 'string' ? modelName : String(modelName);\n\n            if (modelNameString && modelNameString.trim() !== '') {\n                const convertedModelName = convertEnumToModelName(modelNameString);\n\n                if (!modelGroups.has(convertedModelName)) {\n                    modelGroups.set(convertedModelName, []);\n                }\n\n                modelGroups.get(convertedModelName)!.push(doc);\n            }\n        }\n        catch (error) {\n            catchError(new Error(`Dynamic ref function failed for virtual \"${virtualName}\": ${error instanceof Error ? error.message : String(error)}`));\n        }\n    });\n\n    return Array.from(modelGroups.entries(), ([model, docs]) => ({ model, docs }));\n}\n\n/**\n * Type guard to check if an object is a Mongoose Document (has toObject method).\n * @param obj - The object to check\n * @returns True if obj has a toObject function\n */\nexport function isMongooseDoc(obj: unknown): obj is { toObject: () => { [key: string]: unknown } } {\n    return obj !== null && typeof obj === 'object' && 'toObject' in obj && typeof (obj as { toObject: unknown }).toObject === 'function';\n}\n\n/**\n * Optimized batch population for dynamic virtuals.\n *\n * - Groups documents by model and batches queries for each model.\n * - Populates all dynamic virtuals in parallel for maximum performance.\n * - Uses direct assignment for plain objects and skips already populated fields.\n * - Supports optional projection for population queries.\n * - Only populates virtuals that are explicitly requested in populate options.\n * - Reminder: Ensure indexes exist on foreignField in referenced collections for best performance.\n *\n * @template T - The document type (must be an object)\n * @template R - The model name type (usually string or enum)\n * @param {typeof mongooseRaw} mongoose - The Mongoose instance\n * @param {T[]} documents - The array of documents to populate\n * @param {I_DynamicVirtualConfig<T, R>[]} virtualConfigs - The dynamic virtual configurations to process\n * @param {T_Input_Populate} [populate] - Population options to determine which virtuals to populate\n * @param {Record<string, 0 | 1>} [projection] - Optional projection for population queries\n * @returns {Promise<object[]>} The array of documents with dynamic virtuals populated\n */\nexport async function populateDynamicVirtuals<T extends object, R extends string = string>(\n    mongoose: typeof mongooseRaw,\n    documents: T[],\n    virtualConfigs: I_DynamicVirtualConfig<T, R>[],\n    populate?: T_Input_Populate,\n    projection?: Record<string, 0 | 1>,\n    startModel?: any,\n): Promise<T[]> {\n    if (!documents.length || !virtualConfigs.length) {\n        return documents;\n    }\n\n    if (!populate) {\n        return documents;\n    }\n\n    const requestedVirtuals = virtualConfigs.filter((config) => {\n        if (Array.isArray(populate)) {\n            return populate.length > 0 && populate.some((p) => {\n                if (typeof p === 'string') {\n                    return p === config.name || p.startsWith(`${config.name}.`);\n                }\n                if (p && typeof p === 'object') {\n                    const popObj = p as { path?: string; populate?: string };\n                    const path = popObj.path || popObj.populate || '';\n\n                    return path === config.name || path.startsWith(`${config.name}.`);\n                }\n\n                return false;\n            });\n        }\n\n        if (typeof populate === 'string') {\n            return populate === config.name || populate.startsWith(`${config.name}.`);\n        }\n\n        if (typeof populate === 'object' && populate !== null) {\n            const popObj = populate as { path?: string; populate?: string };\n            const path = popObj.path || popObj.populate || '';\n\n            return (path === config.name) || path.startsWith(`${config.name}.`);\n        }\n\n        return false;\n    });\n\n    if (requestedVirtuals.length === 0) {\n        return documents;\n    }\n\n    const clonedDocuments = deepClone(documents.map(doc => isMongooseDoc(doc) ? doc.toObject() : doc)) as T[];\n\n    clonedDocuments.forEach((doc) => {\n        requestedVirtuals.forEach(({ name, options }) => {\n            if (!(name in doc)) {\n                (doc as { [key: string]: unknown })[name as string] = options.count ? 0 : (options.justOne ? null : []);\n            }\n        });\n    });\n\n    const modelProcessingMap = new Map<string, {\n        virtuals: I_DynamicVirtualConfig<T, R>[];\n        localValueSets: Map<string, Set<string>>;\n        docsByLocalValue: Map<string, number[]>;\n    }>();\n\n    for (const virtualConfig of requestedVirtuals) {\n        const { name, options } = virtualConfig;\n        const populateGroups = remapDynamicPopulate(clonedDocuments, name, options);\n\n        for (const group of populateGroups) {\n            if (!modelProcessingMap.has(group.model)) {\n                modelProcessingMap.set(group.model, {\n                    virtuals: [],\n                    localValueSets: new Map(),\n                    docsByLocalValue: new Map(),\n                });\n            }\n\n            const processing = modelProcessingMap.get(group.model)!;\n\n            if (!processing.virtuals.some(v => v.name === name)) {\n                processing.virtuals.push(virtualConfig);\n                processing.localValueSets.set(name as string, new Set());\n            }\n\n            const localValueSet = processing.localValueSets.get(name as string)!;\n            group.docs.forEach((doc) => {\n                const localVal = (doc as { [key: string]: unknown })[options.localField];\n\n                if (localVal != null) {\n                    const strVal = String(localVal);\n                    localValueSet.add(strVal);\n\n                    let idx = -1;\n\n                    const docWithKeys = doc as { [key: string]: unknown };\n\n                    if (docWithKeys['id'] !== undefined) {\n                        idx = clonedDocuments.findIndex((d) => {\n                            const dWithKeys = d as { [key: string]: unknown };\n\n                            return dWithKeys['id'] === docWithKeys['id'];\n                        });\n                    }\n                    else if (docWithKeys['_id'] !== undefined) {\n                        idx = clonedDocuments.findIndex((d) => {\n                            const dWithKeys = d as { [key: string]: unknown };\n\n                            return dWithKeys['_id']?.toString?.() === docWithKeys['_id']?.toString?.();\n                        });\n                    }\n\n                    if (idx !== -1) {\n                        if (!processing.docsByLocalValue.has(strVal)) {\n                            processing.docsByLocalValue.set(strVal, []);\n                        }\n                        processing.docsByLocalValue.get(strVal)!.push(idx);\n                    }\n                }\n            });\n        }\n    }\n\n    await Promise.all(Array.from(modelProcessingMap.entries(), async ([modelName, processing]) => {\n        const Model = mongoose.models[modelName];\n\n        if (!Model) {\n            return;\n        }\n\n        const allLocalValues = new Set<string>();\n        processing.localValueSets.forEach((localValueSet) => {\n            localValueSet.forEach(val => allLocalValues.add(val));\n        });\n\n        if (allLocalValues.size === 0) {\n            return;\n        }\n\n        const foreignFields = [...new Set(processing.virtuals.map(v => v.options.foreignField))];\n        const localValuesArray = [...allLocalValues];\n        let query;\n\n        if (foreignFields.length === 1) {\n            query = { [String(foreignFields[0])]: { $in: localValuesArray } };\n        }\n        else {\n            query = { $or: foreignFields.map(field => ({ [field]: { $in: localValuesArray } })) };\n        }\n\n        const allPopulatedData = await Model.find(query, projection).lean();\n\n        for (const virtualConfig of processing.virtuals) {\n            const { name, options } = virtualConfig;\n            const relevantData = allPopulatedData.filter((item) => {\n                const foreignVal = (item)[options.foreignField];\n\n                return foreignVal != null && allLocalValues.has(String(foreignVal));\n            });\n\n            if (options.count) {\n                const countMap = new Map<string, number>();\n\n                relevantData.forEach((item) => {\n                    const key = (item)[options.foreignField]?.toString();\n\n                    if (key) {\n                        countMap.set(key, (countMap.get(key) || 0) + 1);\n                    }\n                });\n\n                processing.localValueSets.get(name as string)!.forEach((localValue) => {\n                    const docs = processing.docsByLocalValue.get(localValue) || [];\n                    const count = countMap.get(localValue) || 0;\n\n                    docs.forEach((idx) => {\n                        const docToUpdate = clonedDocuments[idx] as { [key: string]: unknown };\n\n                        if (docToUpdate[name] === undefined) {\n                            docToUpdate[name] = count;\n                        }\n                    });\n                });\n            }\n            else {\n                const resultMap = new Map<string, T[]>();\n\n                relevantData.forEach((item) => {\n                    const key = (item)[options.foreignField]?.toString();\n\n                    if (key) {\n                        if (!resultMap.has(key)) {\n                            resultMap.set(key, []);\n                        }\n                        resultMap.get(key)!.push(item);\n                    }\n                });\n\n                processing.localValueSets.get(name as string)!.forEach((localVal) => {\n                    const docs = processing.docsByLocalValue.get(localVal) || [];\n                    const results = resultMap.get(localVal) || [];\n                    const value = options.justOne ? (results[0] || null) : results;\n\n                    docs.forEach((idx) => {\n                        const docToUpdate = clonedDocuments[idx] as { [key: string]: unknown };\n                        docToUpdate[name] = value;\n                    });\n                });\n            }\n        }\n    }));\n\n    if (populate) {\n        const normalizePopulate = (pop: T_Input_Populate): T_Input_Populate => {\n            const asArray = Array.isArray(pop) ? pop : [pop];\n            const grouped = new Map<string, any[]>();\n            const passthrough: any[] = [];\n\n            for (const entry of asArray) {\n                if (typeof entry === 'string') {\n                    if (entry.includes('.')) {\n                        const parts = entry.split('.');\n                        const first = parts[0] || '';\n                        const rest = parts.slice(1).join('.');\n\n                        if (first) {\n                            if (!grouped.has(first)) {\n                                grouped.set(first, []);\n                            }\n                            if (rest) {\n                                grouped.get(first)!.push(rest);\n                            }\n                        }\n                    }\n                    else {\n                        passthrough.push(entry);\n                    }\n                }\n                else if (entry && typeof entry === 'object') {\n                    const obj = entry as { path?: string; populate?: T_Input_Populate };\n\n                    if (obj.path && obj.path.includes('.')) {\n                        const parts = obj.path.split('.');\n                        const first = parts[0] || '';\n                        const rest = parts.slice(1).join('.');\n\n                        if (first) {\n                            if (!grouped.has(first)) {\n                                grouped.set(first, []);\n                            }\n                            if (rest) {\n                                grouped.get(first)!.push(rest);\n                            }\n                            if (obj.populate) {\n                                grouped.get(first)!.push(obj.populate as unknown as any);\n                            }\n                        }\n                    }\n                    else {\n                        passthrough.push(entry as any);\n                    }\n                }\n            }\n\n            const normalized: any[] = [...passthrough];\n            grouped.forEach((nested, root) => {\n                const flat: any[] = [];\n\n                for (const n of nested) {\n                    if (typeof n === 'string') {\n                        flat.push(n);\n                    }\n                    else if (n && typeof n === 'object') {\n                        flat.push(n);\n                    }\n                }\n                if (flat.length > 0) {\n                    normalized.push({ path: root as string, populate: flat as unknown as T_Input_Populate });\n                }\n                else {\n                    normalized.push(root);\n                }\n            });\n\n            return normalized as unknown as T_Input_Populate;\n        };\n\n        const normalizedPopulate = normalizePopulate(populate);\n\n        await applyNestedPopulate(mongoose, clonedDocuments, normalizedPopulate, virtualConfigs as I_DynamicVirtualConfig<unknown, string>[], startModel);\n    }\n\n    return clonedDocuments;\n}\n"],"mappings":"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"}
+{"version":3,"file":"mongo.dynamic-populate.js","names":[],"sources":["../../../src/node/mongo/mongo.dynamic-populate.ts"],"sourcesContent":["import type mongooseRaw from 'mongoose';\n\nimport { deepClone } from '#util/index.js';\n\nimport type { I_ModelWithSchema } from './mongo.internal-types.js';\nimport type { I_DynamicVirtualConfig, I_DynamicVirtualOptions, T_Input_Populate } from './mongo.type.js';\n\nimport { catchError } from '../log/index.js';\nimport { applyNestedPopulate } from './mongo.populate.js';\nimport { convertEnumToModelName } from './mongo.util.js';\n\n/**\n * Checks if value is object-like (e.g., objects, arrays, etc.), not null.\n */\nexport function isObject(value: unknown): value is object {\n    return value != null && typeof value === 'object';\n}\n\n/**\n * Filters out dynamic virtuals from populate options to prevent Mongoose from trying to populate them.\n * This function creates a new populate configuration that only includes regular virtuals.\n *\n * @template T - The document type\n * @param populate - The original populate options\n * @param dynamicVirtuals - Array of dynamic virtual configurations\n * @returns Filtered populate options excluding dynamic virtuals\n */\nexport function filterDynamicVirtualsFromPopulate<T>(\n    populate: T_Input_Populate | undefined,\n    dynamicVirtuals: I_DynamicVirtualConfig<T>[] | undefined,\n): T_Input_Populate | undefined {\n    if (!populate || !dynamicVirtuals || dynamicVirtuals.length === 0) {\n        return populate;\n    }\n\n    const dynamicVirtualNames = new Set(dynamicVirtuals.map(v => v.name));\n\n    if (Array.isArray(populate)) {\n        const filtered = populate.filter((p) => {\n            if (typeof p === 'string') {\n                return ![...dynamicVirtualNames].some(virtualName =>\n                    p === virtualName || p.startsWith(`${virtualName}.`),\n                );\n            }\n\n            if (typeof p === 'object' && p !== null) {\n                const popObj = p as { path?: string; populate?: string };\n                const path = popObj.path || popObj.populate || '';\n\n                return ![...dynamicVirtualNames].some(virtualName =>\n                    path === virtualName || path.startsWith(`${virtualName}.`),\n                );\n            }\n\n            return true;\n        });\n\n        return filtered.length > 0 ? (filtered as T_Input_Populate) : undefined;\n    }\n\n    if (typeof populate === 'string') {\n        return [...dynamicVirtualNames].some(virtualName =>\n            populate === virtualName || populate.startsWith(`${virtualName}.`),\n        )\n            ? undefined\n            : populate;\n    }\n\n    if (typeof populate === 'object' && populate !== null) {\n        const popObj = populate as { path?: string; populate?: string };\n        const path = popObj.path || popObj.populate || '';\n\n        return [...dynamicVirtualNames].some(virtualName =>\n            path === virtualName || path.startsWith(`${virtualName}.`),\n        )\n            ? undefined\n            : populate;\n    }\n\n    return populate;\n}\n\n/**\n * Groups documents by the resolved model name for a dynamic virtual field.\n * Used to batch population queries for dynamic virtuals.\n *\n * @template T - The document type\n * @template R - The model name type (usually string or enum)\n * @param {T[]} documents - The array of documents to process\n * @param {string} virtualName - The name of the dynamic virtual field\n * @param {I_DynamicVirtualOptions<T, R>} virtualOptions - The dynamic virtual options (must include a ref function)\n * @returns {Array<{ model: string; docs: T[] }>} An array of groups, each with a model name and the docs for that model\n */\nexport function remapDynamicPopulate<T, R extends string = string>(\n    documents: T[],\n    virtualName: string,\n    virtualOptions: I_DynamicVirtualOptions<T, R>,\n): Array<{ model: string; docs: T[] }> {\n    if (!documents.length || !virtualName || !virtualOptions?.ref) {\n        return [];\n    }\n\n    const modelGroups = new Map<string, T[]>();\n    documents.forEach((doc) => {\n        try {\n            const modelName = virtualOptions.ref(doc);\n\n            if (modelName === undefined || modelName === null) {\n                return;\n            }\n\n            const modelNameString = typeof modelName === 'string' ? modelName : String(modelName);\n\n            if (modelNameString && modelNameString.trim() !== '') {\n                const convertedModelName = convertEnumToModelName(modelNameString);\n\n                if (!modelGroups.has(convertedModelName)) {\n                    modelGroups.set(convertedModelName, []);\n                }\n\n                modelGroups.get(convertedModelName)!.push(doc);\n            }\n        }\n        catch (error) {\n            catchError(new Error(`Dynamic ref function failed for virtual \"${virtualName}\": ${error instanceof Error ? error.message : String(error)}`));\n        }\n    });\n\n    return Array.from(modelGroups.entries(), ([model, docs]) => ({ model, docs }));\n}\n\n/**\n * Type guard to check if an object is a Mongoose Document (has toObject method).\n * @param obj - The object to check\n * @returns True if obj has a toObject function\n */\nexport function isMongooseDoc(obj: unknown): obj is { toObject: () => { [key: string]: unknown } } {\n    return obj !== null && typeof obj === 'object' && 'toObject' in obj && typeof (obj as { toObject: unknown }).toObject === 'function';\n}\n\n/**\n * Optimized batch population for dynamic virtuals.\n *\n * - Groups documents by model and batches queries for each model.\n * - Populates all dynamic virtuals in parallel for maximum performance.\n * - Uses direct assignment for plain objects and skips already populated fields.\n * - Supports optional projection for population queries.\n * - Only populates virtuals that are explicitly requested in populate options.\n * - Reminder: Ensure indexes exist on foreignField in referenced collections for best performance.\n *\n * @template T - The document type (must be an object)\n * @template R - The model name type (usually string or enum)\n * @param {typeof mongooseRaw} mongoose - The Mongoose instance\n * @param {T[]} documents - The array of documents to populate\n * @param {I_DynamicVirtualConfig<T, R>[]} virtualConfigs - The dynamic virtual configurations to process\n * @param {T_Input_Populate} [populate] - Population options to determine which virtuals to populate\n * @param {Record<string, 0 | 1>} [projection] - Optional projection for population queries\n * @returns {Promise<object[]>} The array of documents with dynamic virtuals populated\n */\nexport async function populateDynamicVirtuals<T extends object, R extends string = string>(\n    mongoose: typeof mongooseRaw,\n    documents: T[],\n    virtualConfigs: I_DynamicVirtualConfig<T, R>[],\n    populate?: T_Input_Populate,\n    projection?: Record<string, 0 | 1>,\n    startModel?: I_ModelWithSchema,\n): Promise<T[]> {\n    if (!documents.length || !virtualConfigs.length) {\n        return documents;\n    }\n\n    if (!populate) {\n        return documents;\n    }\n\n    const requestedVirtuals = virtualConfigs.filter((config) => {\n        if (Array.isArray(populate)) {\n            return populate.length > 0 && populate.some((p) => {\n                if (typeof p === 'string') {\n                    return p === config.name || p.startsWith(`${config.name}.`);\n                }\n                if (p && typeof p === 'object') {\n                    const popObj = p as { path?: string; populate?: string };\n                    const path = popObj.path || popObj.populate || '';\n\n                    return path === config.name || path.startsWith(`${config.name}.`);\n                }\n\n                return false;\n            });\n        }\n\n        if (typeof populate === 'string') {\n            return populate === config.name || populate.startsWith(`${config.name}.`);\n        }\n\n        if (typeof populate === 'object' && populate !== null) {\n            const popObj = populate as { path?: string; populate?: string };\n            const path = popObj.path || popObj.populate || '';\n\n            return (path === config.name) || path.startsWith(`${config.name}.`);\n        }\n\n        return false;\n    });\n\n    if (requestedVirtuals.length === 0) {\n        return documents;\n    }\n\n    // Only deepClone documents that need it. toObject() already creates a plain copy,\n    // so we avoid redundant deep cloning for Mongoose documents.\n    const plainDocuments = documents.map(doc => isMongooseDoc(doc) ? doc.toObject() : doc);\n    const clonedDocuments = plainDocuments.some(doc => isMongooseDoc(doc)) ? plainDocuments as T[] : deepClone(plainDocuments) as T[];\n\n    clonedDocuments.forEach((doc) => {\n        requestedVirtuals.forEach(({ name, options }) => {\n            if (!(name in doc)) {\n                (doc as { [key: string]: unknown })[name as string] = options.count ? 0 : (options.justOne ? null : []);\n            }\n        });\n    });\n\n    const modelProcessingMap = new Map<string, {\n        virtuals: I_DynamicVirtualConfig<T, R>[];\n        localValueSets: Map<string, Set<string>>;\n        docsByLocalValue: Map<string, number[]>;\n    }>();\n\n    for (const virtualConfig of requestedVirtuals) {\n        const { name, options } = virtualConfig;\n        const populateGroups = remapDynamicPopulate(clonedDocuments, name, options);\n\n        for (const group of populateGroups) {\n            if (!modelProcessingMap.has(group.model)) {\n                modelProcessingMap.set(group.model, {\n                    virtuals: [],\n                    localValueSets: new Map(),\n                    docsByLocalValue: new Map(),\n                });\n            }\n\n            const processing = modelProcessingMap.get(group.model)!;\n\n            if (!processing.virtuals.some(v => v.name === name)) {\n                processing.virtuals.push(virtualConfig);\n                processing.localValueSets.set(name as string, new Set());\n            }\n\n            const localValueSet = processing.localValueSets.get(name as string)!;\n            group.docs.forEach((doc) => {\n                const localVal = (doc as { [key: string]: unknown })[options.localField];\n\n                if (localVal != null) {\n                    const strVal = String(localVal);\n                    localValueSet.add(strVal);\n\n                    let idx = -1;\n\n                    const docWithKeys = doc as { [key: string]: unknown };\n\n                    if (docWithKeys['id'] !== undefined) {\n                        idx = clonedDocuments.findIndex((d) => {\n                            const dWithKeys = d as { [key: string]: unknown };\n\n                            return dWithKeys['id'] === docWithKeys['id'];\n                        });\n                    }\n                    else if (docWithKeys['_id'] !== undefined) {\n                        idx = clonedDocuments.findIndex((d) => {\n                            const dWithKeys = d as { [key: string]: unknown };\n\n                            return dWithKeys['_id']?.toString?.() === docWithKeys['_id']?.toString?.();\n                        });\n                    }\n\n                    if (idx !== -1) {\n                        if (!processing.docsByLocalValue.has(strVal)) {\n                            processing.docsByLocalValue.set(strVal, []);\n                        }\n                        processing.docsByLocalValue.get(strVal)!.push(idx);\n                    }\n                }\n            });\n        }\n    }\n\n    await Promise.all(Array.from(modelProcessingMap.entries(), async ([modelName, processing]) => {\n        const Model = mongoose.models[modelName];\n\n        if (!Model) {\n            return;\n        }\n\n        const allLocalValues = new Set<string>();\n        processing.localValueSets.forEach((localValueSet) => {\n            localValueSet.forEach(val => allLocalValues.add(val));\n        });\n\n        if (allLocalValues.size === 0) {\n            return;\n        }\n\n        const foreignFields = [...new Set(processing.virtuals.map(v => v.options.foreignField))];\n        const localValuesArray = [...allLocalValues];\n        let query;\n\n        if (foreignFields.length === 1) {\n            query = { [String(foreignFields[0])]: { $in: localValuesArray } };\n        }\n        else {\n            query = { $or: foreignFields.map(field => ({ [field]: { $in: localValuesArray } })) };\n        }\n\n        const allPopulatedData = await Model.find(query, projection).lean();\n\n        for (const virtualConfig of processing.virtuals) {\n            const { name, options } = virtualConfig;\n            const relevantData = allPopulatedData.filter((item) => {\n                const foreignVal = (item)[options.foreignField];\n\n                return foreignVal != null && allLocalValues.has(String(foreignVal));\n            });\n\n            if (options.count) {\n                const countMap = new Map<string, number>();\n\n                relevantData.forEach((item) => {\n                    const key = (item)[options.foreignField]?.toString();\n\n                    if (key) {\n                        countMap.set(key, (countMap.get(key) || 0) + 1);\n                    }\n                });\n\n                processing.localValueSets.get(name as string)!.forEach((localValue) => {\n                    const docs = processing.docsByLocalValue.get(localValue) || [];\n                    const count = countMap.get(localValue) || 0;\n\n                    docs.forEach((idx) => {\n                        const docToUpdate = clonedDocuments[idx] as { [key: string]: unknown };\n\n                        if (docToUpdate[name] === undefined) {\n                            docToUpdate[name] = count;\n                        }\n                    });\n                });\n            }\n            else {\n                const resultMap = new Map<string, T[]>();\n\n                relevantData.forEach((item) => {\n                    const key = (item)[options.foreignField]?.toString();\n\n                    if (key) {\n                        if (!resultMap.has(key)) {\n                            resultMap.set(key, []);\n                        }\n                        resultMap.get(key)!.push(item);\n                    }\n                });\n\n                processing.localValueSets.get(name as string)!.forEach((localVal) => {\n                    const docs = processing.docsByLocalValue.get(localVal) || [];\n                    const results = resultMap.get(localVal) || [];\n                    const value = options.justOne ? (results[0] || null) : results;\n\n                    docs.forEach((idx) => {\n                        const docToUpdate = clonedDocuments[idx] as { [key: string]: unknown };\n                        docToUpdate[name] = value;\n                    });\n                });\n            }\n        }\n    }));\n\n    if (populate) {\n        const normalizePopulate = (pop: T_Input_Populate): T_Input_Populate => {\n            const asArray = Array.isArray(pop) ? pop : [pop];\n            const grouped = new Map<string, unknown[]>();\n            const passthrough: unknown[] = [];\n\n            for (const entry of asArray) {\n                if (typeof entry === 'string') {\n                    if (entry.includes('.')) {\n                        const parts = entry.split('.');\n                        const first = parts[0] || '';\n                        const rest = parts.slice(1).join('.');\n\n                        if (first) {\n                            if (!grouped.has(first)) {\n                                grouped.set(first, []);\n                            }\n                            if (rest) {\n                                grouped.get(first)!.push(rest);\n                            }\n                        }\n                    }\n                    else {\n                        passthrough.push(entry);\n                    }\n                }\n                else if (entry && typeof entry === 'object') {\n                    const obj = entry as { path?: string; populate?: T_Input_Populate };\n\n                    if (obj.path && obj.path.includes('.')) {\n                        const parts = obj.path.split('.');\n                        const first = parts[0] || '';\n                        const rest = parts.slice(1).join('.');\n\n                        if (first) {\n                            if (!grouped.has(first)) {\n                                grouped.set(first, []);\n                            }\n                            if (rest) {\n                                grouped.get(first)!.push(rest);\n                            }\n                            if (obj.populate) {\n                                grouped.get(first)!.push(obj.populate);\n                            }\n                        }\n                    }\n                    else {\n                        passthrough.push(entry);\n                    }\n                }\n            }\n\n            const normalized: unknown[] = [...passthrough];\n            grouped.forEach((nested, root) => {\n                const flat: unknown[] = [];\n\n                for (const n of nested) {\n                    if (typeof n === 'string') {\n                        flat.push(n);\n                    }\n                    else if (n && typeof n === 'object') {\n                        flat.push(n);\n                    }\n                }\n                if (flat.length > 0) {\n                    normalized.push({ path: root, populate: flat as unknown as T_Input_Populate });\n                }\n                else {\n                    normalized.push(root);\n                }\n            });\n\n            return normalized as unknown as T_Input_Populate;\n        };\n\n        const normalizedPopulate = normalizePopulate(populate);\n\n        await applyNestedPopulate(mongoose, clonedDocuments, normalizedPopulate, virtualConfigs as I_DynamicVirtualConfig<unknown, string>[], startModel);\n    }\n\n    return clonedDocuments;\n}\n"],"mappings":"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"}

package/dist/node/mongo/mongo.internal-types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Internal type definitions for the mongo module.
+ * These types are NOT part of the public API and are used for internal
+ * type safety across mongo utility and controller files.
+ */
+/**
+ * Represents a Mongoose Model-like object that has a schema with virtuals and paths.
+ * Used instead of `any` when traversing model references internally.
+ */
+export interface I_ModelWithSchema {
+    modelName?: string;
+    schema?: I_SchemaLike;
+    _virtualConfigs?: I_InternalVirtualConfig[];
+}
+/**
+ * Schema-like structure for internal traversal.
+ */
+export interface I_SchemaLike {
+    virtuals?: Record<string, I_SchemaVirtual>;
+    paths?: Record<string, {
+        schema?: I_SchemaLike;
+        instance?: string;
+        [key: string]: unknown;
+    }>;
+    statics?: Record<string, unknown>;
+}
+/**
+ * A virtual field definition within a schema.
+ */
+export interface I_SchemaVirtual {
+    options?: {
+        ref?: string | ((doc: unknown) => string | undefined);
+        localField?: string;
+        foreignField?: string;
+        count?: boolean;
+        justOne?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Internal shape of a virtual config stored on the model (via _virtualConfigs or _dynamicVirtuals statics).
+ */
+export interface I_InternalVirtualConfig {
+    name: string;
+    options?: {
+        ref?: string | ((doc: unknown) => string | undefined);
+        [key: string]: unknown;
+    };
+}
+/**
+ * Resolves a `ref` value (which can be a string or a function) to a model name string.
+ * This is a central helper that replaces the 9 duplicated ref-resolution blocks
+ * throughout the mongo module.
+ *
+ * @param ref - The ref value, either a string or a function that returns a string.
+ * @param doc - The document to pass to the ref function (if ref is a function).
+ * @returns The resolved model name string, or undefined if resolution fails.
+ */
+export declare function resolveRef(ref: string | ((doc: unknown) => string | undefined) | undefined, doc?: unknown): string | undefined;
+/**
+ * Retrieves the dynamic virtual configurations from a model's _virtualConfigs
+ * or schema.statics._dynamicVirtuals.
+ *
+ * @param model - The model to search for dynamic virtuals.
+ * @returns An array of internal virtual configs, or an empty array if none found.
+ */
+export declare function getDynamicVirtualConfigs(model: I_ModelWithSchema | undefined): I_InternalVirtualConfig[];
+/**
+ * Recursively searches a schema's virtuals (including nested path schemas)
+ * for a virtual with the given field name and returns the resolved model name.
+ *
+ * This function was previously duplicated twice (verbatim) inside
+ * `populateNestedFieldOnParent` in `mongo.populate.ts`.
+ *
+ * @param schemaToSearch - The schema to search.
+ * @param fieldName - The virtual field name to look for.
+ * @param document - The document context for resolving function refs.
+ * @returns The resolved model name, or undefined.
+ */
+export declare function searchVirtualsInSchema(schemaToSearch: I_SchemaLike | undefined, fieldName: string, document: Record<string, unknown>): string | undefined;

package/dist/node/mongo/mongo.internal-types.js

@@ -0,0 +1,40 @@
+//#region src/node/mongo/mongo.internal-types.ts
+function e(e, t) {
+	if (e) {
+		if (typeof e == "function") return e(t);
+		if (typeof e == "string") return e;
+	}
+}
+function t(e) {
+	if (!e) return [];
+	let t = e._virtualConfigs;
+	if (t && t.length > 0) return t;
+	let n = e.schema?.statics;
+	if (n) {
+		let e = n._dynamicVirtuals;
+		if (e && e.length > 0) return e;
+	}
+	return [];
+}
+function n(t, r, i) {
+	if (!t || !t.virtuals) return;
+	let a = t.virtuals;
+	for (let t of Object.keys(a)) if (t === r) {
+		let n = a[t];
+		if (n?.options?.ref) {
+			let t = e(n.options.ref, i);
+			if (t && typeof t == "string") return t;
+		}
+	}
+	if (t.paths) for (let e of Object.keys(t.paths)) {
+		let a = t.paths[e];
+		if (a?.schema) {
+			let e = n(a.schema, r, i);
+			if (e) return e;
+		}
+	}
+}
+//#endregion
+export { t as getDynamicVirtualConfigs, e as resolveRef, n as searchVirtualsInSchema };
+
+//# sourceMappingURL=mongo.internal-types.js.map

package/dist/node/mongo/mongo.internal-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo.internal-types.js","names":[],"sources":["../../../src/node/mongo/mongo.internal-types.ts"],"sourcesContent":["/**\n * Internal type definitions for the mongo module.\n * These types are NOT part of the public API and are used for internal\n * type safety across mongo utility and controller files.\n */\n\n/**\n * Represents a Mongoose Model-like object that has a schema with virtuals and paths.\n * Used instead of `any` when traversing model references internally.\n */\nexport interface I_ModelWithSchema {\n    modelName?: string;\n    schema?: I_SchemaLike;\n    _virtualConfigs?: I_InternalVirtualConfig[];\n}\n\n/**\n * Schema-like structure for internal traversal.\n */\nexport interface I_SchemaLike {\n    virtuals?: Record<string, I_SchemaVirtual>;\n    paths?: Record<string, { schema?: I_SchemaLike; instance?: string; [key: string]: unknown }>;\n    statics?: Record<string, unknown>;\n}\n\n/**\n * A virtual field definition within a schema.\n */\nexport interface I_SchemaVirtual {\n    options?: {\n        ref?: string | ((doc: unknown) => string | undefined);\n        localField?: string;\n        foreignField?: string;\n        count?: boolean;\n        justOne?: boolean;\n        [key: string]: unknown;\n    };\n    [key: string]: unknown;\n}\n\n/**\n * Internal shape of a virtual config stored on the model (via _virtualConfigs or _dynamicVirtuals statics).\n */\nexport interface I_InternalVirtualConfig {\n    name: string;\n    options?: {\n        ref?: string | ((doc: unknown) => string | undefined);\n        [key: string]: unknown;\n    };\n}\n\n/**\n * Resolves a `ref` value (which can be a string or a function) to a model name string.\n * This is a central helper that replaces the 9 duplicated ref-resolution blocks\n * throughout the mongo module.\n *\n * @param ref - The ref value, either a string or a function that returns a string.\n * @param doc - The document to pass to the ref function (if ref is a function).\n * @returns The resolved model name string, or undefined if resolution fails.\n */\nexport function resolveRef(\n    ref: string | ((doc: unknown) => string | undefined) | undefined,\n    doc?: unknown,\n): string | undefined {\n    if (!ref) {\n        return undefined;\n    }\n\n    if (typeof ref === 'function') {\n        return ref(doc);\n    }\n\n    if (typeof ref === 'string') {\n        return ref;\n    }\n\n    return undefined;\n}\n\n/**\n * Retrieves the dynamic virtual configurations from a model's _virtualConfigs\n * or schema.statics._dynamicVirtuals.\n *\n * @param model - The model to search for dynamic virtuals.\n * @returns An array of internal virtual configs, or an empty array if none found.\n */\nexport function getDynamicVirtualConfigs(model: I_ModelWithSchema | undefined): I_InternalVirtualConfig[] {\n    if (!model) {\n        return [];\n    }\n\n    const virtualConfigs = model._virtualConfigs;\n    if (virtualConfigs && virtualConfigs.length > 0) {\n        return virtualConfigs;\n    }\n\n    const statics = model.schema?.statics;\n    if (statics) {\n        const dynamicVirtuals = statics['_dynamicVirtuals'] as I_InternalVirtualConfig[] | undefined;\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0) {\n            return dynamicVirtuals;\n        }\n    }\n\n    return [];\n}\n\n/**\n * Recursively searches a schema's virtuals (including nested path schemas)\n * for a virtual with the given field name and returns the resolved model name.\n *\n * This function was previously duplicated twice (verbatim) inside\n * `populateNestedFieldOnParent` in `mongo.populate.ts`.\n *\n * @param schemaToSearch - The schema to search.\n * @param fieldName - The virtual field name to look for.\n * @param document - The document context for resolving function refs.\n * @returns The resolved model name, or undefined.\n */\nexport function searchVirtualsInSchema(\n    schemaToSearch: I_SchemaLike | undefined,\n    fieldName: string,\n    document: Record<string, unknown>,\n): string | undefined {\n    if (!schemaToSearch || !schemaToSearch.virtuals) {\n        return undefined;\n    }\n\n    const virtuals = schemaToSearch.virtuals;\n\n    for (const virtualName of Object.keys(virtuals)) {\n        if (virtualName === fieldName) {\n            const virtual = virtuals[virtualName];\n            if (virtual?.options?.ref) {\n                const refResult = resolveRef(virtual.options.ref, document);\n                if (refResult && typeof refResult === 'string') {\n                    return refResult;\n                }\n            }\n        }\n    }\n\n    if (schemaToSearch.paths) {\n        for (const pathName of Object.keys(schemaToSearch.paths)) {\n            const pathSchema = schemaToSearch.paths[pathName];\n\n            if (pathSchema?.schema) {\n                const nestedResult = searchVirtualsInSchema(pathSchema.schema, fieldName, document);\n\n                if (nestedResult) {\n                    return nestedResult;\n                }\n            }\n        }\n    }\n\n    return undefined;\n}\n"],"mappings":";AA4DA,SAAgB,EACZ,GACA,GACkB;AACb,QAIL;MAAI,OAAO,KAAQ,WACf,QAAO,EAAI,EAAI;AAGnB,MAAI,OAAO,KAAQ,SACf,QAAO;;;AAaf,SAAgB,EAAyB,GAAiE;AACtG,KAAI,CAAC,EACD,QAAO,EAAE;CAGb,IAAM,IAAiB,EAAM;AAC7B,KAAI,KAAkB,EAAe,SAAS,EAC1C,QAAO;CAGX,IAAM,IAAU,EAAM,QAAQ;AAC9B,KAAI,GAAS;EACT,IAAM,IAAkB,EAAQ;AAEhC,MAAI,KAAmB,EAAgB,SAAS,EAC5C,QAAO;;AAIf,QAAO,EAAE;;AAeb,SAAgB,EACZ,GACA,GACA,GACkB;AAClB,KAAI,CAAC,KAAkB,CAAC,EAAe,SACnC;CAGJ,IAAM,IAAW,EAAe;AAEhC,MAAK,IAAM,KAAe,OAAO,KAAK,EAAS,CAC3C,KAAI,MAAgB,GAAW;EAC3B,IAAM,IAAU,EAAS;AACzB,MAAI,GAAS,SAAS,KAAK;GACvB,IAAM,IAAY,EAAW,EAAQ,QAAQ,KAAK,EAAS;AAC3D,OAAI,KAAa,OAAO,KAAc,SAClC,QAAO;;;AAMvB,KAAI,EAAe,MACf,MAAK,IAAM,KAAY,OAAO,KAAK,EAAe,MAAM,EAAE;EACtD,IAAM,IAAa,EAAe,MAAM;AAExC,MAAI,GAAY,QAAQ;GACpB,IAAM,IAAe,EAAuB,EAAW,QAAQ,GAAW,EAAS;AAEnF,OAAI,EACA,QAAO"}

package/dist/node/mongo/mongo.populate.d.ts

@@ -1,4 +1,5 @@
 import { default as mongooseRaw } from 'mongoose';
+import { I_ModelWithSchema } from './mongo.internal-types.js';
 import { I_DynamicVirtualConfig, T_Input_Populate } from './mongo.type.js';
 /**
  * Recursively applies nested populate options to populated documents.
@@ -12,4 +13,4 @@ import { I_DynamicVirtualConfig, T_Input_Populate } from './mongo.type.js';
  * @param currentModel - The current model context (which model's schema to search for virtuals)
  * @returns Promise with documents that have nested populations applied
  */
-export declare function applyNestedPopulate<T extends object>(mongoose: typeof mongooseRaw, documents: T[], populateOptions: T_Input_Populate, virtualConfigs?: I_DynamicVirtualConfig<unknown, string>[], currentModel?: any): Promise<T[]>;
+export declare function applyNestedPopulate<T extends object>(mongoose: typeof mongooseRaw, documents: T[], populateOptions: T_Input_Populate, virtualConfigs?: I_DynamicVirtualConfig<unknown, string>[], currentModel?: I_ModelWithSchema): Promise<T[]>;