@cyberskill/shared 3.4.0 → 3.6.0

package/dist/node/mongo/mongo.controller.mongoose.js

@@ -1,11 +1,14 @@
-import { normalizeMongoFilter as e } from "../../util/object/object.util.js";
-import { generateRandomString as t, generateShortId as n, generateSlug as r } from "../../util/string/string.util.js";
-import { RESPONSE_STATUS as i } from "../../constant/response-status.js";
-import { catchError as a } from "../log/log.util.js";
+import { RESPONSE_STATUS as e } from "../../constant/response-status.js";
+import { normalizeMongoFilter as t } from "../../util/object/object.util.js";
+import { generateRandomString as n, generateShortId as r, generateSlug as i } from "../../util/string/string.util.js";
+import { catchError as a, log as o } from "../log/log.util.js";
 import "./mongo.constant.js";
-import { filterDynamicVirtualsFromPopulate as o, isObject as s, populateDynamicVirtuals as c } from "./mongo.dynamic-populate.js";
+import { filterDynamicVirtualsFromPopulate as s, isObject as c, populateDynamicVirtuals as l } from "./mongo.dynamic-populate.js";
 //#region src/node/mongo/mongo.controller.mongoose.ts
-var l = class {
+function u(e) {
+	return e?.toObject?.() ?? e;
+}
+var d = class {
 	defaultLimit;
 	constructor(e, t) {
 		this.model = e, this.defaultLimit = t?.defaultLimit ?? 1e4;
@@ -24,69 +27,67 @@ var l = class {
 	async populateDynamicVirtualsForDocument(e, t) {
 		let n = this.getDynamicVirtuals();
 		if (n && n.length > 0) {
-			let r = await c(this.model.base, [e], n, t, void 0, this.model);
+			let r = await l(this.model.base, [e], n, t, void 0, this.model);
 			return r && r[0] ? r[0] : e;
 		}
 		return e;
 	}
 	async populateDynamicVirtualsForDocuments(e, t) {
 		let n = this.getDynamicVirtuals();
-		return n && n.length > 0 && e.length > 0 ? await c(this.model.base, e, n, t, void 0, this.model) : e;
+		return n && n.length > 0 && e.length > 0 ? await l(this.model.base, e, n, t, void 0, this.model) : e;
 	}
-	async findOne(t = {}, n = {}, r = {}, s) {
+	async findOne(n = {}, r = {}, i = {}, o) {
 		try {
-			let a = e(t), c = this.model.findOne(a, n, r).maxTimeMS(3e4).lean(), l = o(s, this.getDynamicVirtuals());
+			let a = t(n), c = this.model.findOne(a, r, i).maxTimeMS(3e4).lean(), l = s(o, this.getDynamicVirtuals());
 			l && c.populate(l);
-			let u = await c.exec();
-			if (!u) return {
+			let d = await c.exec();
+			return d ? {
+				success: !0,
+				result: u(await this.populateDynamicVirtualsForDocument(d, o))
+			} : {
 				success: !1,
 				message: `No ${this.getModelName()} found.`,
-				code: i.NOT_FOUND.CODE
-			};
-			let d = await this.populateDynamicVirtualsForDocument(u, s);
-			return {
-				success: !0,
-				result: d?.toObject?.() ?? d
+				code: e.NOT_FOUND.CODE
 			};
 		} catch (e) {
 			return a(e);
 		}
 	}
-	async findAll(t = {}, n = {}, r = {}, i) {
+	async findAll(e = {}, n = {}, r = {}, i) {
 		try {
-			let a = e(t), s = this.model.find(a, n, r).maxTimeMS(3e4).lean();
-			r.limit || s.limit(this.defaultLimit);
-			let c = o(i, this.getDynamicVirtuals());
-			c && s.populate(c);
-			let l = await s.exec();
-			return {
+			let a = t(e), c = this.model.find(a, n, r).maxTimeMS(3e4).lean();
+			r.limit || c.limit(this.defaultLimit);
+			let l = s(i, this.getDynamicVirtuals());
+			l && c.populate(l);
+			let d = await c.exec(), f = await this.populateDynamicVirtualsForDocuments(d, i);
+			return f.length === this.defaultLimit && !r.limit && o.warn(`[${this.getModelName()}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
 				success: !0,
-				result: (await this.populateDynamicVirtualsForDocuments(l, i)).map((e) => e?.toObject?.() ?? e)
+				result: f.map((e) => u(e))
 			};
 		} catch (e) {
 			return a(e);
 		}
 	}
-	async findPaging(t = {}, n = {}) {
+	async findPaging(e = {}, n = {}) {
 		try {
-			let r = e(t), i = this.getDynamicVirtuals(), a = { ...n };
-			n.populate && (a.populate = o(n.populate, i));
-			let s = await this.model.paginate(r, a);
+			let r = t(e), i = this.getDynamicVirtuals(), a = { ...n };
+			n.populate && (a.populate = s(n.populate, i));
+			let o = await this.model.paginate(r, a);
 			if (i && i.length > 0) {
-				let e = await this.populateDynamicVirtualsForDocuments(s.docs, n.populate);
+				let e = await this.populateDynamicVirtualsForDocuments(o.docs, n.populate);
 				return {
 					success: !0,
 					result: {
-						...s,
-						docs: e.map((e) => e?.toObject?.() ?? e)
+						...o,
+						docs: e.map((e) => u(e))
 					}
 				};
 			}
 			return {
 				success: !0,
 				result: {
-					...s,
-					docs: s.docs.map((e) => e?.toObject?.() ?? e)
+					...o,
+					docs: o.docs.map((e) => u(e))
 				}
 			};
 		} catch (e) {
@@ -96,7 +97,7 @@ var l = class {
 	async findPagingAggregate(e, t = {}) {
 		try {
 			let n = this.getDynamicVirtuals(), r = { ...t };
-			t.populate && (r.populate = o(t.populate, n));
+			t.populate && (r.populate = s(t.populate, n));
 			let i = await this.model.aggregatePaginate(this.model.aggregate(e), r), a = await this.populateDynamicVirtualsForDocuments(i.docs, t.populate);
 			return {
 				success: !0,
@@ -109,9 +110,9 @@ var l = class {
 			return a(e);
 		}
 	}
-	async count(t = {}) {
+	async count(e = {}) {
 		try {
-			let n = e(t);
+			let n = t(e);
 			return {
 				success: !0,
 				result: await this.model.countDocuments(n)
@@ -141,11 +142,11 @@ var l = class {
 			return a(e);
 		}
 	}
-	async updateOne(t = {}, n = {}, r = {}) {
+	async updateOne(n = {}, r = {}, i = {}) {
 		try {
-			let a = e(t), o = await this.model.findOneAndUpdate(a, n, {
+			let a = t(n), o = await this.model.findOneAndUpdate(a, r, {
 				new: !0,
-				...r
+				...i
 			}).exec();
 			return o ? {
 				success: !0,
@@ -153,15 +154,15 @@ var l = class {
 			} : {
 				success: !1,
 				message: `Failed to update ${this.getModelName()}.`,
-				code: i.NOT_FOUND.CODE
+				code: e.NOT_FOUND.CODE
 			};
 		} catch (e) {
 			return a(e);
 		}
 	}
-	async updateMany(t = {}, n = {}, r = {}) {
+	async updateMany(e = {}, n = {}, r = {}) {
 		try {
-			let i = e(t);
+			let i = t(e);
 			return {
 				success: !0,
 				result: await this.model.updateMany(i, n, r).exec()
@@ -170,28 +171,28 @@ var l = class {
 			return a(e);
 		}
 	}
-	async deleteOne(t = {}, n = {}) {
+	async deleteOne(n = {}, r = {}) {
 		try {
-			let r = e(t), a = await this.model.findOneAndDelete(r, n).exec();
+			let i = t(n), a = await this.model.findOneAndDelete(i, r).exec();
 			return a ? {
 				success: !0,
 				result: a?.toObject?.() ?? a
 			} : {
 				success: !1,
 				message: `No ${this.getModelName()} found to delete.`,
-				code: i.NOT_FOUND.CODE
+				code: e.NOT_FOUND.CODE
 			};
 		} catch (e) {
 			return a(e);
 		}
 	}
-	async deleteMany(t = {}, n = {}) {
+	async deleteMany(n = {}, r = {}) {
 		try {
-			let r = e(t), a = await this.model.deleteMany(r, n).exec();
+			let i = t(n), a = await this.model.deleteMany(i, r).exec();
 			return a.deletedCount === 0 ? {
 				success: !1,
 				message: "No documents found to delete.",
-				code: i.NOT_FOUND.CODE
+				code: e.NOT_FOUND.CODE
 			} : {
 				success: !0,
 				result: a
@@ -200,20 +201,16 @@ var l = class {
 			return a(e);
 		}
 	}
-	async createShortId(e, t = 4) {
+	async createShortId(t, n = 4) {
 		try {
-			let r = Array.from({ length: 10 }, (r, i) => n(e, i + t)), a = (await Promise.all(r.map((e) => this.model.exists({ shortId: e })))).findIndex((e) => !e);
-			if (a !== -1) {
-				let e = r[a];
-				if (e) return {
-					success: !0,
-					result: e
-				};
-			}
-			return {
+			let i = Array.from({ length: 10 }, (e, i) => r(t, i + n)), a = await this.model.find({ shortId: { $in: i } }).select("shortId").lean(), o = new Set(a.map((e) => e.shortId)), s = i.find((e) => !o.has(e));
+			return s ? {
+				success: !0,
+				result: s
+			} : {
 				success: !1,
 				message: "Failed to create a unique shortId",
-				code: i.INTERNAL_SERVER_ERROR.CODE
+				code: e.INTERNAL_SERVER_ERROR.CODE
 			};
 		} catch (e) {
 			return a(e);
@@ -229,29 +226,29 @@ var l = class {
 			$or: [{ slug: e }, ...r ? [{ slugHistory: e }] : []]
 		};
 	}
-	async createUniqueSlug({ slug: e, field: n, isObject: i, haveHistory: a, filter: o }) {
+	async createUniqueSlug({ slug: e, field: t, isObject: r, haveHistory: a, filter: o }) {
 		if (!e || typeof e != "string") throw Error("Invalid slug provided: must be a non-empty string");
-		let s = r(e);
+		let s = i(e);
 		if (!await this.model.exists(this.createSlugQuery({
 			slug: s,
-			field: n,
-			isObject: i,
+			field: t,
+			isObject: r,
 			haveHistory: a,
 			filter: o
 		}))) return s;
 		let c = Array.from({ length: 100 }, (e, t) => `${s}-${t + 1}`), l = c.map((e) => this.createSlugQuery({
 			slug: e,
-			field: n,
-			isObject: i,
+			field: t,
+			isObject: r,
 			haveHistory: a,
 			filter: o
-		})), u = i ? `slug.${n}` : "slug", d = await this.model.find({ $or: l.map((e) => e.$or).flat() }).select(u).lean(), f = new Set(d.map((e) => i ? e?.slug?.[n] : e?.slug));
-		return c.find((e) => !f.has(e)) || `${s}-${Date.now()}-${t(6)}`;
+		})), u = r ? `slug.${t}` : "slug", d = await this.model.find({ $or: l.map((e) => e.$or).flat() }).select(u).lean(), f = new Set(d.map((e) => r ? e.slug?.[t] : e.slug));
+		return c.find((e) => !f.has(e)) || `${s}-${Date.now()}-${n(6)}`;
 	}
 	async createSlug({ field: e, from: t, filter: n, haveHistory: r }) {
 		try {
 			let i = t[e];
-			return s(i) ? {
+			return c(i) ? {
 				success: !0,
 				result: Object.fromEntries(await Promise.all(Object.entries(i).map(async ([e, t]) => [e, await this.createUniqueSlug({
 					slug: t,
@@ -274,17 +271,17 @@ var l = class {
 			return a(e);
 		}
 	}
-	async checkSlug({ slug: e, field: t, from: n, filter: i, haveHistory: o }) {
+	async checkSlug({ slug: e, field: t, from: n, filter: r, haveHistory: o }) {
 		try {
 			let a = n[t];
-			if (s(a)) {
-				let e = Object.values(a).map((e) => r(e));
+			if (c(a)) {
+				let e = Object.values(a).map((e) => i(e));
 				return (await Promise.all(e.map((e) => this.model.exists(this.createSlugQuery({
 					slug: e,
 					field: t,
 					isObject: !0,
 					haveHistory: o,
-					filter: i
+					filter: r
 				}))))).some((e) => e) ? {
 					success: !0,
 					result: !0
@@ -293,14 +290,14 @@ var l = class {
 					result: !1
 				};
 			}
-			let c = r(e);
+			let s = i(e);
 			return {
 				success: !0,
 				result: await this.model.exists(this.createSlugQuery({
-					slug: c,
+					slug: s,
 					field: t,
 					isObject: !1,
-					filter: i
+					filter: r
 				})) !== null
 			};
 		} catch (e) {
@@ -329,6 +326,6 @@ var l = class {
 	}
 };
 //#endregion
-export { l as MongooseController };
+export { d as MongooseController };
 
 //# sourceMappingURL=mongo.controller.mongoose.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"mongo.controller.mongoose.js","names":[],"sources":["../../../src/node/mongo/mongo.controller.mongoose.ts"],"sourcesContent":["import type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\nimport { normalizeMongoFilter } from '#util/index.js';\nimport { generateRandomString, generateShortId, generateSlug } from '#util/string/index.js';\n\nimport type { C_Document, I_DeleteOptionsExtended, I_DynamicVirtualConfig, I_ExtendedModel, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Input_Populate, T_InsertManyOptions, T_PaginateResult, T_PipelineStage, T_PopulateOptions, T_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult } from './mongo.type.js';\n\nimport { catchError } from '../log/index.js';\nimport { MONGO_SLUG_MAX_ATTEMPTS } from './mongo.constant.js';\nimport { filterDynamicVirtualsFromPopulate, isObject, populateDynamicVirtuals } from './mongo.dynamic-populate.js';\n\n/** Internal shape of a single virtual config stored on the model. */\ninterface I_VirtualConfig {\n    name: string;\n    options?: { ref?: unknown };\n}\n\n/**\n * Mongoose controller for database operations with advanced features.\n * This class provides a comprehensive interface for Mongoose operations including\n * pagination, aggregation, slug generation, and short ID creation.\n */\nexport class MongooseController<T extends Partial<C_Document>> {\n    private defaultLimit: number;\n\n    /**\n     * Creates a new Mongoose controller instance.\n     *\n     * @param model - The Mongoose model 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(private model: I_ExtendedModel<T>, options?: { defaultLimit?: number }) {\n        this.defaultLimit = options?.defaultLimit ?? 10_000;\n    }\n\n    /**\n     * Gets the model name for logging and error messages.\n     *\n     * @returns The name of the model.\n     */\n    private getModelName(): string {\n        return this.model.modelName;\n    }\n\n    /**\n     * Gets the dynamic virtuals configuration from the model instance.\n     *\n     * @returns Array of dynamic virtual configurations or undefined if none exist.\n     */\n    private getDynamicVirtuals(): I_DynamicVirtualConfig<T>[] | undefined {\n        const model = this.model as I_ExtendedModel<T> & { _virtualConfigs?: I_VirtualConfig[] };\n\n        if (model._virtualConfigs) {\n            const dynamicOnly = model._virtualConfigs.filter(\n                v => typeof v.options?.ref === 'function',\n            ) as unknown as I_DynamicVirtualConfig<T>[];\n\n            if (dynamicOnly.length > 0) {\n                return dynamicOnly;\n            }\n        }\n\n        const schemaStatics = this.model.schema.statics as { [key: string]: unknown };\n\n        return schemaStatics['_dynamicVirtuals'] as I_DynamicVirtualConfig<T>[] | undefined;\n    }\n\n    /**\n     * Populates dynamic virtuals for a single document.\n     *\n     * @param result - The document to populate dynamic virtuals for.\n     * @param populate - The populate options to determine which virtuals to populate.\n     * @returns The document with dynamic virtuals populated.\n     */\n    private async populateDynamicVirtualsForDocument(result: T, populate?: T_Input_Populate): Promise<T> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0) {\n            const populatedArr = await populateDynamicVirtuals(this.model.base, [result], dynamicVirtuals, populate, undefined, this.model);\n\n            return (populatedArr && populatedArr[0]) ? populatedArr[0] as T : result;\n        }\n\n        return result;\n    }\n\n    /**\n     * Populates dynamic virtuals for an array of documents.\n     *\n     * @param results - The documents to populate dynamic virtuals for.\n     * @param populate - The populate options to determine which virtuals to populate.\n     * @returns The documents with dynamic virtuals populated.\n     */\n    private async populateDynamicVirtualsForDocuments(results: T[], populate?: T_Input_Populate): Promise<T[]> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0 && results.length > 0) {\n            const populatedResults = await populateDynamicVirtuals(this.model.base, results, dynamicVirtuals, populate, undefined, this.model) as T[];\n\n            return populatedResults;\n        }\n\n        return results;\n    }\n\n    /**\n     * Finds a single document with optional population and projection.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find the document.\n     * @param projection - The fields to include/exclude in the result.\n     * @param options - Query options for the operation.\n     * @param populate - Population configuration for related documents.\n     * @returns A promise that resolves to a standardized response with the found document.\n     */\n    async findOne(\n        filter: T_QueryFilter<T> = {},\n        projection: T_ProjectionType<T> = {},\n        options: T_QueryOptions<T> = {},\n        populate?: T_Input_Populate,\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const query = this.model.findOne(normalizedFilter, projection, options).maxTimeMS(30_000).lean();\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const regularPopulate = filterDynamicVirtualsFromPopulate(populate, dynamicVirtuals);\n\n            if (regularPopulate) {\n                query.populate(regularPopulate as T_PopulateOptions);\n            }\n\n            const result = await query.exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `No ${this.getModelName()} found.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            const finalResult = await this.populateDynamicVirtualsForDocument(result, populate);\n\n            return { success: true, result: finalResult?.toObject?.() ?? finalResult };\n        }\n        catch (error) {\n            return catchError<T>(error);\n        }\n    }\n\n    /**\n     * Finds all documents with optional population and projection.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find documents.\n     * @param projection - The fields to include/exclude in the result.\n     * @param options - Query options for the operation.\n     * @param populate - Population configuration for related documents.\n     * @returns A promise that resolves to a standardized response with the found documents.\n     */\n    async findAll(\n        filter: T_QueryFilter<T> = {},\n        projection: T_ProjectionType<T> = {},\n        options: T_QueryOptions<T> = {},\n        populate?: T_Input_Populate,\n    ): Promise<I_Return<T[]>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const query = this.model.find(normalizedFilter, projection, options).maxTimeMS(30_000).lean();\n\n            if (!options.limit) {\n                query.limit(this.defaultLimit);\n            }\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const regularPopulate = filterDynamicVirtualsFromPopulate(populate, dynamicVirtuals);\n\n            if (regularPopulate) {\n                query.populate(regularPopulate as T_PopulateOptions);\n            }\n\n            const result = await query.exec();\n\n            const finalResult = await this.populateDynamicVirtualsForDocuments(result, populate);\n\n            return { success: true, result: finalResult.map(item => item?.toObject?.() ?? item) };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Finds documents with pagination support.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find documents.\n     * @param options - Pagination options including page, limit, and population.\n     * @returns A promise that resolves to a standardized response with paginated results.\n     */\n    async findPaging(\n        filter: T_QueryFilter<T> = {},\n        options: I_PaginateOptionsWithPopulate = {},\n    ): Promise<I_Return<T_PaginateResult<T>>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const filteredOptions = { ...options };\n\n            if (options.populate) {\n                filteredOptions.populate = filterDynamicVirtualsFromPopulate(options.populate, dynamicVirtuals);\n            }\n\n            const result = await this.model.paginate(normalizedFilter, filteredOptions);\n\n            if (dynamicVirtuals && dynamicVirtuals.length > 0) {\n                const populatedDocs = await this.populateDynamicVirtualsForDocuments(result.docs, options.populate);\n\n                return { success: true, result: { ...result, docs: populatedDocs.map(item => item?.toObject?.() ?? item) } };\n            }\n\n            return { success: true, result: { ...result, docs: result.docs.map(item => item?.toObject?.() ?? item) } };\n        }\n        catch (error) {\n            return catchError<T_PaginateResult<T>>(error);\n        }\n    }\n\n    /**\n     * Performs aggregation with pagination support.\n     *\n     * @param pipeline - The aggregation pipeline stages.\n     * @param options - Pagination options for the aggregation result.\n     * @returns A promise that resolves to a standardized response with paginated aggregation results.\n     */\n    async findPagingAggregate(\n        pipeline: T_PipelineStage[],\n        options: I_PaginateOptionsWithPopulate = {},\n    ): Promise<I_Return<T_AggregatePaginateResult<T>>> {\n        try {\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const filteredOptions = { ...options };\n\n            if (options.populate) {\n                filteredOptions.populate = filterDynamicVirtualsFromPopulate(options.populate, dynamicVirtuals);\n            }\n\n            const result = await this.model.aggregatePaginate(\n                this.model.aggregate(pipeline),\n                filteredOptions,\n            );\n\n            const finalDocs = await this.populateDynamicVirtualsForDocuments(result.docs, options.populate);\n\n            return { success: true, result: { ...result, docs: finalDocs.map(item => item?.toObject?.() ?? item) } };\n        }\n        catch (error) {\n            return catchError<T_AggregatePaginateResult<T>>(error);\n        }\n    }\n\n    /**\n     * Counts documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to count documents.\n     * @returns A promise that resolves to a standardized response with the document count.\n     */\n    async count(filter: T_QueryFilter<T> = {}): Promise<I_Return<number>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model.countDocuments(normalizedFilter);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<number>(error);\n        }\n    }\n\n    /**\n     * Creates a single document.\n     *\n     * @param doc - The document to create.\n     * @returns A promise that resolves to a standardized response with the created document.\n     */\n    async createOne(doc: T | Partial<T>): Promise<I_Return<T>> {\n        try {\n            const result = await this.model.create(doc as unknown as Parameters<typeof this.model.create>[0]);\n\n            return { success: true, result: (result as T)?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(error);\n        }\n    }\n\n    /**\n     * Creates multiple documents with bulk insertion.\n     *\n     * @param docs - An array of documents to create.\n     * @param options - Options for the bulk insertion operation.\n     * @returns A promise that resolves to a standardized response with the created documents.\n     */\n    async createMany(\n        docs: (T | Partial<T>)[],\n        options: T_InsertManyOptions = {},\n    ): Promise<I_Return<T[]>> {\n        try {\n            const createdDocuments = await this.model.insertMany(docs, options);\n\n            return { success: true, result: createdDocuments.map(item => item?.toObject?.() ?? item) as T[] };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Updates a single document and returns the updated version.\n     *\n     * @param filter - The filter criteria to find the document to update.\n     * @param update - The update data to apply.\n     * @param options - Options for the update operation.\n     * @returns A promise that resolves to a standardized response with the updated document.\n     */\n    async updateOne(\n        filter: T_QueryFilter<T> = {},\n        update: T_UpdateQuery<T> = {},\n        options: I_UpdateOptionsExtended = {},\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .findOneAndUpdate(normalizedFilter, update, {\n                    new: true,\n                    ...options,\n                })\n                .exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `Failed to update ${this.getModelName()}.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result: result?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(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.\n     * @param options - Options for the update operation.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateMany(\n        filter: T_QueryFilter<T> = {},\n        update: T_UpdateQuery<T> = {},\n        options: I_UpdateOptionsExtended = {},\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .updateMany(normalizedFilter, update, options)\n                .exec();\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Deletes a single document and returns the deleted version.\n     *\n     * @param filter - The filter criteria to find the document to delete.\n     * @param options - Options for the delete operation.\n     * @returns A promise that resolves to a standardized response with the deleted document.\n     */\n    async deleteOne(\n        filter: T_QueryFilter<T> = {},\n        options: I_DeleteOptionsExtended = {},\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .findOneAndDelete(normalizedFilter, options)\n                .exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `No ${this.getModelName()} found to delete.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result: result?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(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     * @param options - Options for the delete operation.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteMany(\n        filter: T_QueryFilter<T> = {},\n        options: I_DeleteOptionsExtended = {},\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model.deleteMany(normalizedFilter, options).exec();\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: `No documents found to delete.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n\n    /**\n     * Creates a unique short ID based on a given ID.\n     * This method generates multiple short IDs with increasing lengths and finds the first available one.\n     *\n     * @param id - The base ID to generate short IDs from.\n     * @param length - The initial length for short ID generation (default: 4).\n     * @returns A promise that resolves to a standardized response with the unique short ID.\n     */\n    async createShortId(id: string, length = 4): Promise<I_Return<string>> {\n        try {\n            const maxRetries = 10;\n            const shortIds = Array.from({ length: maxRetries }, (_, index) =>\n                generateShortId(id, index + length));\n\n            const existenceChecks = await Promise.all(\n                shortIds.map(shortId => this.model.exists({ shortId })),\n            );\n\n            const availableIndex = existenceChecks.findIndex(exists => !exists);\n\n            if (availableIndex !== -1) {\n                const availableShortId = shortIds[availableIndex];\n\n                if (availableShortId) {\n                    return { success: true, result: availableShortId };\n                }\n            }\n\n            return {\n                success: false,\n                message: 'Failed to create a unique shortId',\n                code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n            };\n        }\n        catch (error) {\n            return catchError<string>(error);\n        }\n    }\n\n    /**\n     * Creates a query for slug existence checking.\n     * This method generates a query that checks for slug existence in both current and historical slug fields.\n     *\n     * @param options - Configuration for slug query generation including slug, field, and filter.\n     * @param options.slug - The slug string to check for existence.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.isObject - Whether the slug is stored as an object with nested fields.\n     * @param options.haveHistory - Whether to check historical slug fields for existence.\n     * @param options.filter - Additional filter conditions to apply to the query.\n     * @returns A MongoDB query object for checking slug existence.\n     */\n    createSlugQuery({ slug, field, isObject, haveHistory = false, filter }: I_Input_GenerateSlug<T>) {\n        const baseFilter = { ...(filter ?? {}) };\n\n        return isObject\n            ? {\n                    ...baseFilter,\n                    $or: [\n                        { [`slug.${field}`]: slug },\n                        ...(haveHistory ? [{ slugHistory: { $elemMatch: { [`slug.${field}`]: slug } } }] : []),\n                    ],\n                }\n            : {\n                    ...baseFilter,\n                    $or: [\n                        { slug },\n                        ...(haveHistory ? [{ slugHistory: slug }] : []),\n                    ],\n                };\n    }\n\n    /**\n     * Creates a unique slug based on a given string.\n     * This method generates multiple slug variations and finds the first available one.\n     *\n     * @param options - Configuration for slug generation including slug, field, and filter.\n     * @param options.slug - The base slug string to make unique.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.isObject - Whether the slug is stored as an object with nested fields.\n     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.\n     * @param options.filter - Additional filter conditions to apply when checking slug existence.\n     * @returns A promise that resolves to a unique slug string.\n     */\n    async createUniqueSlug({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): Promise<string> {\n        if (!slug || typeof slug !== 'string') {\n            throw new Error('Invalid slug provided: must be a non-empty string');\n        }\n\n        const baseSlug = generateSlug(slug);\n\n        const baseExists = await this.model.exists(\n            this.createSlugQuery({ slug: baseSlug, field, isObject, haveHistory, filter }),\n        );\n\n        if (!baseExists) {\n            return baseSlug;\n        }\n\n        // Batch query: check all slug variations in a single database call instead of N+1 sequential queries\n        const variants = Array.from(\n            { length: MONGO_SLUG_MAX_ATTEMPTS },\n            (_, i) => `${baseSlug}-${i + 1}`,\n        );\n\n        const slugQueries = variants.map(s =>\n            this.createSlugQuery({ slug: s, field, isObject, haveHistory, filter }),\n        );\n\n        const slugField = isObject ? `slug.${field as string}` : 'slug';\n        const existingDocs = await this.model\n            .find({ $or: slugQueries.map(q => q.$or).flat() })\n            .select(slugField)\n            .lean();\n\n        const existingSlugs = new Set(\n            existingDocs.map((d: any) => isObject ? d?.slug?.[field as string] : d?.slug),\n        );\n\n        const available = variants.find(s => !existingSlugs.has(s));\n\n        if (available) {\n            return available;\n        }\n\n        const timestamp = Date.now();\n        const randomSuffix = generateRandomString(6);\n\n        return `${baseSlug}-${timestamp}-${randomSuffix}`;\n    }\n\n    /**\n     * Creates a slug for a document field.\n     * This method handles both simple string fields and object fields with nested slug generation.\n     *\n     * @param options - Configuration for slug creation including field, source document, and filter.\n     * @param options.field - The field name to create a slug for.\n     * @param options.from - The source document containing the field value.\n     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.\n     * @param options.filter - Additional filter conditions to apply when checking slug existence.\n     * @returns A promise that resolves to a standardized response with the created slug(s).\n     */\n    async createSlug<R = string>({ field, from, filter, haveHistory }: I_Input_CreateSlug<T>): Promise<I_Return<R>> {\n        try {\n            const fieldValue = from[field as keyof T];\n            const isObjectValue = isObject(fieldValue);\n\n            if (isObjectValue) {\n                const uniqueSlug = Object.fromEntries(\n                    await Promise.all(\n                        Object.entries(fieldValue).map(async ([key, value]) => {\n                            const uniqueSlugForKey = await this.createUniqueSlug({\n                                slug: value as string,\n                                field: key,\n                                isObject: true,\n                                haveHistory,\n                                filter,\n                            });\n                            return [key, uniqueSlugForKey];\n                        }),\n                    ),\n                );\n\n                return { success: true, result: uniqueSlug as R };\n            }\n\n            const uniqueSlug = await this.createUniqueSlug({\n                slug: fieldValue as string,\n                field,\n                isObject: false,\n                haveHistory,\n                filter,\n            });\n\n            return { success: true, result: uniqueSlug as R };\n        }\n        catch (error) {\n            return catchError<R>(error);\n        }\n    }\n\n    /**\n     * Checks if a slug already exists in the collection.\n     * This method verifies slug existence in both current and historical slug fields.\n     *\n     * @param options - Configuration for slug checking including slug, field, source document, and filter.\n     * @param options.slug - The slug string to check for existence.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.from - The source document containing the field value.\n     * @param options.haveHistory - Whether to check historical slug fields for existence.\n     * @param options.filter - Additional filter conditions to apply to the query.\n     * @returns A promise that resolves to a standardized response indicating whether the slug exists.\n     */\n    async checkSlug({ slug, field, from, filter, haveHistory }: I_Input_CheckSlug<T>): Promise<I_Return<boolean>> {\n        try {\n            const fieldValue = from[field as keyof T];\n            const isObjectValue = isObject(fieldValue);\n\n            if (isObjectValue) {\n                const values = Object.values(fieldValue);\n                const nestedSlugs = values.map(value => generateSlug(value as string));\n\n                const existenceChecks = await Promise.all(\n                    nestedSlugs.map(nestedSlug =>\n                        this.model.exists(this.createSlugQuery({\n                            slug: nestedSlug,\n                            field,\n                            isObject: true,\n                            haveHistory,\n                            filter,\n                        })),\n                    ),\n                );\n\n                if (existenceChecks.some(exists => exists)) {\n                    return { success: true, result: true };\n                }\n\n                return { success: true, result: false };\n            }\n\n            const baseSlug = generateSlug(slug);\n            const exists = await this.model.exists(this.createSlugQuery({\n                slug: baseSlug,\n                field,\n                isObject: false,\n                filter,\n            }));\n\n            return { success: true, result: exists !== null };\n        }\n        catch (error) {\n            return catchError<boolean>(error);\n        }\n    }\n\n    /**\n     * Performs aggregation operations on the collection.\n     *\n     * @param pipeline - The aggregation pipeline stages to execute.\n     * @returns A promise that resolves to a standardized response with the aggregation results.\n     */\n    async aggregate(pipeline: T_PipelineStage[]): Promise<I_Return<T[]>> {\n        try {\n            const result = await this.model.aggregate<T>(pipeline);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Retrieves distinct values for the specified key from the collection.\n     *\n     * @param key - The field for which to return distinct values.\n     * @param filter - The filter query to apply (optional).\n     * @param options - Additional options for the distinct operation (optional).\n     * @returns A promise that resolves to a standardized response with the array of distinct values.\n     */\n    async distinct(\n        key: string,\n        filter: T_QueryFilter<T> = {},\n        options: T_QueryOptions<T> = {},\n    ): Promise<I_Return<unknown[]>> {\n        try {\n            const result = await this.model.distinct(key, filter, options);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<unknown[]>(error);\n        }\n    }\n}\n"],"mappings":";;;;;;;AAuBA,IAAa,IAAb,MAA+D;CAC3D;CASA,YAAY,GAAmC,GAAqC;AAChF,EADgB,KAAA,QAAA,GAChB,KAAK,eAAe,GAAS,gBAAgB;;CAQjD,eAA+B;AAC3B,SAAO,KAAK,MAAM;;CAQtB,qBAAsE;EAClE,IAAM,IAAQ,KAAK;AAEnB,MAAI,EAAM,iBAAiB;GACvB,IAAM,IAAc,EAAM,gBAAgB,QACtC,MAAK,OAAO,EAAE,SAAS,OAAQ,WAClC;AAED,OAAI,EAAY,SAAS,EACrB,QAAO;;AAMf,SAFsB,KAAK,MAAM,OAAO,QAEnB;;CAUzB,MAAc,mCAAmC,GAAW,GAAyC;EACjG,IAAM,IAAkB,KAAK,oBAAoB;AAEjD,MAAI,KAAmB,EAAgB,SAAS,GAAG;GAC/C,IAAM,IAAe,MAAM,EAAwB,KAAK,MAAM,MAAM,CAAC,EAAO,EAAE,GAAiB,GAAU,KAAA,GAAW,KAAK,MAAM;AAE/H,UAAQ,KAAgB,EAAa,KAAM,EAAa,KAAU;;AAGtE,SAAO;;CAUX,MAAc,oCAAoC,GAAc,GAA2C;EACvG,IAAM,IAAkB,KAAK,oBAAoB;AAQjD,SANI,KAAmB,EAAgB,SAAS,KAAK,EAAQ,SAAS,IACzC,MAAM,EAAwB,KAAK,MAAM,MAAM,GAAS,GAAiB,GAAU,KAAA,GAAW,KAAK,MAAM,GAK/H;;CAaX,MAAM,QACF,IAA2B,EAAE,EAC7B,IAAkC,EAAE,EACpC,IAA6B,EAAE,EAC/B,GACoB;AACpB,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAQ,KAAK,MAAM,QAAQ,GAAkB,GAAY,EAAQ,CAAC,UAAU,IAAO,CAAC,MAAM,EAG1F,IAAkB,EAAkC,GAFlC,KAAK,oBAAoB,CAEmC;AAEpF,GAAI,KACA,EAAM,SAAS,EAAqC;GAGxD,IAAM,IAAS,MAAM,EAAM,MAAM;AAEjC,OAAI,CAAC,EACD,QAAO;IACH,SAAS;IACT,SAAS,MAAM,KAAK,cAAc,CAAC;IACnC,MAAM,EAAgB,UAAU;IACnC;GAGL,IAAM,IAAc,MAAM,KAAK,mCAAmC,GAAQ,EAAS;AAEnF,UAAO;IAAE,SAAS;IAAM,QAAQ,GAAa,YAAY,IAAI;IAAa;WAEvE,GAAO;AACV,UAAO,EAAc,EAAM;;;CAcnC,MAAM,QACF,IAA2B,EAAE,EAC7B,IAAkC,EAAE,EACpC,IAA6B,EAAE,EAC/B,GACsB;AACtB,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAQ,KAAK,MAAM,KAAK,GAAkB,GAAY,EAAQ,CAAC,UAAU,IAAO,CAAC,MAAM;AAE7F,GAAK,EAAQ,SACT,EAAM,MAAM,KAAK,aAAa;GAIlC,IAAM,IAAkB,EAAkC,GAFlC,KAAK,oBAAoB,CAEmC;AAEpF,GAAI,KACA,EAAM,SAAS,EAAqC;GAGxD,IAAM,IAAS,MAAM,EAAM,MAAM;AAIjC,UAAO;IAAE,SAAS;IAAM,SAFJ,MAAM,KAAK,oCAAoC,GAAQ,EAAS,EAExC,KAAI,MAAQ,GAAM,YAAY,IAAI,EAAK;IAAE;WAElF,GAAO;AACV,UAAO,EAAgB,EAAM;;;CAYrC,MAAM,WACF,IAA2B,EAAE,EAC7B,IAAyC,EAAE,EACL;AACtC,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAkB,KAAK,oBAAoB,EAE3C,IAAkB,EAAE,GAAG,GAAS;AAEtC,GAAI,EAAQ,aACR,EAAgB,WAAW,EAAkC,EAAQ,UAAU,EAAgB;GAGnG,IAAM,IAAS,MAAM,KAAK,MAAM,SAAS,GAAkB,EAAgB;AAE3E,OAAI,KAAmB,EAAgB,SAAS,GAAG;IAC/C,IAAM,IAAgB,MAAM,KAAK,oCAAoC,EAAO,MAAM,EAAQ,SAAS;AAEnG,WAAO;KAAE,SAAS;KAAM,QAAQ;MAAE,GAAG;MAAQ,MAAM,EAAc,KAAI,MAAQ,GAAM,YAAY,IAAI,EAAK;MAAE;KAAE;;AAGhH,UAAO;IAAE,SAAS;IAAM,QAAQ;KAAE,GAAG;KAAQ,MAAM,EAAO,KAAK,KAAI,MAAQ,GAAM,YAAY,IAAI,EAAK;KAAE;IAAE;WAEvG,GAAO;AACV,UAAO,EAAgC,EAAM;;;CAWrD,MAAM,oBACF,GACA,IAAyC,EAAE,EACI;AAC/C,MAAI;GACA,IAAM,IAAkB,KAAK,oBAAoB,EAE3C,IAAkB,EAAE,GAAG,GAAS;AAEtC,GAAI,EAAQ,aACR,EAAgB,WAAW,EAAkC,EAAQ,UAAU,EAAgB;GAGnG,IAAM,IAAS,MAAM,KAAK,MAAM,kBAC5B,KAAK,MAAM,UAAU,EAAS,EAC9B,EACH,EAEK,IAAY,MAAM,KAAK,oCAAoC,EAAO,MAAM,EAAQ,SAAS;AAE/F,UAAO;IAAE,SAAS;IAAM,QAAQ;KAAE,GAAG;KAAQ,MAAM,EAAU,KAAI,MAAQ,GAAM,YAAY,IAAI,EAAK;KAAE;IAAE;WAErG,GAAO;AACV,UAAO,EAAyC,EAAM;;;CAU9D,MAAM,MAAM,IAA2B,EAAE,EAA6B;AAClE,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO;AAGrD,UAAO;IAAE,SAAS;IAAM,QAFT,MAAM,KAAK,MAAM,eAAe,EAAiB;IAEhC;WAE7B,GAAO;AACV,UAAO,EAAmB,EAAM;;;CAUxC,MAAM,UAAU,GAA2C;AACvD,MAAI;GACA,IAAM,IAAS,MAAM,KAAK,MAAM,OAAO,EAA0D;AAEjG,UAAO;IAAE,SAAS;IAAM,QAAS,GAAc,YAAY,IAAI;IAAQ;WAEpE,GAAO;AACV,UAAO,EAAc,EAAM;;;CAWnC,MAAM,WACF,GACA,IAA+B,EAAE,EACX;AACtB,MAAI;AAGA,UAAO;IAAE,SAAS;IAAM,SAFC,MAAM,KAAK,MAAM,WAAW,GAAM,EAAQ,EAElB,KAAI,MAAQ,GAAM,YAAY,IAAI,EAAK;IAAS;WAE9F,GAAO;AACV,UAAO,EAAgB,EAAM;;;CAYrC,MAAM,UACF,IAA2B,EAAE,EAC7B,IAA2B,EAAE,EAC7B,IAAmC,EAAE,EACjB;AACpB,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAS,MAAM,KAAK,MACrB,iBAAiB,GAAkB,GAAQ;IACxC,KAAK;IACL,GAAG;IACN,CAAC,CACD,MAAM;AAUX,UARK,IAQE;IAAE,SAAS;IAAM,QAAQ,GAAQ,YAAY,IAAI;IAAQ,GAPrD;IACH,SAAS;IACT,SAAS,oBAAoB,KAAK,cAAc,CAAC;IACjD,MAAM,EAAgB,UAAU;IACnC;WAKF,GAAO;AACV,UAAO,EAAc,EAAM;;;CAYnC,MAAM,WACF,IAA2B,EAAE,EAC7B,IAA2B,EAAE,EAC7B,IAAmC,EAAE,EACJ;AACjC,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO;AAKrD,UAAO;IAAE,SAAS;IAAM,QAJT,MAAM,KAAK,MACrB,WAAW,GAAkB,GAAQ,EAAQ,CAC7C,MAAM;IAEqB;WAE7B,GAAO;AACV,UAAO,EAA2B,EAAM;;;CAWhD,MAAM,UACF,IAA2B,EAAE,EAC7B,IAAmC,EAAE,EACjB;AACpB,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAS,MAAM,KAAK,MACrB,iBAAiB,GAAkB,EAAQ,CAC3C,MAAM;AAUX,UARK,IAQE;IAAE,SAAS;IAAM,QAAQ,GAAQ,YAAY,IAAI;IAAQ,GAPrD;IACH,SAAS;IACT,SAAS,MAAM,KAAK,cAAc,CAAC;IACnC,MAAM,EAAgB,UAAU;IACnC;WAKF,GAAO;AACV,UAAO,EAAc,EAAM;;;CAWnC,MAAM,WACF,IAA2B,EAAE,EAC7B,IAAmC,EAAE,EACJ;AACjC,MAAI;GACA,IAAM,IAAmB,EAAqB,EAAO,EAC/C,IAAS,MAAM,KAAK,MAAM,WAAW,GAAkB,EAAQ,CAAC,MAAM;AAU5E,UARI,EAAO,iBAAiB,IACjB;IACH,SAAS;IACT,SAAS;IACT,MAAM,EAAgB,UAAU;IACnC,GAGE;IAAE,SAAS;IAAM;IAAQ;WAE7B,GAAO;AACV,UAAO,EAA2B,EAAM;;;CAYhD,MAAM,cAAc,GAAY,IAAS,GAA8B;AACnE,MAAI;GAEA,IAAM,IAAW,MAAM,KAAK,EAAE,QADX,IAC+B,GAAG,GAAG,MACpD,EAAgB,GAAI,IAAQ,EAAO,CAAC,EAMlC,KAJkB,MAAM,QAAQ,IAClC,EAAS,KAAI,MAAW,KAAK,MAAM,OAAO,EAAE,YAAS,CAAC,CAAC,CAC1D,EAEsC,WAAU,MAAU,CAAC,EAAO;AAEnE,OAAI,MAAmB,IAAI;IACvB,IAAM,IAAmB,EAAS;AAElC,QAAI,EACA,QAAO;KAAE,SAAS;KAAM,QAAQ;KAAkB;;AAI1D,UAAO;IACH,SAAS;IACT,SAAS;IACT,MAAM,EAAgB,sBAAsB;IAC/C;WAEE,GAAO;AACV,UAAO,EAAmB,EAAM;;;CAgBxC,gBAAgB,EAAE,SAAM,UAAO,aAAU,iBAAc,IAAO,aAAmC;EAC7F,IAAM,IAAa,EAAE,GAAI,KAAU,EAAE,EAAG;AAExC,SAAO,IACD;GACM,GAAG;GACH,KAAK,CACD,GAAG,QAAQ,MAAU,GAAM,EAC3B,GAAI,IAAc,CAAC,EAAE,aAAa,EAAE,YAAY,GAAG,QAAQ,MAAU,GAAM,EAAE,EAAE,CAAC,GAAG,EAAE,CACxF;GACJ,GACH;GACM,GAAG;GACH,KAAK,CACD,EAAE,SAAM,EACR,GAAI,IAAc,CAAC,EAAE,aAAa,GAAM,CAAC,GAAG,EAAE,CACjD;GACJ;;CAeb,MAAM,iBAAiB,EAAE,SAAM,UAAO,aAAU,gBAAa,aAAoD;AAC7G,MAAI,CAAC,KAAQ,OAAO,KAAS,SACzB,OAAU,MAAM,oDAAoD;EAGxE,IAAM,IAAW,EAAa,EAAK;AAMnC,MAAI,CAJe,MAAM,KAAK,MAAM,OAChC,KAAK,gBAAgB;GAAE,MAAM;GAAU;GAAO;GAAU;GAAa;GAAQ,CAAC,CACjF,CAGG,QAAO;EAIX,IAAM,IAAW,MAAM,KACnB,EAAE,QAAA,KAAiC,GAClC,GAAG,MAAM,GAAG,EAAS,GAAG,IAAI,IAChC,EAEK,IAAc,EAAS,KAAI,MAC7B,KAAK,gBAAgB;GAAE,MAAM;GAAG;GAAO;GAAU;GAAa;GAAQ,CAAC,CAC1E,EAEK,IAAY,IAAW,QAAQ,MAAoB,QACnD,IAAe,MAAM,KAAK,MAC3B,KAAK,EAAE,KAAK,EAAY,KAAI,MAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CACjD,OAAO,EAAU,CACjB,MAAM,EAEL,IAAgB,IAAI,IACtB,EAAa,KAAK,MAAW,IAAW,GAAG,OAAO,KAAmB,GAAG,KAAK,CAChF;AAWD,SATkB,EAAS,MAAK,MAAK,CAAC,EAAc,IAAI,EAAE,CAAC,IASpD,GAAG,EAAS,GAHD,KAAK,KAAK,CAGI,GAFX,EAAqB,EAAE;;CAgBhD,MAAM,WAAuB,EAAE,UAAO,SAAM,WAAQ,kBAA4D;AAC5G,MAAI;GACA,IAAM,IAAa,EAAK;AA8BxB,UA7BsB,EAAS,EAAW,GAkB/B;IAAE,SAAS;IAAM,QAfL,OAAO,YACtB,MAAM,QAAQ,IACV,OAAO,QAAQ,EAAW,CAAC,IAAI,OAAO,CAAC,GAAK,OAQjC,CAAC,GAPiB,MAAM,KAAK,iBAAiB;KACjD,MAAM;KACN,OAAO;KACP,UAAU;KACV;KACA;KACH,CAAC,CAC4B,CAChC,CACL,CACJ;IAEgD,GAW9C;IAAE,SAAS;IAAM,QARL,MAAM,KAAK,iBAAiB;KAC3C,MAAM;KACN;KACA,UAAU;KACV;KACA;KACH,CAAC;IAE+C;WAE9C,GAAO;AACV,UAAO,EAAc,EAAM;;;CAgBnC,MAAM,UAAU,EAAE,SAAM,UAAO,SAAM,WAAQ,kBAAiE;AAC1G,MAAI;GACA,IAAM,IAAa,EAAK;AAGxB,OAFsB,EAAS,EAAW,EAEvB;IAEf,IAAM,IADS,OAAO,OAAO,EAAW,CACb,KAAI,MAAS,EAAa,EAAgB,CAAC;AAkBtE,YAhBwB,MAAM,QAAQ,IAClC,EAAY,KAAI,MACZ,KAAK,MAAM,OAAO,KAAK,gBAAgB;KACnC,MAAM;KACN;KACA,UAAU;KACV;KACA;KACH,CAAC,CAAC,CACN,CACJ,EAEmB,MAAK,MAAU,EAAO,GAC/B;KAAE,SAAS;KAAM,QAAQ;KAAM,GAGnC;KAAE,SAAS;KAAM,QAAQ;KAAO;;GAG3C,IAAM,IAAW,EAAa,EAAK;AAQnC,UAAO;IAAE,SAAS;IAAM,QAPT,MAAM,KAAK,MAAM,OAAO,KAAK,gBAAgB;KACxD,MAAM;KACN;KACA,UAAU;KACV;KACH,CAAC,CAAC,KAEwC;IAAM;WAE9C,GAAO;AACV,UAAO,EAAoB,EAAM;;;CAUzC,MAAM,UAAU,GAAqD;AACjE,MAAI;AAGA,UAAO;IAAE,SAAS;IAAM,QAFT,MAAM,KAAK,MAAM,UAAa,EAAS;IAEtB;WAE7B,GAAO;AACV,UAAO,EAAgB,EAAM;;;CAYrC,MAAM,SACF,GACA,IAA2B,EAAE,EAC7B,IAA6B,EAAE,EACH;AAC5B,MAAI;AAGA,UAAO;IAAE,SAAS;IAAM,QAFT,MAAM,KAAK,MAAM,SAAS,GAAK,GAAQ,EAAQ;IAE9B;WAE7B,GAAO;AACV,UAAO,EAAsB,EAAM"}
+{"version":3,"file":"mongo.controller.mongoose.js","names":[],"sources":["../../../src/node/mongo/mongo.controller.mongoose.ts"],"sourcesContent":["import type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\nimport { normalizeMongoFilter } from '#util/index.js';\nimport { generateRandomString, generateShortId, generateSlug } from '#util/string/index.js';\n\nimport type { C_Document, I_DeleteOptionsExtended, I_DynamicVirtualConfig, I_ExtendedModel, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Input_Populate, T_InsertManyOptions, T_PaginateResult, T_PipelineStage, T_PopulateOptions, T_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult } from './mongo.type.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { MONGO_SLUG_MAX_ATTEMPTS } from './mongo.constant.js';\nimport { filterDynamicVirtualsFromPopulate, isObject, populateDynamicVirtuals } from './mongo.dynamic-populate.js';\n\n/**\n * Converts a Mongoose document to a plain object, handling the case where\n * the document may already be a plain object (e.g., from `.lean()`).\n *\n * @param doc - The document or plain object.\n * @returns The plain object representation.\n */\nfunction toPlainObject<T>(doc: T): T {\n    return (doc as T & { toObject?: () => T })?.toObject?.() ?? doc;\n}\n\n/** Internal shape of a single virtual config stored on the model. */\ninterface I_VirtualConfig {\n    name: string;\n    options?: { ref?: unknown };\n}\n\n/**\n * Mongoose controller for database operations with advanced features.\n * This class provides a comprehensive interface for Mongoose operations including\n * pagination, aggregation, slug generation, and short ID creation.\n */\nexport class MongooseController<T extends Partial<C_Document>> {\n    private defaultLimit: number;\n\n    /**\n     * Creates a new Mongoose controller instance.\n     *\n     * @param model - The Mongoose model 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(private model: I_ExtendedModel<T>, options?: { defaultLimit?: number }) {\n        this.defaultLimit = options?.defaultLimit ?? 10_000;\n    }\n\n    /**\n     * Gets the model name for logging and error messages.\n     *\n     * @returns The name of the model.\n     */\n    private getModelName(): string {\n        return this.model.modelName;\n    }\n\n    /**\n     * Gets the dynamic virtuals configuration from the model instance.\n     *\n     * @returns Array of dynamic virtual configurations or undefined if none exist.\n     */\n    private getDynamicVirtuals(): I_DynamicVirtualConfig<T>[] | undefined {\n        const model = this.model as I_ExtendedModel<T> & { _virtualConfigs?: I_VirtualConfig[] };\n\n        if (model._virtualConfigs) {\n            const dynamicOnly = model._virtualConfigs.filter(\n                v => typeof v.options?.ref === 'function',\n            ) as unknown as I_DynamicVirtualConfig<T>[];\n\n            if (dynamicOnly.length > 0) {\n                return dynamicOnly;\n            }\n        }\n\n        const schemaStatics = this.model.schema.statics as { [key: string]: unknown };\n\n        return schemaStatics['_dynamicVirtuals'] as I_DynamicVirtualConfig<T>[] | undefined;\n    }\n\n    /**\n     * Populates dynamic virtuals for a single document.\n     *\n     * @param result - The document to populate dynamic virtuals for.\n     * @param populate - The populate options to determine which virtuals to populate.\n     * @returns The document with dynamic virtuals populated.\n     */\n    private async populateDynamicVirtualsForDocument(result: T, populate?: T_Input_Populate): Promise<T> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0) {\n            const populatedArr = await populateDynamicVirtuals(this.model.base, [result], dynamicVirtuals, populate, undefined, this.model);\n\n            return (populatedArr && populatedArr[0]) ? populatedArr[0] as T : result;\n        }\n\n        return result;\n    }\n\n    /**\n     * Populates dynamic virtuals for an array of documents.\n     *\n     * @param results - The documents to populate dynamic virtuals for.\n     * @param populate - The populate options to determine which virtuals to populate.\n     * @returns The documents with dynamic virtuals populated.\n     */\n    private async populateDynamicVirtualsForDocuments(results: T[], populate?: T_Input_Populate): Promise<T[]> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0 && results.length > 0) {\n            const populatedResults = await populateDynamicVirtuals(this.model.base, results, dynamicVirtuals, populate, undefined, this.model) as T[];\n\n            return populatedResults;\n        }\n\n        return results;\n    }\n\n    /**\n     * Finds a single document with optional population and projection.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find the document.\n     * @param projection - The fields to include/exclude in the result.\n     * @param options - Query options for the operation.\n     * @param populate - Population configuration for related documents.\n     * @returns A promise that resolves to a standardized response with the found document.\n     */\n    async findOne(\n        filter: T_QueryFilter<T> = {},\n        projection: T_ProjectionType<T> = {},\n        options: T_QueryOptions<T> = {},\n        populate?: T_Input_Populate,\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const query = this.model.findOne(normalizedFilter, projection, options).maxTimeMS(30_000).lean();\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const regularPopulate = filterDynamicVirtualsFromPopulate(populate, dynamicVirtuals);\n\n            if (regularPopulate) {\n                query.populate(regularPopulate as T_PopulateOptions);\n            }\n\n            const result = await query.exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `No ${this.getModelName()} found.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            const finalResult = await this.populateDynamicVirtualsForDocument(result, populate);\n\n            return { success: true, result: toPlainObject(finalResult) };\n        }\n        catch (error) {\n            return catchError<T>(error);\n        }\n    }\n\n    /**\n     * Finds all documents with optional population and projection.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find documents.\n     * @param projection - The fields to include/exclude in the result.\n     * @param options - Query options for the operation.\n     * @param populate - Population configuration for related documents.\n     * @returns A promise that resolves to a standardized response with the found documents.\n     */\n    async findAll(\n        filter: T_QueryFilter<T> = {},\n        projection: T_ProjectionType<T> = {},\n        options: T_QueryOptions<T> = {},\n        populate?: T_Input_Populate,\n    ): Promise<I_Return<T[]>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const query = this.model.find(normalizedFilter, projection, options).maxTimeMS(30_000).lean();\n\n            if (!options.limit) {\n                query.limit(this.defaultLimit);\n            }\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const regularPopulate = filterDynamicVirtualsFromPopulate(populate, dynamicVirtuals);\n\n            if (regularPopulate) {\n                query.populate(regularPopulate as T_PopulateOptions);\n            }\n\n            const result = await query.exec();\n\n            const finalResult = await this.populateDynamicVirtualsForDocuments(result, populate);\n\n            if (finalResult.length === this.defaultLimit && !options.limit) {\n                log.warn(`[${this.getModelName()}] 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 { success: true, result: finalResult.map(item => toPlainObject(item)) };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Finds documents with pagination support.\n     * Automatically handles dynamic virtual population if configured.\n     *\n     * @param filter - The filter criteria to find documents.\n     * @param options - Pagination options including page, limit, and population.\n     * @returns A promise that resolves to a standardized response with paginated results.\n     */\n    async findPaging(\n        filter: T_QueryFilter<T> = {},\n        options: I_PaginateOptionsWithPopulate = {},\n    ): Promise<I_Return<T_PaginateResult<T>>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const filteredOptions = { ...options };\n\n            if (options.populate) {\n                filteredOptions.populate = filterDynamicVirtualsFromPopulate(options.populate, dynamicVirtuals);\n            }\n\n            const result = await this.model.paginate(normalizedFilter, filteredOptions);\n\n            if (dynamicVirtuals && dynamicVirtuals.length > 0) {\n                const populatedDocs = await this.populateDynamicVirtualsForDocuments(result.docs, options.populate);\n\n                return { success: true, result: { ...result, docs: populatedDocs.map(item => toPlainObject(item)) } };\n            }\n\n            return { success: true, result: { ...result, docs: result.docs.map(item => toPlainObject(item)) } };\n        }\n        catch (error) {\n            return catchError<T_PaginateResult<T>>(error);\n        }\n    }\n\n    /**\n     * Performs aggregation with pagination support.\n     *\n     * @param pipeline - The aggregation pipeline stages.\n     * @param options - Pagination options for the aggregation result.\n     * @returns A promise that resolves to a standardized response with paginated aggregation results.\n     */\n    async findPagingAggregate(\n        pipeline: T_PipelineStage[],\n        options: I_PaginateOptionsWithPopulate = {},\n    ): Promise<I_Return<T_AggregatePaginateResult<T>>> {\n        try {\n            const dynamicVirtuals = this.getDynamicVirtuals();\n\n            const filteredOptions = { ...options };\n\n            if (options.populate) {\n                filteredOptions.populate = filterDynamicVirtualsFromPopulate(options.populate, dynamicVirtuals);\n            }\n\n            const result = await this.model.aggregatePaginate(\n                this.model.aggregate(pipeline),\n                filteredOptions,\n            );\n\n            const finalDocs = await this.populateDynamicVirtualsForDocuments(result.docs, options.populate);\n\n            return { success: true, result: { ...result, docs: finalDocs.map(item => item?.toObject?.() ?? item) } };\n        }\n        catch (error) {\n            return catchError<T_AggregatePaginateResult<T>>(error);\n        }\n    }\n\n    /**\n     * Counts documents matching the filter criteria.\n     *\n     * @param filter - The filter criteria to count documents.\n     * @returns A promise that resolves to a standardized response with the document count.\n     */\n    async count(filter: T_QueryFilter<T> = {}): Promise<I_Return<number>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model.countDocuments(normalizedFilter);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<number>(error);\n        }\n    }\n\n    /**\n     * Creates a single document.\n     *\n     * @param doc - The document to create.\n     * @returns A promise that resolves to a standardized response with the created document.\n     */\n    async createOne(doc: T | Partial<T>): Promise<I_Return<T>> {\n        try {\n            const result = await this.model.create(doc as unknown as Parameters<typeof this.model.create>[0]);\n\n            return { success: true, result: (result as T)?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(error);\n        }\n    }\n\n    /**\n     * Creates multiple documents with bulk insertion.\n     *\n     * @param docs - An array of documents to create.\n     * @param options - Options for the bulk insertion operation.\n     * @returns A promise that resolves to a standardized response with the created documents.\n     */\n    async createMany(\n        docs: (T | Partial<T>)[],\n        options: T_InsertManyOptions = {},\n    ): Promise<I_Return<T[]>> {\n        try {\n            const createdDocuments = await this.model.insertMany(docs, options);\n\n            return { success: true, result: createdDocuments.map(item => item?.toObject?.() ?? item) as T[] };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Updates a single document and returns the updated version.\n     *\n     * @param filter - The filter criteria to find the document to update.\n     * @param update - The update data to apply.\n     * @param options - Options for the update operation.\n     * @returns A promise that resolves to a standardized response with the updated document.\n     */\n    async updateOne(\n        filter: T_QueryFilter<T> = {},\n        update: T_UpdateQuery<T> = {},\n        options: I_UpdateOptionsExtended = {},\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .findOneAndUpdate(normalizedFilter, update, {\n                    new: true,\n                    ...options,\n                })\n                .exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `Failed to update ${this.getModelName()}.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result: result?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(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.\n     * @param options - Options for the update operation.\n     * @returns A promise that resolves to a standardized response with the update result.\n     */\n    async updateMany(\n        filter: T_QueryFilter<T> = {},\n        update: T_UpdateQuery<T> = {},\n        options: I_UpdateOptionsExtended = {},\n    ): Promise<I_Return<T_UpdateResult>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .updateMany(normalizedFilter, update, options)\n                .exec();\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T_UpdateResult>(error);\n        }\n    }\n\n    /**\n     * Deletes a single document and returns the deleted version.\n     *\n     * @param filter - The filter criteria to find the document to delete.\n     * @param options - Options for the delete operation.\n     * @returns A promise that resolves to a standardized response with the deleted document.\n     */\n    async deleteOne(\n        filter: T_QueryFilter<T> = {},\n        options: I_DeleteOptionsExtended = {},\n    ): Promise<I_Return<T>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model\n                .findOneAndDelete(normalizedFilter, options)\n                .exec();\n\n            if (!result) {\n                return {\n                    success: false,\n                    message: `No ${this.getModelName()} found to delete.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result: result?.toObject?.() ?? result };\n        }\n        catch (error) {\n            return catchError<T>(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     * @param options - Options for the delete operation.\n     * @returns A promise that resolves to a standardized response with the delete result.\n     */\n    async deleteMany(\n        filter: T_QueryFilter<T> = {},\n        options: I_DeleteOptionsExtended = {},\n    ): Promise<I_Return<T_DeleteResult>> {\n        try {\n            const normalizedFilter = normalizeMongoFilter(filter);\n            const result = await this.model.deleteMany(normalizedFilter, options).exec();\n\n            if (result.deletedCount === 0) {\n                return {\n                    success: false,\n                    message: `No documents found to delete.`,\n                    code: RESPONSE_STATUS.NOT_FOUND.CODE,\n                };\n            }\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T_DeleteResult>(error);\n        }\n    }\n\n    /**\n     * Creates a unique short ID based on a given ID.\n     * This method generates multiple short IDs with increasing lengths and finds the first available one.\n     *\n     * @param id - The base ID to generate short IDs from.\n     * @param length - The initial length for short ID generation (default: 4).\n     * @returns A promise that resolves to a standardized response with the unique short ID.\n     */\n    async createShortId(id: string, length = 4): Promise<I_Return<string>> {\n        try {\n            const maxRetries = 10;\n            const shortIds = Array.from({ length: maxRetries }, (_, index) =>\n                generateShortId(id, index + length));\n\n            // Use a single $in query instead of 10 parallel exists() calls\n            const existingDocs = await this.model\n                .find({ shortId: { $in: shortIds } })\n                .select('shortId')\n                .lean();\n\n            const existingShortIds = new Set(\n                existingDocs.map((d: Record<string, unknown>) => d['shortId'] as string),\n            );\n\n            const availableShortId = shortIds.find(s => !existingShortIds.has(s));\n\n            if (availableShortId) {\n                return { success: true, result: availableShortId };\n            }\n\n            return {\n                success: false,\n                message: 'Failed to create a unique shortId',\n                code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n            };\n        }\n        catch (error) {\n            return catchError<string>(error);\n        }\n    }\n\n    /**\n     * Creates a query for slug existence checking.\n     * This method generates a query that checks for slug existence in both current and historical slug fields.\n     *\n     * @param options - Configuration for slug query generation including slug, field, and filter.\n     * @param options.slug - The slug string to check for existence.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.isObject - Whether the slug is stored as an object with nested fields.\n     * @param options.haveHistory - Whether to check historical slug fields for existence.\n     * @param options.filter - Additional filter conditions to apply to the query.\n     * @returns A MongoDB query object for checking slug existence.\n     */\n    createSlugQuery({ slug, field, isObject, haveHistory = false, filter }: I_Input_GenerateSlug<T>) {\n        const baseFilter = { ...(filter ?? {}) };\n\n        return isObject\n            ? {\n                    ...baseFilter,\n                    $or: [\n                        { [`slug.${field}`]: slug },\n                        ...(haveHistory ? [{ slugHistory: { $elemMatch: { [`slug.${field}`]: slug } } }] : []),\n                    ],\n                }\n            : {\n                    ...baseFilter,\n                    $or: [\n                        { slug },\n                        ...(haveHistory ? [{ slugHistory: slug }] : []),\n                    ],\n                };\n    }\n\n    /**\n     * Creates a unique slug based on a given string.\n     * This method generates multiple slug variations and finds the first available one.\n     *\n     * @param options - Configuration for slug generation including slug, field, and filter.\n     * @param options.slug - The base slug string to make unique.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.isObject - Whether the slug is stored as an object with nested fields.\n     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.\n     * @param options.filter - Additional filter conditions to apply when checking slug existence.\n     * @returns A promise that resolves to a unique slug string.\n     */\n    async createUniqueSlug({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): Promise<string> {\n        if (!slug || typeof slug !== 'string') {\n            throw new Error('Invalid slug provided: must be a non-empty string');\n        }\n\n        const baseSlug = generateSlug(slug);\n\n        const baseExists = await this.model.exists(\n            this.createSlugQuery({ slug: baseSlug, field, isObject, haveHistory, filter }),\n        );\n\n        if (!baseExists) {\n            return baseSlug;\n        }\n\n        // Batch query: check all slug variations in a single database call instead of N+1 sequential queries\n        const variants = Array.from(\n            { length: MONGO_SLUG_MAX_ATTEMPTS },\n            (_, i) => `${baseSlug}-${i + 1}`,\n        );\n\n        const slugQueries = variants.map(s =>\n            this.createSlugQuery({ slug: s, field, isObject, haveHistory, filter }),\n        );\n\n        const slugField = isObject ? `slug.${field as string}` : 'slug';\n        const existingDocs = await this.model\n            .find({ $or: slugQueries.map(q => q.$or).flat() })\n            .select(slugField)\n            .lean();\n\n        const existingSlugs = new Set(\n            existingDocs.map((d: Record<string, unknown>) => {\n                if (isObject) {\n                    const slug = d['slug'] as Record<string, unknown> | undefined;\n                    return slug?.[field as string];\n                }\n                return d['slug'];\n            }),\n        );\n\n        const available = variants.find(s => !existingSlugs.has(s));\n\n        if (available) {\n            return available;\n        }\n\n        const timestamp = Date.now();\n        const randomSuffix = generateRandomString(6);\n\n        return `${baseSlug}-${timestamp}-${randomSuffix}`;\n    }\n\n    /**\n     * Creates a slug for a document field.\n     * This method handles both simple string fields and object fields with nested slug generation.\n     *\n     * @param options - Configuration for slug creation including field, source document, and filter.\n     * @param options.field - The field name to create a slug for.\n     * @param options.from - The source document containing the field value.\n     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.\n     * @param options.filter - Additional filter conditions to apply when checking slug existence.\n     * @returns A promise that resolves to a standardized response with the created slug(s).\n     */\n    async createSlug<R = string>({ field, from, filter, haveHistory }: I_Input_CreateSlug<T>): Promise<I_Return<R>> {\n        try {\n            const fieldValue = from[field as keyof T];\n            const isObjectValue = isObject(fieldValue);\n\n            if (isObjectValue) {\n                const uniqueSlug = Object.fromEntries(\n                    await Promise.all(\n                        Object.entries(fieldValue).map(async ([key, value]) => {\n                            const uniqueSlugForKey = await this.createUniqueSlug({\n                                slug: value as string,\n                                field: key,\n                                isObject: true,\n                                haveHistory,\n                                filter,\n                            });\n                            return [key, uniqueSlugForKey];\n                        }),\n                    ),\n                );\n\n                return { success: true, result: uniqueSlug as R };\n            }\n\n            const uniqueSlug = await this.createUniqueSlug({\n                slug: fieldValue as string,\n                field,\n                isObject: false,\n                haveHistory,\n                filter,\n            });\n\n            return { success: true, result: uniqueSlug as R };\n        }\n        catch (error) {\n            return catchError<R>(error);\n        }\n    }\n\n    /**\n     * Checks if a slug already exists in the collection.\n     * This method verifies slug existence in both current and historical slug fields.\n     *\n     * @param options - Configuration for slug checking including slug, field, source document, and filter.\n     * @param options.slug - The slug string to check for existence.\n     * @param options.field - The field name for object-based slug checking.\n     * @param options.from - The source document containing the field value.\n     * @param options.haveHistory - Whether to check historical slug fields for existence.\n     * @param options.filter - Additional filter conditions to apply to the query.\n     * @returns A promise that resolves to a standardized response indicating whether the slug exists.\n     */\n    async checkSlug({ slug, field, from, filter, haveHistory }: I_Input_CheckSlug<T>): Promise<I_Return<boolean>> {\n        try {\n            const fieldValue = from[field as keyof T];\n            const isObjectValue = isObject(fieldValue);\n\n            if (isObjectValue) {\n                const values = Object.values(fieldValue);\n                const nestedSlugs = values.map(value => generateSlug(value as string));\n\n                const existenceChecks = await Promise.all(\n                    nestedSlugs.map(nestedSlug =>\n                        this.model.exists(this.createSlugQuery({\n                            slug: nestedSlug,\n                            field,\n                            isObject: true,\n                            haveHistory,\n                            filter,\n                        })),\n                    ),\n                );\n\n                if (existenceChecks.some(exists => exists)) {\n                    return { success: true, result: true };\n                }\n\n                return { success: true, result: false };\n            }\n\n            const baseSlug = generateSlug(slug);\n            const exists = await this.model.exists(this.createSlugQuery({\n                slug: baseSlug,\n                field,\n                isObject: false,\n                filter,\n            }));\n\n            return { success: true, result: exists !== null };\n        }\n        catch (error) {\n            return catchError<boolean>(error);\n        }\n    }\n\n    /**\n     * Performs aggregation operations on the collection.\n     *\n     * @param pipeline - The aggregation pipeline stages to execute.\n     * @returns A promise that resolves to a standardized response with the aggregation results.\n     */\n    async aggregate(pipeline: T_PipelineStage[]): Promise<I_Return<T[]>> {\n        try {\n            const result = await this.model.aggregate<T>(pipeline);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<T[]>(error);\n        }\n    }\n\n    /**\n     * Retrieves distinct values for the specified key from the collection.\n     *\n     * @param key - The field for which to return distinct values.\n     * @param filter - The filter query to apply (optional).\n     * @param options - Additional options for the distinct operation (optional).\n     * @returns A promise that resolves to a standardized response with the array of distinct values.\n     */\n    async distinct(\n        key: string,\n        filter: T_QueryFilter<T> = {},\n        options: T_QueryOptions<T> = {},\n    ): Promise<I_Return<unknown[]>> {\n        try {\n            const result = await this.model.distinct(key, filter, options);\n\n            return { success: true, result };\n        }\n        catch (error) {\n            return catchError<unknown[]>(error);\n        }\n    }\n}\n"],"mappings":"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"}

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

@@ -4,16 +4,24 @@ import { C_Db, C_Document, T_DeleteResult, T_Filter, T_UpdateResult, T_WithId }
  * MongoDB native driver controller for direct database operations.
  * This class provides a simplified interface for MongoDB operations using the native driver,
  * with automatic generic field generation and standardized response formatting.
+ *
+ * @see I_MongoController for the shared polymorphic interface (use via type assertion when needed).
  */
 export declare class MongoController<D extends Partial<C_Document>> {
     private collection;
+    private defaultLimit;
+    private collectionName;
     /**
      * Creates a new MongoDB controller instance.
      *
      * @param db - The MongoDB database instance.
      * @param collectionName - The name of the collection to operate on.
+     * @param options - Optional configuration for the controller.
+     * @param options.defaultLimit - Maximum documents returned by findAll when no limit is specified (default: 10,000).
      */
-    constructor(db: C_Db, collectionName: string);
+    constructor(db: C_Db, collectionName: string, options?: {
+        defaultLimit?: number;
+    });
     /**
      * Creates a single document in the collection.
      * This method adds generic fields (id, isDel, timestamps) to the document before insertion.

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

@@ -1,17 +1,19 @@
 import { RESPONSE_STATUS as e } from "../../constant/response-status.js";
-import { catchError as t } from "../log/log.util.js";
-import { mongo as n } from "./mongo.util.js";
+import { catchError as t, log as n } from "../log/log.util.js";
+import { mongo as r } from "./mongo.util.js";
 //#region src/node/mongo/mongo.controller.native.ts
-var r = class {
+var i = class {
 	collection;
-	constructor(e, t) {
-		this.collection = e.collection(t);
+	defaultLimit;
+	collectionName;
+	constructor(e, t, n) {
+		this.collection = e.collection(t), this.collectionName = t, this.defaultLimit = n?.defaultLimit ?? 1e4;
 	}
-	async createOne(r) {
+	async createOne(n) {
 		try {
 			let t = {
-				...n.createGenericFields(),
-				...r
+				...r.createGenericFields(),
+				...n
 			};
 			return (await this.collection.insertOne(t)).acknowledged ? {
 				success: !0,
@@ -26,10 +28,10 @@ var r = class {
 			return t(e);
 		}
 	}
-	async createMany(r) {
+	async createMany(n) {
 		try {
-			let t = r.map((e) => ({
-				...n.createGenericFields(),
+			let t = n.map((e) => ({
+				...r.createGenericFields(),
 				...e
 			})), i = await this.collection.insertMany(t);
 			return i.insertedCount === 0 ? {
@@ -63,10 +65,11 @@ var r = class {
 	}
 	async findAll(e = {}) {
 		try {
-			return {
+			let t = await this.collection.find(e).limit(this.defaultLimit).maxTimeMS(3e4).toArray();
+			return t.length === this.defaultLimit && n.warn(`[${this.collectionName}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
 				success: !0,
 				message: "Documents retrieved successfully",
-				result: await this.collection.find(e).limit(1e4).maxTimeMS(3e4).toArray()
+				result: t
 			};
 		} catch (e) {
 			return t(e);
@@ -150,6 +153,6 @@ var r = class {
 	}
 };
 //#endregion
-export { r as MongoController };
+export { i as MongoController };
 
 //# sourceMappingURL=mongo.controller.native.js.map