@cyberskill/shared 3.0.0 → 3.2.0

package/dist/node/log/log.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.util.js","sources":["../../../src/node/log/log.util.ts"],"sourcesContent":["import type { ChalkInstance } from 'chalk';\n\nimport chalk from 'chalk';\nimport consola from 'consola';\nimport { GraphQLError } from 'graphql';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { getEnv } from '#config/env/index.js';\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { I_CatchErrorOptions, I_IssueEntry, I_Log, I_ThrowError } from './log.type.js';\n\nconst env = getEnv();\n\n/**\n * Throws a standardized error with optional status information and type specification.\n * This function creates and throws errors that can be either GraphQL errors (with extensions)\n * or standard JavaScript errors, depending on the specified type.\n *\n * @param options - Error configuration including message, status information, and error type.\n * @param options.message - The error message to display.\n * @param options.status - The response status information (defaults to INTERNAL_SERVER_ERROR).\n * @param options.type - The type of error to throw ('graphql' or 'rest', defaults to 'graphql').\n * @throws {GraphQLError} When type is 'graphql', throws a GraphQL error with extensions.\n * @throws {Error} When type is 'rest' or unspecified, throws a standard JavaScript error.\n */\nexport function throwError({\n    message,\n    status = RESPONSE_STATUS.INTERNAL_SERVER_ERROR,\n    type = 'graphql',\n}: I_ThrowError): never {\n    const responseMessage\n        = message ?? status.MESSAGE ?? 'Internal server error';\n\n    if (type === 'graphql') {\n        throw new GraphQLError(responseMessage, {\n            extensions: { code: status.CODE },\n        });\n    }\n\n    else {\n        throw new Error(responseMessage);\n    }\n}\n\nif (!env.DEBUG) {\n    consola.level = 4;\n}\n\n/**\n * Gets a chalk color instance by keyword name.\n * This function safely retrieves a chalk color function by name, falling back to green\n * if the specified color is not available or invalid.\n *\n * @param color - The color keyword to get the chalk instance for.\n * @returns A chalk instance for the specified color, or green as fallback.\n */\nfunction chalkKeyword(color: string): ChalkInstance {\n    const chalkColor = chalk[color as keyof typeof chalk];\n\n    return typeof chalkColor === 'function' ? (chalkColor as ChalkInstance) : chalk.green;\n}\n\n/**\n * Enhanced logging interface that extends consola with custom functionality.\n * This object provides all standard consola logging methods plus additional features\n * like boxed log printing for structured error/warning display.\n */\nexport const log: I_Log = {\n    silent: consola.silent,\n    level: consola.level,\n    fatal: consola.fatal,\n    error: consola.error,\n    warn: consola.warn,\n    log: consola.log,\n    info: consola.info,\n    success: consola.success,\n    ready: consola.ready,\n    start: consola.start,\n    box: consola.box,\n    debug: consola.debug,\n    trace: consola.trace,\n    verbose: consola.verbose,\n    /**\n     * Prints a boxed log with structured issue information.\n     * This method displays issues (errors or warnings) in a formatted box with:\n     * - File paths and line/column positions\n     * - Rule violations (if applicable)\n     * - Error/warning messages\n     * - Color-coded output based on issue type\n     *\n     * @param title - The title to display in the box header.\n     * @param issues - An array of issue entries to display.\n     * @param color - The color to use for highlighting (defaults to 'red').\n     */\n    printBoxedLog(title: string, issues: I_IssueEntry[], color = 'red') {\n        if (!issues?.length) {\n            consola.box(chalk.green(title));\n            return;\n        }\n\n        issues.forEach(({ file, position, rule, message }) => {\n            const positionSuffix = position ? `:${position}` : '';\n            const filePath = `${file}${positionSuffix}`;\n            consola.log(`${chalk.gray('File:')} ${chalk.blue(filePath)}`);\n\n            if (rule) {\n                consola.log(`   ${chalkKeyword(color)('Rule:')} ${rule}`);\n            }\n\n            consola.log(`   ${chalkKeyword(color)('Message:')} ${message}`);\n        });\n\n        consola.box(chalkKeyword(color)(`${title} : ${issues.length}`));\n\n        consola.log(chalk.gray('─'.repeat(40)));\n    },\n};\n\n/**\n * Catches and handles errors with configurable behavior.\n * This function provides a standardized way to handle errors with options for:\n * - Logging control (whether to log the error)\n * - Return value specification (what to return on error)\n * - Custom callback execution (additional error handling)\n *\n * @param errorInput - The error to catch and handle.\n * @param options - Configuration options for error handling behavior.\n * @returns Either the specified return value or a standardized error response object.\n */\nexport function catchError<T = unknown>(errorInput: unknown, options: I_CatchErrorOptions & { returnValue: T }): T;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T>;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T> | T {\n    const { shouldLog = true, returnValue, callback } = options ?? {};\n\n    const error = errorInput instanceof Error\n        ? errorInput\n        : new Error(typeof errorInput === 'string' ? errorInput : 'Unknown error');\n\n    if (shouldLog) {\n        log.error(error.message);\n    }\n\n    if (callback && typeof callback === 'function') {\n        callback(error);\n    }\n\n    if (returnValue) {\n        return returnValue as T;\n    }\n\n    return {\n        success: false,\n        message: error.message,\n        code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n    };\n}\n"],"names":["env","getEnv","throwError","message","status","RESPONSE_STATUS","type","responseMessage","GraphQLError","consola","chalkKeyword","color","chalkColor","chalk","log","title","issues","file","position","rule","positionSuffix","filePath","catchError","errorInput","options","shouldLog","returnValue","callback","error"],"mappings":";;;;;AAaA,MAAMA,IAAMC,EAAA;AAcL,SAASC,EAAW;AAAA,EACvB,SAAAC;AAAA,EACA,QAAAC,IAASC,EAAgB;AAAA,EACzB,MAAAC,IAAO;AACX,GAAwB;AACpB,QAAMC,IACAJ,KAAWC,EAAO,WAAW;AAEnC,QAAIE,MAAS,YACH,IAAIE,EAAaD,GAAiB;AAAA,IACpC,YAAY,EAAE,MAAMH,EAAO,KAAA;AAAA,EAAK,CACnC,IAIK,IAAI,MAAMG,CAAe;AAEvC;AAEKP,EAAI,UACLS,EAAQ,QAAQ;AAWpB,SAASC,EAAaC,GAA8B;AAChD,QAAMC,IAAaC,EAAMF,CAA2B;AAEpD,SAAO,OAAOC,KAAe,aAAcA,IAA+BC,EAAM;AACpF;AAOO,MAAMC,IAAa;AAAA,EACtB,QAAQL,EAAQ;AAAA,EAChB,OAAOA,EAAQ;AAAA,EACf,OAAOA,EAAQ;AAAA,EACf,OAAOA,EAAQ;AAAA,EACf,MAAMA,EAAQ;AAAA,EACd,KAAKA,EAAQ;AAAA,EACb,MAAMA,EAAQ;AAAA,EACd,SAASA,EAAQ;AAAA,EACjB,OAAOA,EAAQ;AAAA,EACf,OAAOA,EAAQ;AAAA,EACf,KAAKA,EAAQ;AAAA,EACb,OAAOA,EAAQ;AAAA,EACf,OAAOA,EAAQ;AAAA,EACf,SAASA,EAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAajB,cAAcM,GAAeC,GAAwBL,IAAQ,OAAO;AAChE,QAAI,CAACK,GAAQ,QAAQ;AACjB,MAAAP,EAAQ,IAAII,EAAM,MAAME,CAAK,CAAC;AAC9B;AAAA,IACJ;AAEA,IAAAC,EAAO,QAAQ,CAAC,EAAE,MAAAC,GAAM,UAAAC,GAAU,MAAAC,GAAM,SAAAhB,QAAc;AAClD,YAAMiB,IAAiBF,IAAW,IAAIA,CAAQ,KAAK,IAC7CG,IAAW,GAAGJ,CAAI,GAAGG,CAAc;AACzC,MAAAX,EAAQ,IAAI,GAAGI,EAAM,KAAK,OAAO,CAAC,IAAIA,EAAM,KAAKQ,CAAQ,CAAC,EAAE,GAExDF,KACAV,EAAQ,IAAI,MAAMC,EAAaC,CAAK,EAAE,OAAO,CAAC,IAAIQ,CAAI,EAAE,GAG5DV,EAAQ,IAAI,MAAMC,EAAaC,CAAK,EAAE,UAAU,CAAC,IAAIR,CAAO,EAAE;AAAA,IAClE,CAAC,GAEDM,EAAQ,IAAIC,EAAaC,CAAK,EAAE,GAAGI,CAAK,MAAMC,EAAO,MAAM,EAAE,CAAC,GAE9DP,EAAQ,IAAII,EAAM,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC;AAAA,EAC1C;AACJ;AAeO,SAASS,EAAwBC,GAAqBC,GAAgD;AACzG,QAAM,EAAE,WAAAC,IAAY,IAAM,aAAAC,GAAa,UAAAC,EAAA,IAAaH,KAAW,CAAA,GAEzDI,IAAQL,aAAsB,QAC9BA,IACA,IAAI,MAAM,OAAOA,KAAe,WAAWA,IAAa,eAAe;AAU7E,SARIE,KACAX,EAAI,MAAMc,EAAM,OAAO,GAGvBD,KAAY,OAAOA,KAAa,cAChCA,EAASC,CAAK,GAGdF,KAIG;AAAA,IACH,SAAS;AAAA,IACT,SAASE,EAAM;AAAA,IACf,MAAMvB,EAAgB,sBAAsB;AAAA,EAAA;AAEpD;"}

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

@@ -1,4 +1,6 @@
 export * from './mongo.constant.js';
 export * from './mongo.controller.js';
+export * from './mongo.dynamic-populate.js';
+export * from './mongo.populate.js';
 export * from './mongo.type.js';
 export * from './mongo.util.js';

package/dist/node/mongo/index.js

@@ -1,17 +1,26 @@
 import { MONGO_MIGRATE_OPTIONS as r, MONGO_SLUG_MAX_ATTEMPTS as t } from "./mongo.constant.js";
-import { MongoController as n, MongooseController as M } from "./mongo.controller.js";
-import { C_Collection as m, C_Db as p, C_Document as C, C_Model as O } from "./mongo.type.js";
-import { applyNestedPopulate as N, convertEnumToModelName as f, mongo as x } from "./mongo.util.js";
+import { filterDynamicVirtualsFromPopulate as m, isMongooseDoc as p, isObject as n, populateDynamicVirtuals as a, remapDynamicPopulate as M } from "./mongo.dynamic-populate.js";
+import { applyNestedPopulate as _ } from "./mongo.populate.js";
+import { C_Collection as f, C_Db as u, C_Document as s, C_Model as x } from "./mongo.type.js";
+import { convertEnumToModelName as O, mongo as D } from "./mongo.util.js";
+import { MongoController as N } from "./mongo.controller.native.js";
+import { MongooseController as g } from "./mongo.controller.mongoose.js";
 export {
-  m as C_Collection,
-  p as C_Db,
-  C as C_Document,
-  O as C_Model,
+  f as C_Collection,
+  u as C_Db,
+  s as C_Document,
+  x as C_Model,
   r as MONGO_MIGRATE_OPTIONS,
   t as MONGO_SLUG_MAX_ATTEMPTS,
-  n as MongoController,
-  M as MongooseController,
-  N as applyNestedPopulate,
-  f as convertEnumToModelName,
-  x as mongo
+  N as MongoController,
+  g as MongooseController,
+  _ as applyNestedPopulate,
+  O as convertEnumToModelName,
+  m as filterDynamicVirtualsFromPopulate,
+  p as isMongooseDoc,
+  n as isObject,
+  D as mongo,
+  a as populateDynamicVirtuals,
+  M as remapDynamicPopulate
 };
+//# sourceMappingURL=index.js.map

package/dist/node/mongo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}

package/dist/node/mongo/mongo.constant.js

@@ -3,3 +3,4 @@ export {
   O as MONGO_MIGRATE_OPTIONS,
   M as MONGO_SLUG_MAX_ATTEMPTS
 };
+//# sourceMappingURL=mongo.constant.js.map

package/dist/node/mongo/mongo.constant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo.constant.js","sources":["../../../src/node/mongo/mongo.constant.ts"],"sourcesContent":["/**\n * Environment variable key for MongoDB migration options.\n * This constant defines the environment variable name that can be used to configure\n * MongoDB migration settings and options for database schema management.\n */\nexport const MONGO_MIGRATE_OPTIONS = 'MONGO_MIGRATE_OPTIONS';\n\n/**\n * Maximum number of attempts to generate a unique slug.\n * This constant defines the maximum number of attempts to generate a unique slug\n * before giving up and returning a fallback slug.\n */\nexport const MONGO_SLUG_MAX_ATTEMPTS = 100;\n"],"names":["MONGO_MIGRATE_OPTIONS","MONGO_SLUG_MAX_ATTEMPTS"],"mappings":"AAKO,MAAMA,IAAwB,yBAOxBC,IAA0B;"}

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

@@ -1,317 +1,7 @@
-import { default as mongooseRaw } from 'mongoose';
-import { I_Return } from '../../typescript/index.js';
-import { C_Db, C_Document, I_DeleteOptionsExtended, I_ExtendedModel, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Filter, T_Input_Populate, T_InsertManyOptions, T_PaginateResult, T_PipelineStage, T_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult, T_WithId } from './mongo.type.js';
+export * from './mongo.controller.mongoose.js';
 /**
- * MongoDB native driver controller for direct database operations.
- * This class provides a simplified interface for MongoDB operations using the native driver,
- * with automatic generic field generation and standardized response formatting.
+ * Re-exports both MongoDB controller implementations.
+ * - MongoController: Native MongoDB driver operations
+ * - MongooseController: Mongoose ORM with pagination, aggregation, and slug generation
  */
-export declare class MongoController<D extends Partial<C_Document>> {
-    private collection;
-    /**
-     * Creates a new MongoDB controller instance.
-     *
-     * @param db - The MongoDB database instance.
-     * @param collectionName - The name of the collection to operate on.
-     */
-    constructor(db: C_Db, collectionName: string);
-    /**
-     * Creates a single document in the collection.
-     * This method adds generic fields (id, isDel, timestamps) to the document before insertion.
-     *
-     * @param document - The document to create, with or without generic fields.
-     * @returns A promise that resolves to a standardized response with the created document.
-     */
-    createOne(document: D | Partial<D>): Promise<I_Return<D | Partial<D>>>;
-    /**
-     * Creates multiple documents in the collection.
-     * This method adds generic fields to each document before bulk insertion.
-     *
-     * @param documents - An array of documents to create.
-     * @returns A promise that resolves to a standardized response with the created documents.
-     */
-    createMany(documents: (D | Partial<D>)[]): Promise<I_Return<(D | Partial<D>)[]>>;
-    /**
-     * Finds a single document by filter criteria.
-     *
-     * @param filter - The filter criteria to find the document.
-     * @returns A promise that resolves to a standardized response with the found document.
-     */
-    findOne(filter: T_Filter<D>): Promise<I_Return<T_WithId<D>>>;
-    /**
-     * Finds all documents matching the filter criteria.
-     *
-     * @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>[]>>;
-    /**
-     * Counts documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to count documents (defaults to empty object for all documents).
-     * @returns A promise that resolves to a standardized response with the document count.
-     */
-    count(filter?: T_Filter<D>): Promise<I_Return<number>>;
-    /**
-     * Updates a single document matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find the document to update.
-     * @param update - The update data to apply to the document.
-     * @returns A promise that resolves to a standardized response with the update result.
-     */
-    updateOne(filter: T_Filter<D>, update: Partial<D>): Promise<I_Return<T_UpdateResult>>;
-    /**
-     * Updates multiple documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find documents to update.
-     * @param update - The update data to apply to the documents.
-     * @returns A promise that resolves to a standardized response with the update result.
-     */
-    updateMany(filter: T_Filter<D>, update: Partial<D>): Promise<I_Return<T_UpdateResult>>;
-    /**
-     * Deletes a single document matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find the document to delete.
-     * @returns A promise that resolves to a standardized response with the delete result.
-     */
-    deleteOne(filter: T_Filter<D>): Promise<I_Return<T_DeleteResult>>;
-    /**
-     * Deletes multiple documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find documents to delete.
-     * @returns A promise that resolves to a standardized response with the delete result.
-     */
-    deleteMany(filter: T_Filter<D>): Promise<I_Return<T_DeleteResult>>;
-}
-/**
- * Mongoose controller for database operations with advanced features.
- * This class provides a comprehensive interface for Mongoose operations including
- * pagination, aggregation, slug generation, and short ID creation.
- */
-export declare class MongooseController<T extends Partial<C_Document>> {
-    private model;
-    /**
-     * Creates a new Mongoose controller instance.
-     *
-     * @param model - The Mongoose model to operate on.
-     */
-    constructor(model: I_ExtendedModel<T>);
-    /**
-     * Gets the model name for logging and error messages.
-     *
-     * @returns The name of the model.
-     */
-    private getModelName;
-    /**
-     * Gets the dynamic virtuals configuration from the model instance.
-     *
-     * @returns Array of dynamic virtual configurations or undefined if none exist.
-     */
-    private getDynamicVirtuals;
-    /**
-     * Populates dynamic virtuals for a single document.
-     *
-     * @param result - The document to populate dynamic virtuals for.
-     * @param populate - The populate options to determine which virtuals to populate.
-     * @returns The document with dynamic virtuals populated.
-     */
-    private populateDynamicVirtualsForDocument;
-    /**
-     * Populates dynamic virtuals for an array of documents.
-     *
-     * @param results - The documents to populate dynamic virtuals for.
-     * @param populate - The populate options to determine which virtuals to populate.
-     * @returns The documents with dynamic virtuals populated.
-     */
-    private populateDynamicVirtualsForDocuments;
-    /**
-     * Finds a single document with optional population and projection.
-     * Automatically handles dynamic virtual population if configured.
-     *
-     * @param filter - The filter criteria to find the document.
-     * @param projection - The fields to include/exclude in the result.
-     * @param options - Query options for the operation.
-     * @param populate - Population configuration for related documents.
-     * @returns A promise that resolves to a standardized response with the found document.
-     */
-    findOne(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T>>;
-    /**
-     * Finds all documents with optional population and projection.
-     * Automatically handles dynamic virtual population if configured.
-     *
-     * @param filter - The filter criteria to find documents.
-     * @param projection - The fields to include/exclude in the result.
-     * @param options - Query options for the operation.
-     * @param populate - Population configuration for related documents.
-     * @returns A promise that resolves to a standardized response with the found documents.
-     */
-    findAll(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T[]>>;
-    /**
-     * Finds documents with pagination support.
-     * Automatically handles dynamic virtual population if configured.
-     *
-     * @param filter - The filter criteria to find documents.
-     * @param options - Pagination options including page, limit, and population.
-     * @returns A promise that resolves to a standardized response with paginated results.
-     */
-    findPaging(filter?: T_QueryFilter<T>, options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_PaginateResult<T>>>;
-    /**
-     * Performs aggregation with pagination support.
-     *
-     * @param pipeline - The aggregation pipeline stages.
-     * @param options - Pagination options for the aggregation result.
-     * @returns A promise that resolves to a standardized response with paginated aggregation results.
-     */
-    findPagingAggregate(pipeline: T_PipelineStage[], options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_AggregatePaginateResult<T>>>;
-    /**
-     * Counts documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to count documents.
-     * @returns A promise that resolves to a standardized response with the document count.
-     */
-    count(filter?: T_QueryFilter<T>): Promise<I_Return<number>>;
-    /**
-     * Creates a single document.
-     *
-     * @param doc - The document to create.
-     * @returns A promise that resolves to a standardized response with the created document.
-     */
-    createOne(doc: T | Partial<T>): Promise<I_Return<T>>;
-    /**
-     * Creates multiple documents with bulk insertion.
-     *
-     * @param docs - An array of documents to create.
-     * @param options - Options for the bulk insertion operation.
-     * @returns A promise that resolves to a standardized response with the created documents.
-     */
-    createMany(docs: (T | Partial<T>)[], options?: T_InsertManyOptions): Promise<I_Return<T[]>>;
-    /**
-     * Updates a single document and returns the updated version.
-     *
-     * @param filter - The filter criteria to find the document to update.
-     * @param update - The update data to apply.
-     * @param options - Options for the update operation.
-     * @returns A promise that resolves to a standardized response with the updated document.
-     */
-    updateOne(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T>>;
-    /**
-     * Updates multiple documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find documents to update.
-     * @param update - The update data to apply.
-     * @param options - Options for the update operation.
-     * @returns A promise that resolves to a standardized response with the update result.
-     */
-    updateMany(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T_UpdateResult>>;
-    /**
-     * Deletes a single document and returns the deleted version.
-     *
-     * @param filter - The filter criteria to find the document to delete.
-     * @param options - Options for the delete operation.
-     * @returns A promise that resolves to a standardized response with the deleted document.
-     */
-    deleteOne(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T>>;
-    /**
-     * Deletes multiple documents matching the filter criteria.
-     *
-     * @param filter - The filter criteria to find documents to delete.
-     * @param options - Options for the delete operation.
-     * @returns A promise that resolves to a standardized response with the delete result.
-     */
-    deleteMany(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T_DeleteResult>>;
-    /**
-     * Creates a unique short ID based on a given ID.
-     * This method generates multiple short IDs with increasing lengths and finds the first available one.
-     *
-     * @param id - The base ID to generate short IDs from.
-     * @param length - The initial length for short ID generation (default: 4).
-     * @returns A promise that resolves to a standardized response with the unique short ID.
-     */
-    createShortId(id: string, length?: number): Promise<I_Return<string>>;
-    /**
-     * Creates a query for slug existence checking.
-     * This method generates a query that checks for slug existence in both current and historical slug fields.
-     *
-     * @param options - Configuration for slug query generation including slug, field, and filter.
-     * @param options.slug - The slug string to check for existence.
-     * @param options.field - The field name for object-based slug checking.
-     * @param options.isObject - Whether the slug is stored as an object with nested fields.
-     * @param options.haveHistory - Whether to check historical slug fields for existence.
-     * @param options.filter - Additional filter conditions to apply to the query.
-     * @returns A MongoDB query object for checking slug existence.
-     */
-    createSlugQuery({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): (mongooseRaw.QueryFilter<T> & {
-        $or: ({
-            [x: string]: string;
-            slugHistory?: undefined;
-        } | {
-            slugHistory: {
-                $elemMatch: {
-                    [x: string]: string;
-                };
-            };
-        })[];
-    }) | (mongooseRaw.QueryFilter<T> & {
-        $or: ({
-            slug: string;
-            slugHistory?: undefined;
-        } | {
-            slugHistory: string;
-            slug?: undefined;
-        })[];
-    });
-    /**
-     * Creates a unique slug based on a given string.
-     * This method generates multiple slug variations and finds the first available one.
-     *
-     * @param options - Configuration for slug generation including slug, field, and filter.
-     * @param options.slug - The base slug string to make unique.
-     * @param options.field - The field name for object-based slug checking.
-     * @param options.isObject - Whether the slug is stored as an object with nested fields.
-     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
-     * @param options.filter - Additional filter conditions to apply when checking slug existence.
-     * @returns A promise that resolves to a unique slug string.
-     */
-    createUniqueSlug({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): Promise<string>;
-    /**
-     * Creates a slug for a document field.
-     * This method handles both simple string fields and object fields with nested slug generation.
-     *
-     * @param options - Configuration for slug creation including field, source document, and filter.
-     * @param options.field - The field name to create a slug for.
-     * @param options.from - The source document containing the field value.
-     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
-     * @param options.filter - Additional filter conditions to apply when checking slug existence.
-     * @returns A promise that resolves to a standardized response with the created slug(s).
-     */
-    createSlug<R = string>({ field, from, filter, haveHistory }: I_Input_CreateSlug<T>): Promise<I_Return<R>>;
-    /**
-     * Checks if a slug already exists in the collection.
-     * This method verifies slug existence in both current and historical slug fields.
-     *
-     * @param options - Configuration for slug checking including slug, field, source document, and filter.
-     * @param options.slug - The slug string to check for existence.
-     * @param options.field - The field name for object-based slug checking.
-     * @param options.from - The source document containing the field value.
-     * @param options.haveHistory - Whether to check historical slug fields for existence.
-     * @param options.filter - Additional filter conditions to apply to the query.
-     * @returns A promise that resolves to a standardized response indicating whether the slug exists.
-     */
-    checkSlug({ slug, field, from, filter, haveHistory }: I_Input_CheckSlug<T>): Promise<I_Return<boolean>>;
-    /**
-     * Performs aggregation operations on the collection.
-     *
-     * @param pipeline - The aggregation pipeline stages to execute.
-     * @returns A promise that resolves to a standardized response with the aggregation results.
-     */
-    aggregate(pipeline: T_PipelineStage[]): Promise<I_Return<T[]>>;
-    /**
-     * Retrieves distinct values for the specified key from the collection.
-     *
-     * @param key - The field for which to return distinct values.
-     * @param filter - The filter query to apply (optional).
-     * @param options - Additional options for the distinct operation (optional).
-     * @returns A promise that resolves to a standardized response with the array of distinct values.
-     */
-    distinct(key: string, filter?: T_QueryFilter<T>, options?: T_QueryOptions<T>): Promise<I_Return<unknown[]>>;
-}
+export * from './mongo.controller.native.js';

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

@@ -0,0 +1,234 @@
+import { I_Return } from '../../typescript/index.js';
+import { C_Document, I_DeleteOptionsExtended, 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_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult } from './mongo.type.js';
+/**
+ * Mongoose controller for database operations with advanced features.
+ * This class provides a comprehensive interface for Mongoose operations including
+ * pagination, aggregation, slug generation, and short ID creation.
+ */
+export declare class MongooseController<T extends Partial<C_Document>> {
+    private model;
+    /**
+     * Creates a new Mongoose controller instance.
+     *
+     * @param model - The Mongoose model to operate on.
+     */
+    constructor(model: I_ExtendedModel<T>);
+    /**
+     * Gets the model name for logging and error messages.
+     *
+     * @returns The name of the model.
+     */
+    private getModelName;
+    /**
+     * Gets the dynamic virtuals configuration from the model instance.
+     *
+     * @returns Array of dynamic virtual configurations or undefined if none exist.
+     */
+    private getDynamicVirtuals;
+    /**
+     * Populates dynamic virtuals for a single document.
+     *
+     * @param result - The document to populate dynamic virtuals for.
+     * @param populate - The populate options to determine which virtuals to populate.
+     * @returns The document with dynamic virtuals populated.
+     */
+    private populateDynamicVirtualsForDocument;
+    /**
+     * Populates dynamic virtuals for an array of documents.
+     *
+     * @param results - The documents to populate dynamic virtuals for.
+     * @param populate - The populate options to determine which virtuals to populate.
+     * @returns The documents with dynamic virtuals populated.
+     */
+    private populateDynamicVirtualsForDocuments;
+    /**
+     * Finds a single document with optional population and projection.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find the document.
+     * @param projection - The fields to include/exclude in the result.
+     * @param options - Query options for the operation.
+     * @param populate - Population configuration for related documents.
+     * @returns A promise that resolves to a standardized response with the found document.
+     */
+    findOne(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T>>;
+    /**
+     * Finds all documents with optional population and projection.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find documents.
+     * @param projection - The fields to include/exclude in the result.
+     * @param options - Query options for the operation.
+     * @param populate - Population configuration for related documents.
+     * @returns A promise that resolves to a standardized response with the found documents.
+     */
+    findAll(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T[]>>;
+    /**
+     * Finds documents with pagination support.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find documents.
+     * @param options - Pagination options including page, limit, and population.
+     * @returns A promise that resolves to a standardized response with paginated results.
+     */
+    findPaging(filter?: T_QueryFilter<T>, options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_PaginateResult<T>>>;
+    /**
+     * Performs aggregation with pagination support.
+     *
+     * @param pipeline - The aggregation pipeline stages.
+     * @param options - Pagination options for the aggregation result.
+     * @returns A promise that resolves to a standardized response with paginated aggregation results.
+     */
+    findPagingAggregate(pipeline: T_PipelineStage[], options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_AggregatePaginateResult<T>>>;
+    /**
+     * Counts documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to count documents.
+     * @returns A promise that resolves to a standardized response with the document count.
+     */
+    count(filter?: T_QueryFilter<T>): Promise<I_Return<number>>;
+    /**
+     * Creates a single document.
+     *
+     * @param doc - The document to create.
+     * @returns A promise that resolves to a standardized response with the created document.
+     */
+    createOne(doc: T | Partial<T>): Promise<I_Return<T>>;
+    /**
+     * Creates multiple documents with bulk insertion.
+     *
+     * @param docs - An array of documents to create.
+     * @param options - Options for the bulk insertion operation.
+     * @returns A promise that resolves to a standardized response with the created documents.
+     */
+    createMany(docs: (T | Partial<T>)[], options?: T_InsertManyOptions): Promise<I_Return<T[]>>;
+    /**
+     * Updates a single document and returns the updated version.
+     *
+     * @param filter - The filter criteria to find the document to update.
+     * @param update - The update data to apply.
+     * @param options - Options for the update operation.
+     * @returns A promise that resolves to a standardized response with the updated document.
+     */
+    updateOne(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T>>;
+    /**
+     * Updates multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to update.
+     * @param update - The update data to apply.
+     * @param options - Options for the update operation.
+     * @returns A promise that resolves to a standardized response with the update result.
+     */
+    updateMany(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Deletes a single document and returns the deleted version.
+     *
+     * @param filter - The filter criteria to find the document to delete.
+     * @param options - Options for the delete operation.
+     * @returns A promise that resolves to a standardized response with the deleted document.
+     */
+    deleteOne(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T>>;
+    /**
+     * Deletes multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to delete.
+     * @param options - Options for the delete operation.
+     * @returns A promise that resolves to a standardized response with the delete result.
+     */
+    deleteMany(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T_DeleteResult>>;
+    /**
+     * Creates a unique short ID based on a given ID.
+     * This method generates multiple short IDs with increasing lengths and finds the first available one.
+     *
+     * @param id - The base ID to generate short IDs from.
+     * @param length - The initial length for short ID generation (default: 4).
+     * @returns A promise that resolves to a standardized response with the unique short ID.
+     */
+    createShortId(id: string, length?: number): Promise<I_Return<string>>;
+    /**
+     * Creates a query for slug existence checking.
+     * This method generates a query that checks for slug existence in both current and historical slug fields.
+     *
+     * @param options - Configuration for slug query generation including slug, field, and filter.
+     * @param options.slug - The slug string to check for existence.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.isObject - Whether the slug is stored as an object with nested fields.
+     * @param options.haveHistory - Whether to check historical slug fields for existence.
+     * @param options.filter - Additional filter conditions to apply to the query.
+     * @returns A MongoDB query object for checking slug existence.
+     */
+    createSlugQuery({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): (import('mongoose').QueryFilter<T> & {
+        $or: ({
+            [x: string]: string;
+            slugHistory?: undefined;
+        } | {
+            slugHistory: {
+                $elemMatch: {
+                    [x: string]: string;
+                };
+            };
+        })[];
+    }) | (import('mongoose').QueryFilter<T> & {
+        $or: ({
+            slug: string;
+            slugHistory?: undefined;
+        } | {
+            slugHistory: string;
+            slug?: undefined;
+        })[];
+    });
+    /**
+     * Creates a unique slug based on a given string.
+     * This method generates multiple slug variations and finds the first available one.
+     *
+     * @param options - Configuration for slug generation including slug, field, and filter.
+     * @param options.slug - The base slug string to make unique.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.isObject - Whether the slug is stored as an object with nested fields.
+     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
+     * @param options.filter - Additional filter conditions to apply when checking slug existence.
+     * @returns A promise that resolves to a unique slug string.
+     */
+    createUniqueSlug({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): Promise<string>;
+    /**
+     * Creates a slug for a document field.
+     * This method handles both simple string fields and object fields with nested slug generation.
+     *
+     * @param options - Configuration for slug creation including field, source document, and filter.
+     * @param options.field - The field name to create a slug for.
+     * @param options.from - The source document containing the field value.
+     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
+     * @param options.filter - Additional filter conditions to apply when checking slug existence.
+     * @returns A promise that resolves to a standardized response with the created slug(s).
+     */
+    createSlug<R = string>({ field, from, filter, haveHistory }: I_Input_CreateSlug<T>): Promise<I_Return<R>>;
+    /**
+     * Checks if a slug already exists in the collection.
+     * This method verifies slug existence in both current and historical slug fields.
+     *
+     * @param options - Configuration for slug checking including slug, field, source document, and filter.
+     * @param options.slug - The slug string to check for existence.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.from - The source document containing the field value.
+     * @param options.haveHistory - Whether to check historical slug fields for existence.
+     * @param options.filter - Additional filter conditions to apply to the query.
+     * @returns A promise that resolves to a standardized response indicating whether the slug exists.
+     */
+    checkSlug({ slug, field, from, filter, haveHistory }: I_Input_CheckSlug<T>): Promise<I_Return<boolean>>;
+    /**
+     * Performs aggregation operations on the collection.
+     *
+     * @param pipeline - The aggregation pipeline stages to execute.
+     * @returns A promise that resolves to a standardized response with the aggregation results.
+     */
+    aggregate(pipeline: T_PipelineStage[]): Promise<I_Return<T[]>>;
+    /**
+     * Retrieves distinct values for the specified key from the collection.
+     *
+     * @param key - The field for which to return distinct values.
+     * @param filter - The filter query to apply (optional).
+     * @param options - Additional options for the distinct operation (optional).
+     * @returns A promise that resolves to a standardized response with the array of distinct values.
+     */
+    distinct(key: string, filter?: T_QueryFilter<T>, options?: T_QueryOptions<T>): Promise<I_Return<unknown[]>>;
+}