@cyberskill/shared 3.12.0 → 3.14.0

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 { isObject } from '#util/common/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, populateDynamicVirtuals } from './mongo.dynamic-populate.js';\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: 1,000).\n     */\n    constructor(private model: I_ExtendedModel<T>, options?: { defaultLimit?: number }) {\n        this.defaultLimit = options?.defaultLimit ?? 1_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 populated = await this.populateDynamic([result], populate);\n        return populated[0] ?? 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        return this.populateDynamic(results, populate);\n    }\n\n    /**\n     * Internal helper that populates dynamic virtuals for an array of documents.\n     * Shared implementation used by both single-document and multi-document methods.\n     */\n    private async populateDynamic(results: T[], populate?: T_Input_Populate): Promise<T[]> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0 && results.length > 0) {\n            return await populateDynamicVirtuals(this.model.base, results, dynamicVirtuals, populate, undefined, this.model) as T[];\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            const truncated = finalResult.length === this.defaultLimit && !options.limit;\n\n            if (truncated) {\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)), truncated };\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 => toPlainObject(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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"}
+{"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 { isObject } from '#util/common/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_MAX_TIME_MS, MONGO_SLUG_MAX_ATTEMPTS } from './mongo.constant.js';\nimport { wrapNotFound } from './mongo.controller.helpers.js';\nimport { filterDynamicVirtualsFromPopulate, populateDynamicVirtuals } from './mongo.dynamic-populate.js';\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    private defaultProjection: T_ProjectionType<T>;\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: 1,000).\n     * @param options.defaultProjection - Default projection to apply to findOne and findAll queries.\n     */\n    constructor(private model: I_ExtendedModel<T>, options?: { defaultLimit?: number; defaultProjection?: T_ProjectionType<T> }) {\n        this.defaultLimit = options?.defaultLimit ?? 1_000;\n        this.defaultProjection = options?.defaultProjection ?? {};\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 populated = await this.populateDynamic([result], populate);\n        return populated[0] ?? 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        return this.populateDynamic(results, populate);\n    }\n\n    /**\n     * Internal helper that populates dynamic virtuals for an array of documents.\n     * Shared implementation used by both single-document and multi-document methods.\n     */\n    private async populateDynamic(results: T[], populate?: T_Input_Populate): Promise<T[]> {\n        const dynamicVirtuals = this.getDynamicVirtuals();\n\n        if (dynamicVirtuals && dynamicVirtuals.length > 0 && results.length > 0) {\n            return await populateDynamicVirtuals(this.model.base, results, dynamicVirtuals, populate, undefined, this.model) as T[];\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 appliedProjection = Object.keys(projection).length > 0 ? projection : Object.keys(this.defaultProjection).length > 0 ? this.defaultProjection : projection;\n            const query = this.model.findOne(normalizedFilter, appliedProjection, options).maxTimeMS(MONGO_MAX_TIME_MS).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 wrapNotFound(this.getModelName());\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 appliedProjection = Object.keys(projection).length > 0 ? projection : Object.keys(this.defaultProjection).length > 0 ? this.defaultProjection : projection;\n            const query = this.model.find(normalizedFilter, appliedProjection, options).maxTimeMS(MONGO_MAX_TIME_MS).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            const truncated = finalResult.length === this.defaultLimit && !options.limit;\n\n            if (truncated) {\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)), truncated };\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 => toPlainObject(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 wrapNotFound(this.getModelName());\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 wrapNotFound(this.getModelName());\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 wrapNotFound('documents');\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/{src/node → node}/mongo/mongo.controller.native.d.ts

@@ -1,5 +1,5 @@
-import { I_Return } from '../../../typescript/index.js';
-import { C_Db, C_Document, T_DeleteResult, T_Filter, T_UpdateResult, T_WithId } from './mongo.type.js';
+import { I_Return } from '../../typescript/index.js';
+import { C_Db, C_Document, T_BulkWriteOperation, T_BulkWriteResult, T_DeleteResult, T_Filter, T_UpdateResult, T_WithId } from './mongo.type.js';
 /**
  * MongoDB native driver controller for direct database operations.
  * This class provides a simplified interface for MongoDB operations using the native driver,
@@ -51,7 +51,10 @@ export declare class MongoController<D extends Partial<C_Document>> {
      * @param filter - The filter criteria to find documents (defaults to empty object for all documents).
      * @returns A promise that resolves to a standardized response with the found documents.
      */
-    findAll(filter?: T_Filter<D>): Promise<I_Return<T_WithId<D>[]>>;
+    findAll(filter?: T_Filter<D>, options?: {
+        skip?: number;
+        limit?: number;
+    }): Promise<I_Return<T_WithId<D>[]>>;
     /**
      * Counts documents matching the filter criteria.
      *
@@ -89,4 +92,28 @@ export declare class MongoController<D extends Partial<C_Document>> {
      * @returns A promise that resolves to a standardized response with the delete result.
      */
     deleteMany(filter: T_Filter<D>): Promise<I_Return<T_DeleteResult>>;
+    /**
+     * Executes multiple write operations in a single batch.
+     * Use this for high-performance ingestion or batched updates.
+     * Note: This method does NOT automatically add generic fields (id, timestamps)
+     * to the documents. If required, inject these fields before invoking bulkWrite.
+     *
+     * @param operations - The array of bulk write operations.
+     * @returns A promise that resolves to a standardized response with the bulk write result.
+     */
+    bulkWrite(operations: T_BulkWriteOperation<D>[]): Promise<I_Return<T_BulkWriteResult>>;
 }
+/**
+ * Factory function to create a native MongoController.
+ * Use this method to construct controllers in migration scripts or services.
+ *
+ * @param db - The MongoDB database instance.
+ * @param collectionName - The name of the collection.
+ * @param options - Controller options.
+ * @param options.defaultLimit - Optional default limit for pagination.
+ * @returns A new MongoController instance for the given collection.
+ * @since 3.13.0
+ */
+export declare function createMongoController<D extends Partial<C_Document>>(db: C_Db, collectionName: string, options?: {
+    defaultLimit?: number;
+}): MongoController<D>;

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

@@ -1,8 +1,9 @@
 import { catchError as e, log as t } from "../log/log.util.js";
-import { mongo as n } from "./mongo.util.js";
+import { MONGO_MAX_TIME_MS as n } from "./mongo.constant.js";
 import { wrapError as r, wrapNotFound as i } from "./mongo.controller.helpers.js";
+import { mongo as a } from "./mongo.util.js";
 //#region src/node/mongo/mongo.controller.native.ts
-var a = class {
+var o = class {
 	collection;
 	defaultLimit;
 	collectionName;
@@ -12,7 +13,7 @@ var a = class {
 	async createOne(t) {
 		try {
 			let e = {
-				...n.createGenericFields(),
+				...a.createGenericFields(),
 				...t
 			};
 			return (await this.collection.insertOne(e)).acknowledged ? {
@@ -27,12 +28,12 @@ var a = class {
 	async createMany(t) {
 		try {
 			let e = t.map((e) => ({
-				...n.createGenericFields(),
+				...a.createGenericFields(),
 				...e
-			})), i = await this.collection.insertMany(e);
-			return i.insertedCount === 0 ? r("No documents were inserted") : {
+			})), n = await this.collection.insertMany(e);
+			return n.insertedCount === 0 ? r("No documents were inserted") : {
 				success: !0,
-				message: `${i.insertedCount} documents created successfully`,
+				message: `${n.insertedCount} documents created successfully`,
 				result: e
 			};
 		} catch (t) {
@@ -41,7 +42,7 @@ var a = class {
 	}
 	async findOne(t) {
 		try {
-			let e = await this.collection.findOne(t, { maxTimeMS: 3e4 });
+			let e = await this.collection.findOne(t, { maxTimeMS: n });
 			return e ? {
 				success: !0,
 				message: "Document found",
@@ -51,14 +52,16 @@ var a = class {
 			return e(t);
 		}
 	}
-	async findAll(n = {}) {
+	async findAll(r = {}, i) {
 		try {
-			let e = await this.collection.find(n).limit(this.defaultLimit).maxTimeMS(3e4).toArray(), r = e.length === this.defaultLimit;
-			return r && t.warn(`[${this.collectionName}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
+			let e = i?.limit ?? this.defaultLimit, a = this.collection.find(r).limit(e).maxTimeMS(n);
+			i?.skip && (a = a.skip(i.skip));
+			let o = await a.toArray(), s = o.length === e;
+			return s && t.warn(`[${this.collectionName}] findAll returned exactly ${e} documents (the limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
 				success: !0,
 				message: "Documents retrieved successfully",
-				result: e,
-				truncated: r
+				result: o,
+				truncated: s
 			};
 		} catch (t) {
 			return e(t);
@@ -124,8 +127,22 @@ var a = class {
 			return e(t);
 		}
 	}
+	async bulkWrite(t) {
+		try {
+			return t.length ? {
+				success: !0,
+				message: "Bulk write executed successfully",
+				result: await this.collection.bulkWrite(t)
+			} : r("No bulk write operations provided");
+		} catch (t) {
+			return e(t);
+		}
+	}
 };
+function s(e, t, n) {
+	return new o(e, t, n);
+}
 //#endregion
-export { a as MongoController };
+export { o as MongoController, s as createMongoController };
 
 //# sourceMappingURL=mongo.controller.native.js.map

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 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 { wrapError, wrapNotFound } from './mongo.controller.helpers.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: 1,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 ?? 1_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 wrapError('Document creation failed');\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 wrapError('No documents were inserted');\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 wrapNotFound('Document');\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            const truncated = result.length === this.defaultLimit;\n\n            if (truncated) {\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                truncated,\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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 type { C_Collection, C_Db, C_Document, T_BulkWriteOperation, T_BulkWriteResult, T_DeleteResult, T_Filter, T_OptionalUnlessRequiredId, T_UpdateResult, T_WithId } from './mongo.type.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { MONGO_MAX_TIME_MS } from './mongo.constant.js';\nimport { wrapError, wrapNotFound } from './mongo.controller.helpers.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: 1,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 ?? 1_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 wrapError('Document creation failed');\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 wrapError('No documents were inserted');\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: MONGO_MAX_TIME_MS });\n\n            if (!result) {\n                return wrapNotFound('Document');\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        options?: { skip?: number; limit?: number },\n    ): Promise<I_Return<T_WithId<D>[]>> {\n        try {\n            const limit = options?.limit ?? this.defaultLimit;\n            let query = this.collection.find(filter).limit(limit).maxTimeMS(MONGO_MAX_TIME_MS);\n\n            if (options?.skip) {\n                query = query.skip(options.skip);\n            }\n\n            const result = await query.toArray();\n\n            const truncated = result.length === limit;\n\n            if (truncated) {\n                log.warn(`[${this.collectionName}] findAll returned exactly ${limit} documents (the 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                truncated,\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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 wrapNotFound('No documents matched the filter');\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    /**\n     * Executes multiple write operations in a single batch.\n     * Use this for high-performance ingestion or batched updates.\n     * Note: This method does NOT automatically add generic fields (id, timestamps)\n     * to the documents. If required, inject these fields before invoking bulkWrite.\n     *\n     * @param operations - The array of bulk write operations.\n     * @returns A promise that resolves to a standardized response with the bulk write result.\n     */\n    async bulkWrite(\n        operations: T_BulkWriteOperation<D>[],\n    ): Promise<I_Return<T_BulkWriteResult>> {\n        try {\n            if (!operations.length) {\n                return wrapError('No bulk write operations provided');\n            }\n\n            const result = await this.collection.bulkWrite(operations);\n\n            return {\n                success: true,\n                message: 'Bulk write executed successfully',\n                result,\n            };\n        }\n        catch (error) {\n            return catchError<T_BulkWriteResult>(error);\n        }\n    }\n}\n\n/**\n * Factory function to create a native MongoController.\n * Use this method to construct controllers in migration scripts or services.\n *\n * @param db - The MongoDB database instance.\n * @param collectionName - The name of the collection.\n * @param options - Controller options.\n * @param options.defaultLimit - Optional default limit for pagination.\n * @returns A new MongoController instance for the given collection.\n * @since 3.13.0\n */\nexport function createMongoController<D extends Partial<C_Document>>(\n    db: C_Db,\n    collectionName: string,\n    options?: { defaultLimit?: number },\n): MongoController<D> {\n    return new MongoController<D>(db, collectionName, options);\n}\n"],"mappings":"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"}

package/dist/{src/node → node}/mongo/mongo.controller.type.d.ts

@@ -1,4 +1,4 @@
-import { I_Return } from '../../../typescript/index.js';
+import { I_Return } from '../../typescript/index.js';
 import { T_DeleteResult, T_UpdateResult, T_WithId } from './mongo.type.js';
 /**
  * Shared controller interface for MongoDB operations.

package/dist/{src/node → node}/mongo/mongo.type.d.ts

@@ -1,4 +1,4 @@
-import { DeleteResult, Filter, InsertManyResult, InsertOneResult, OptionalUnlessRequiredId, UpdateResult, WithId, Collection, Db } from 'mongodb';
+import { AnyBulkWriteOperation, BulkWriteResult, DeleteResult, Filter, InsertManyResult, InsertOneResult, OptionalUnlessRequiredId, UpdateResult, WithId, Collection, Db } from 'mongodb';
 import { AggregatePaginateModel, AggregatePaginateResult, ClientSession, ErrorHandlingMiddlewareFunction, ErrorHandlingMiddlewareWithOption, InsertManyOptions, PaginateModel, PaginateOptions, PaginateResult, PipelineStage, PopulateOption, PopulateOptions, PostMiddlewareFunction, PreMiddlewareFunction, PreSaveMiddlewareFunction, ProjectionType, QueryFilter, QueryOptions, QueryWithHelpers, Schema, SchemaDefinition, UpdateQuery, UpdateWriteOpResult, default as mongoose, Document, Model } from 'mongoose';
 export declare class C_Db extends Db {
 }
@@ -7,6 +7,8 @@ export type T_InsertOneResult<T> = InsertOneResult<T>;
 export type T_InsertManyResult<T> = InsertManyResult<T>;
 export type T_UpdateResult = UpdateResult | UpdateWriteOpResult;
 export type T_DeleteResult = DeleteResult;
+export type T_BulkWriteOperation<T extends import('mongodb').Document = import('mongodb').Document> = AnyBulkWriteOperation<T>;
+export type T_BulkWriteResult = BulkWriteResult;
 export type T_WithId<T> = WithId<T>;
 export type T_OptionalUnlessRequiredId<T> = OptionalUnlessRequiredId<T>;
 export declare class C_Document extends Document {

package/dist/{src/node → node}/mongo/mongo.util.d.ts

@@ -42,6 +42,7 @@ interface I_MongoUtils {
     isDynamicVirtual: <T, R extends string>(options?: T_VirtualOptions<T, R>) => options is I_DynamicVirtualOptions<T, R>;
     getNewRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T[]>;
     getExistingRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T_WithId<T>[]>;
+    health: (mongooseInstance: typeof mongooseRaw) => Record<string, unknown>;
 }
 /**
  * MongoDB utility object providing comprehensive database operations and utilities.

package/dist/node/mongo/mongo.util.js

@@ -4,9 +4,9 @@ import { validate as r } from "../../util/validate/validate.util.js";
 import { addGitIgnoreEntry as i, writeFileSync as a } from "../fs/fs.util.js";
 import { MIGRATE_MONGO_CONFIG as o, PATH as s } from "../path/path.constant.js";
 import "./mongo.populate.js";
-import c from "mongoose-aggregate-paginate-v2";
-import l from "mongoose-paginate-v2";
-import { randomUUID as u } from "node:crypto";
+import { randomUUID as c } from "node:crypto";
+import l from "mongoose-aggregate-paginate-v2";
+import u from "mongoose-paginate-v2";
 //#region src/node/mongo/mongo.util.ts
 function d(e) {
 	return e === e.toUpperCase() ? e.charAt(0).toUpperCase() + e.slice(1).toLowerCase() : e;
@@ -14,7 +14,7 @@ function d(e) {
 var f = {
 	createGenericFields() {
 		return {
-			id: u(),
+			id: c(),
 			isDel: !1,
 			createdAt: /* @__PURE__ */ new Date(),
 			updatedAt: /* @__PURE__ */ new Date()
@@ -32,7 +32,7 @@ var f = {
 		return new e.Schema({
 			id: {
 				type: String,
-				default: () => u(),
+				default: () => c(),
 				unique: !0
 			},
 			isDel: {
@@ -69,9 +69,9 @@ var f = {
 			schema: n,
 			virtuals: r
 		});
-		(i || a) && f.applyPlugins(s, [i && l, a && c]), f.applyMiddlewares(s, o);
-		let u = e.model(t, s);
-		return r.length > 0 && (u._virtualConfigs = r), u;
+		(i || a) && f.applyPlugins(s, [i && u, a && l]), f.applyMiddlewares(s, o);
+		let c = e.model(t, s);
+		return r.length > 0 && (c._virtualConfigs = r), c;
 	},
 	validator: {
 		isRequired() {
@@ -82,7 +82,7 @@ var f = {
 		isUnique(e) {
 			return async function(t) {
 				if (!Array.isArray(e) || e.length === 0) throw Error("Fields must be a non-empty array of strings.");
-				let n = { $or: e.map((e) => ({ [e]: t })) };
+				let n = { $or: e.map((e) => ({ [e]: { $eq: t } })) };
 				return !await this.constructor.exists(n);
 			};
 		},
@@ -122,16 +122,37 @@ var f = {
 		return !!(e && typeof e.ref == "function");
 	},
 	async getNewRecords(e, t, n, r = {}) {
-		let i = await e.findAll(r);
-		if (!i.success) throw Error(`Failed to query existing records: ${i.message}`);
-		if ("truncated" in i && i.truncated) throw Error("getNewRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.");
-		return t.filter((e) => !i.result.some((t) => n(t, e)));
+		let i = 1e3, a = 0, o = !1, s = [];
+		for (; !o;) {
+			let t = await e.findAll(r, {
+				skip: a,
+				limit: i
+			});
+			if (!t.success) throw Error(`Failed to query existing records on skip ${a}: ${t.message}`);
+			s.push(...t.result), t.truncated && t.result.length === i ? a += i : o = !0;
+		}
+		return t.filter((e) => !s.some((t) => n(t, e)));
 	},
 	async getExistingRecords(e, t, n, r = {}) {
-		let i = await e.findAll(r);
-		if (!i.success) throw Error(`Failed to query existing records: ${i.message}`);
-		if ("truncated" in i && i.truncated) throw Error("getExistingRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.");
-		return i.result.filter((e) => t.some((t) => n(e, t)));
+		let i = 1e3, a = 0, o = !1, s = [];
+		for (; !o;) {
+			let t = await e.findAll(r, {
+				skip: a,
+				limit: i
+			});
+			if (!t.success) throw Error(`Failed to query existing records on skip ${a}: ${t.message}`);
+			s.push(...t.result), t.truncated && t.result.length === i ? a += i : o = !0;
+		}
+		return s.filter((e) => t.some((t) => n(e, t)));
+	},
+	health(e) {
+		let t = e.connection;
+		return {
+			readyState: t.readyState,
+			host: t.host,
+			name: t.name,
+			models: Object.keys(e.models).length
+		};
 	}
 };
 //#endregion