@cyberskill/shared 1.217.0 → 2.1.0

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

@@ -1 +1,6 @@
+/**
+ * Environment variable key for MongoDB migration options.
+ * This constant defines the environment variable name that can be used to configure
+ * MongoDB migration settings and options for database schema management.
+ */
 export declare const MONGO_MIGRATE_OPTIONS = "MONGO_MIGRATE_OPTIONS";

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

@@ -48,23 +48,43 @@ export type T_Omit_Update = 'id' | 'createdAt' | 'updatedAt';
 interface I_VirtualNestedOptions {
     [key: string]: I_VirtualNestedOptions | number | string | boolean;
 }
-interface I_VirtualOptions {
-    ref: string;
+/**
+ * Function type for dynamically determining the reference model name.
+ * Can return either a string (model name) or an enum value that represents the model.
+ * The function can also return undefined, which will be handled gracefully.
+ * This allows for optional properties in documents without requiring non-null assertions.
+ *
+ * @template T - The document type
+ * @template R - The return type (string or enum)
+ */
+type T_DynamicRefFunction<T = unknown, R extends string = string> = (doc: T) => R | undefined;
+interface I_VirtualBaseOptions {
     localField: string;
     foreignField: string;
     count?: boolean;
     justOne?: boolean;
     options?: I_VirtualNestedOptions;
 }
-interface I_MongooseOptions<T> {
+interface I_VirtualOptions extends I_VirtualBaseOptions {
+    ref: string;
+}
+export interface I_DynamicVirtualOptions<T, R extends string = string> extends I_VirtualBaseOptions {
+    ref: T_DynamicRefFunction<T, R>;
+}
+export type T_VirtualOptions<T, R extends string = string> = I_VirtualOptions | I_DynamicVirtualOptions<T, R>;
+export interface I_DynamicVirtualConfig<T, R extends string = string> {
+    name: string;
+    options: I_DynamicVirtualOptions<T, R>;
+}
+interface I_MongooseOptions<T, R extends string = string> {
     mongoose: typeof mongoose;
     virtuals?: {
         name: keyof T | string;
-        options?: I_VirtualOptions;
+        options?: T_VirtualOptions<T, R>;
         get?: (this: T) => void;
     }[];
 }
-export interface I_CreateSchemaOptions<T> extends I_MongooseOptions<T> {
+export interface I_CreateSchemaOptions<T, R extends string = string> extends I_MongooseOptions<T, R> {
     schema: T_Input_MongooseSchema<T>;
     standalone?: boolean;
 }
@@ -77,7 +97,7 @@ export interface I_MongooseModelMiddleware<T extends Partial<C_Document>> {
     pre?: T_MongooseMiddlewarePreFunction<T & T_QueryWithHelpers<T>>;
     post?: T_MongooseMiddlewarePostFunction<T>;
 }
-export interface I_CreateModelOptions<T extends Partial<C_Document>> extends I_MongooseOptions<T> {
+export interface I_CreateModelOptions<T extends Partial<C_Document>, R extends string = string> extends I_MongooseOptions<T, R> {
     schema: T_Input_MongooseSchema<T>;
     name: string;
     aggregate?: boolean;
@@ -85,7 +105,7 @@ export interface I_CreateModelOptions<T extends Partial<C_Document>> extends I_M
     pagination?: boolean;
 }
 export type T_Input_Populate = string | string[] | T_PopulateOptions | T_PopulateOptions[];
-export interface T_PaginateOptionsWithPopulate extends T_PaginateOptions, Omit<T_PopulateOption, 'populate'> {
+export interface I_PaginateOptionsWithPopulate extends T_PaginateOptions, Omit<T_PopulateOption, 'populate'> {
     populate?: T_Input_Populate;
 }
 export interface I_Input_FindOne<T> extends T_PopulateOption {
@@ -99,14 +119,14 @@ export interface I_Input_FindAll<T> extends T_PopulateOption {
     options?: T_QueryOptions<T>;
 }
 export type I_Input_FindPaging<T = undefined> = T extends undefined ? {
-    options?: T_PaginateOptionsWithPopulate;
+    options?: I_PaginateOptionsWithPopulate;
 } : {
     filter?: T_FilterQuery<T>;
-    options?: T_PaginateOptionsWithPopulate;
+    options?: I_PaginateOptionsWithPopulate;
 };
 export interface I_Input_FindPagingAggregate {
     pipeline: T_PipelineStage[];
-    options?: T_PaginateOptionsWithPopulate;
+    options?: I_PaginateOptionsWithPopulate;
 }
 export interface I_Input_CreateOne<T> {
     doc: T;

package/dist/node/mongo/mongo.util.cjs

@@ -1,5 +1,5 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("lodash-es"),v=require("migrate-mongo"),q=require("mongoose"),A=require("mongoose-aggregate-paginate-v2"),b=require("mongoose-paginate-v2"),T=require("uuid"),D=require("../../util/object/object.util.cjs"),x=require("../../util/common/common.util.cjs"),y=require("../fs/fs.util.cjs"),f=require("../path/path.constant.cjs"),C=require("../../util/validate/validate.util.cjs"),S=require("../../util/string/string.util.cjs"),d=require("../../constant/response-status.cjs"),i=require("../log/log.util.cjs");var I=Object.defineProperty,M=Object.defineProperties,w=Object.getOwnPropertyDescriptors,P=Object.getOwnPropertySymbols,j=Object.prototype.hasOwnProperty,F=Object.prototype.propertyIsEnumerable,_=(n,t,e)=>t in n?I(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e,h=(n,t)=>{for(var e in t||(t={}))j.call(t,e)&&_(n,e,t[e]);if(P)for(var e of P(t))F.call(t,e)&&_(n,e,t[e]);return n},R=(n,t)=>M(n,w(t)),G=(n,t,e)=>_(n,typeof t!="symbol"?t+"":t,e),o=(n,t,e)=>new Promise((r,s)=>{var u=a=>{try{l(e.next(a))}catch(m){s(m)}},c=a=>{try{l(e.throw(a))}catch(m){s(m)}},l=a=>a.done?r(a.value):Promise.resolve(a.value).then(u,c);l((e=e.apply(n,t)).next())});const g={createGenericFields(){return{id:T.v4(),isDel:!1,createdAt:new Date,updatedAt:new Date}},applyPlugins(n,t){t.filter(e=>typeof e=="function").forEach(e=>n.plugin(e))},applyMiddlewares(n,t){t.forEach(({method:e,pre:r,post:s})=>{e&&r&&n.pre(e,r),e&&s&&n.post(e,s)})},createGenericSchema(n){return new n.Schema({id:{type:String,default:T.v4,unique:!0},isDel:{type:Boolean,default:!1}},{timestamps:!0})},createSchema({mongoose:n,schema:t,virtuals:e=[],standalone:r=!1}){const s=new n.Schema(t);return e.forEach(({name:u,options:c,get:l})=>{const a=s.virtual(u,c);l&&a.get(l)}),r||s.add(g.createGenericSchema(n)),s},createModel({mongoose:n,name:t,schema:e,pagination:r=!1,aggregate:s=!1,virtuals:u=[],middlewares:c=[]}){if(!t)throw new Error("Model name is required.");if(n.models[t])return n.models[t];const l=g.createSchema({mongoose:n,schema:e,virtuals:u});return g.applyPlugins(l,[r&&b,s&&A]),g.applyMiddlewares(l,c),n.model(t,l)},validator:{isRequired(){return function(n){return o(this,null,function*(){return!C.validate.isEmpty(n)})}},isUnique(n){return function(t){return o(this,null,function*(){if(!Array.isArray(n)||n.length===0)throw new Error("Fields must be a non-empty array of strings.");const e={$or:n.map(s=>({[s]:t}))};return!(yield this.constructor.exists(e))})}},matchesRegex(n){return function(t){return o(this,null,function*(){if(!Array.isArray(n)||n.some(e=>!(e instanceof RegExp)))throw new Error("regexArray must be an array of valid RegExp objects.");return n.every(e=>e.test(t))})}}},migrate:R(h({},v),{setConfig:n=>{const t=`// This file is automatically generated by the Cyberskill CLI.
-module.exports = ${JSON.stringify(n,null,4)}`;y.writeFileSync(f.PATH.MIGRATE_MONGO_CONFIG,t);const e=`
-${f.MIGRATE_MONGO_CONFIG}
-`;y.pathExistsSync(f.PATH.GIT_IGNORE)?y.readFileSync(f.PATH.GIT_IGNORE,"utf-8").split(`
-`).includes(f.MIGRATE_MONGO_CONFIG)||y.appendFileSync(f.PATH.GIT_IGNORE,e):y.writeFileSync(f.PATH.GIT_IGNORE,e)}}),regexify(n,t){if(!n)return{};let e=p.cloneDeep(n);if(!t||t.length===0)return e;for(const r of t){const s=r.toString().split("."),u=D.getNestedValue(e,s);if(typeof u=="string"&&u.length>0){const c={$regex:`.*${x.regexSearchMapper(u)}.*`,$options:"i"};e=D.setNestedValue(e,s,c)}}return e}};class U{constructor(t,e){G(this,"collection"),this.collection=t.collection(e)}createOne(t){return o(this,null,function*(){try{const e=h(h({},g.createGenericFields()),t);return(yield this.collection.insertOne(e)).acknowledged?{success:!0,message:"Document created successfully",result:e}:{success:!1,message:"Document creation failed",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}}catch(e){return i.catchError(e)}})}createMany(t){return o(this,null,function*(){try{const e=t.map(s=>h(h({},g.createGenericFields()),s)),r=yield this.collection.insertMany(e);return r.insertedCount===0?{success:!1,message:"No documents were inserted",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:`${r.insertedCount} documents created successfully`,result:e}}catch(e){return i.catchError(e)}})}findOne(t){return o(this,null,function*(){try{const e=yield this.collection.findOne(t);return e?{success:!0,message:"Document found",result:e}:{success:!1,message:"Document not found",code:d.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(e){return i.catchError(e)}})}findAll(){return o(this,arguments,function*(t={}){try{return{success:!0,message:"Documents retrieved successfully",result:yield this.collection.find(t).toArray()}}catch(e){return i.catchError(e)}})}count(){return o(this,arguments,function*(t={}){try{return{success:!0,message:"Count retrieved successfully",result:yield this.collection.countDocuments(t)}}catch(e){return i.catchError(e)}})}updateOne(t,e){return o(this,null,function*(){try{const r=yield this.collection.updateOne(t,{$set:e});return r.matchedCount===0?{success:!1,message:"No documents matched the filter",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Document updated successfully",result:r}}catch(r){return i.catchError(r)}})}updateMany(t,e){return o(this,null,function*(){try{const r=yield this.collection.updateMany(t,{$set:e});return r.matchedCount===0?{success:!1,message:"No documents matched the filter",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Documents updated successfully",result:r}}catch(r){return i.catchError(r)}})}deleteOne(t){return o(this,null,function*(){try{const e=yield this.collection.deleteOne(t);return e.deletedCount===0?{success:!1,message:"No documents matched the filter",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Document deleted successfully",result:e}}catch(e){return i.catchError(e)}})}deleteMany(t){return o(this,null,function*(){try{const e=yield this.collection.deleteMany(t);return e.deletedCount===0?{success:!1,message:"No documents matched the filter",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Documents deleted successfully",result:e}}catch(e){return i.catchError(e)}})}}class ${constructor(t){this.model=t}getModelName(){return this.model.modelName}findOne(){return o(this,arguments,function*(t={},e={},r={},s){try{const u=this.model.findOne(t,e,r);s&&u.populate(s);const c=yield u.exec();return c?{success:!0,result:c}:{success:!1,message:`No ${this.getModelName()} found.`,code:d.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(u){return i.catchError(u)}})}findAll(){return o(this,arguments,function*(t={},e={},r={},s){try{const u=this.model.find(t,e,r);return s&&u.populate(s),{success:!0,result:yield u.exec()}}catch(u){return i.catchError(u)}})}findPaging(){return o(this,arguments,function*(t={},e={}){try{return{success:!0,result:yield this.model.paginate(t,e)}}catch(r){return i.catchError(r)}})}findPagingAggregate(t){return o(this,arguments,function*(e,r={}){try{return{success:!0,result:yield this.model.aggregatePaginate(this.model.aggregate(e),r)}}catch(s){return i.catchError(s)}})}count(){return o(this,arguments,function*(t={}){try{return{success:!0,result:yield this.model.countDocuments(t)}}catch(e){return i.catchError(e)}})}createOne(t){return o(this,null,function*(){try{return{success:!0,result:yield this.model.create(t)}}catch(e){return i.catchError(e)}})}createMany(t){return o(this,arguments,function*(e,r={}){try{return{success:!0,result:(yield this.model.insertMany(e,r)).map(c=>c instanceof q.Document?c.toObject():null).filter(c=>c!==null)}}catch(s){return i.catchError(s)}})}updateOne(){return o(this,arguments,function*(t={},e={},r={}){try{const s=yield this.model.findOneAndUpdate(t,e,h({new:!0},r)).exec();return s?{success:!0,result:s}:{success:!1,message:`Failed to update ${this.getModelName()}.`,code:d.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(s){return i.catchError(s)}})}updateMany(){return o(this,arguments,function*(t={},e={},r={}){try{return{success:!0,result:yield this.model.updateMany(t,e,r).exec()}}catch(s){return i.catchError(s)}})}deleteOne(){return o(this,arguments,function*(t={},e={}){try{const r=yield this.model.findOneAndDelete(t,e).exec();return r?{success:!0,result:r}:{success:!1,message:`No ${this.getModelName()} found to delete.`,code:d.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(r){return i.catchError(r)}})}deleteMany(){return o(this,arguments,function*(t={},e={}){try{const r=yield this.model.deleteMany(t,e).exec();return r.deletedCount===0?{success:!1,message:"No documents found to delete.",code:d.RESPONSE_STATUS.NOT_FOUND.CODE}:{success:!0,result:r}}catch(r){return i.catchError(r)}})}createShortId(t,e=4){return o(this,null,function*(){try{const s=new Set;for(let u=0;u<10;u++){const c=S.generateShortId(t,u+e);if(!s.has(c)&&(s.add(c),!(yield this.model.exists({shortId:c}))))return{success:!0,result:c}}return{success:!1,message:"Failed to create a unique shortId",code:d.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}}catch(r){return i.catchError(r)}})}createSlugQuery({slug:t,field:e,isObject:r,filter:s}){const u=h({},s!=null?s:{});return r?R(h({},u),{$or:[{[`slug.${e}`]:t},{slugHistory:{$elemMatch:{[`slug.${e}`]:t}}}]}):R(h({},u),{$or:[{slug:t},{slugHistory:t}]})}createUniqueSlug(t){return o(this,arguments,function*({slug:e,field:r,isObject:s,filter:u}){const c=S.generateSlug(e);let l=c,a=1;for(;yield this.model.exists(this.createSlugQuery({slug:l,field:r,isObject:s,filter:u}));)l=`${c}-${a++}`;return l})}createSlug(t){return o(this,arguments,function*({field:e,from:r,filter:s}){try{const u=r[e];return p.isObject(u)?{success:!0,result:Object.fromEntries(yield Promise.all(Object.entries(u).map(m=>o(this,[m],function*([E,O]){const N=yield this.createUniqueSlug({slug:O,field:E,isObject:!0,filter:s});return[E,N]}))))}:{success:!0,result:yield this.createUniqueSlug({slug:u,field:e,isObject:!1,filter:s})}}catch(u){return i.catchError(u)}})}checkSlug(t){return o(this,arguments,function*({slug:e,field:r,from:s,filter:u}){try{const c=s[r];if(p.isObject(c)){for(const E of Object.values(c)){const O=S.generateSlug(E);if(yield this.model.exists(this.createSlugQuery({slug:O,field:r,isObject:!0,filter:u})))return{success:!0,result:!0}}return{success:!0,result:!1}}const a=S.generateSlug(e);return{success:!0,result:(yield this.model.exists(this.createSlugQuery({slug:a,field:r,isObject:!1,filter:u})))!==null}}catch(c){return i.catchError(c)}})}aggregate(t){return o(this,null,function*(){try{return{success:!0,result:yield this.model.aggregate(t)}}catch(e){return i.catchError(e)}})}}exports.aggregatePaginate=A;exports.mongoosePaginate=b;exports.MongoController=U;exports.MongooseController=$;exports.mongo=g;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const j=require("lodash-es"),B=require("migrate-mongo"),k=require("mongoose"),H=require("mongoose-aggregate-paginate-v2"),K=require("mongoose-paginate-v2"),U=require("uuid"),$=require("../../util/object/object.util.cjs"),W=require("../../util/common/common.util.cjs"),P=require("../fs/fs.util.cjs"),A=require("../path/path.constant.cjs"),Q=require("../../util/validate/validate.util.cjs"),I=require("../../util/string/string.util.cjs"),v=require("../../constant/response-status.cjs"),f=require("../log/log.util.cjs");var z=Object.defineProperty,J=Object.defineProperties,X=Object.getOwnPropertyDescriptors,G=Object.getOwnPropertySymbols,Y=Object.prototype.hasOwnProperty,Z=Object.prototype.propertyIsEnumerable,F=(n,t,e)=>t in n?z(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e,O=(n,t)=>{for(var e in t||(t={}))Y.call(t,e)&&F(n,e,t[e]);if(G)for(var e of G(t))Z.call(t,e)&&F(n,e,t[e]);return n},V=(n,t)=>J(n,X(t)),ee=(n,t,e)=>F(n,typeof t!="symbol"?t+"":t,e),a=(n,t,e)=>new Promise((r,s)=>{var c=i=>{try{o(e.next(i))}catch(l){s(l)}},u=i=>{try{o(e.throw(i))}catch(l){s(l)}},o=i=>i.done?r(i.value):Promise.resolve(i.value).then(c,u);o((e=e.apply(n,t)).next())});function te(n){return n===n.toUpperCase()?n.charAt(0).toUpperCase()+n.slice(1).toLowerCase():n}const T={createGenericFields(){return{id:U.v4(),isDel:!1,createdAt:new Date,updatedAt:new Date}},applyPlugins(n,t){t.filter(e=>typeof e=="function").forEach(e=>n.plugin(e))},applyMiddlewares(n,t){t.forEach(({method:e,pre:r,post:s})=>{e&&r&&n.pre(e,r),e&&s&&n.post(e,s)})},createGenericSchema(n){return new n.Schema({id:{type:String,default:U.v4,unique:!0},isDel:{type:Boolean,default:!1}},{timestamps:!0})},createSchema({mongoose:n,schema:t,virtuals:e=[],standalone:r=!1}){const s=new n.Schema(t);return e.forEach(({name:c,options:u,get:o})=>{if(T.isDynamicVirtual(u)){const i=s.statics;i._dynamicVirtuals||(i._dynamicVirtuals=[]),i._dynamicVirtuals.push({name:c,options:u});const l=s.virtual(c);o?l.get(o):l.get(function(){var d;return((d=this._populated)==null?void 0:d[c])||(u!=null&&u.count?0:u!=null&&u.justOne?null:[])})}else{const i=s.virtual(c,u);o&&i.get(o)}}),r||s.add(T.createGenericSchema(n)),s},createModel({mongoose:n,name:t,schema:e,pagination:r=!1,aggregate:s=!1,virtuals:c=[],middlewares:u=[]}){if(!t)throw new Error("Model name is required.");if(n.models[t])return n.models[t];const o=T.createSchema({mongoose:n,schema:e,virtuals:c});return T.applyPlugins(o,[r&&K,s&&H]),T.applyMiddlewares(o,u),n.model(t,o)},validator:{isRequired(){return function(n){return a(this,null,function*(){return!Q.validate.isEmpty(n)})}},isUnique(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.length===0)throw new Error("Fields must be a non-empty array of strings.");const e={$or:n.map(s=>({[s]:t}))};return!(yield this.constructor.exists(e))})}},matchesRegex(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.some(e=>!(e instanceof RegExp)))throw new Error("regexArray must be an array of valid RegExp objects.");return n.every(e=>e.test(t))})}}},migrate:V(O({},B),{setConfig:n=>{const t=`// This file is automatically generated by the Cyberskill CLI.
+module.exports = ${JSON.stringify(n,null,4)}`;P.writeFileSync(A.PATH.MIGRATE_MONGO_CONFIG,t);const e=`
+${A.MIGRATE_MONGO_CONFIG}
+`;P.pathExistsSync(A.PATH.GIT_IGNORE)?P.readFileSync(A.PATH.GIT_IGNORE,"utf-8").split(`
+`).includes(A.MIGRATE_MONGO_CONFIG)||P.appendFileSync(A.PATH.GIT_IGNORE,e):P.writeFileSync(A.PATH.GIT_IGNORE,e)}}),regexify(n,t){if(!n)return{};let e=j.cloneDeep(n);if(!t||t.length===0)return e;for(const r of t){const s=r.toString().split("."),c=$.getNestedValue(e,s);if(typeof c=="string"&&c.length>0){const u={$regex:`.*${W.regexSearchMapper(c)}.*`,$options:"i"};e=$.setNestedValue(e,s,u)}}return e},isDynamicVirtual(n){return!!(n&&typeof n.ref=="function")}};function re(n){return n!==null&&typeof n=="object"&&"toObject"in n&&typeof n.toObject=="function"}function se(n,t,e){if(!n.length||!t||!(e!=null&&e.ref))return[];const r=new Map;return n.forEach(s=>{try{const c=e.ref(s);if(c==null)return;const u=typeof c=="string"?c:String(c);if(u&&u.trim()!==""){const o=te(u);r.has(o)||r.set(o,[]),r.get(o).push(s)}}catch(c){f.catchError(new Error(`Dynamic ref function failed for virtual "${t}": ${c instanceof Error?c.message:String(c)}`))}}),Array.from(r.entries()).map(([s,c])=>({model:s,docs:c}))}function q(n,t,e,r,s){return a(this,null,function*(){if(!t.length||!e.length||!r)return t;const c=e.filter(i=>{if(Array.isArray(r))return r.length>0&&r.some(l=>typeof l=="string"?l===i.name:l.path===i.name);if(typeof r=="string")return r===i.name;if(typeof r=="object"&&r!==null){const l=r;return l.path&&l.path===i.name||l.populate&&l.populate===i.name}return!1});if(c.length===0)return t;const u=j.cloneDeep(t.map(i=>re(i)?i.toObject():i));u.forEach(i=>{c.forEach(({name:l,options:d})=>{if(!(l in i)){const h=i;h[l]=d.count?0:d.justOne?null:[]}})});const o=new Map;for(const i of c){const{name:l,options:d}=i,h=se(u,l,d);for(const S of h){o.has(S.model)||o.set(S.model,{virtuals:[],localValueSets:new Map,docsByLocalValue:new Map});const m=o.get(S.model);m.virtuals.find(D=>D.name===l)||(m.virtuals.push(i),m.localValueSets.set(l,new Set));const M=m.localValueSets.get(l);S.docs.forEach(D=>{const C=D[d.localField];if(C!=null){const _=String(C);M.add(_);let R=-1;const N=D;N.id!==void 0?R=u.findIndex(b=>b.id===N.id):N._id!==void 0&&(R=u.findIndex(b=>{var E,g,p,y;return((g=(E=b._id)==null?void 0:E.toString)==null?void 0:g.call(E))===((y=(p=N._id)==null?void 0:p.toString)==null?void 0:y.call(p))})),R!==-1&&(m.docsByLocalValue.has(_)||m.docsByLocalValue.set(_,[]),m.docsByLocalValue.get(_).push(R))}})}}return yield Promise.all(Array.from(o.entries()).map(i=>a(null,[i],function*([l,d]){const h=n.models[l];if(!h)return;const S=new Set;if(d.localValueSets.forEach(_=>{_.forEach(R=>S.add(R))}),S.size===0)return;const m=[...new Set(d.virtuals.map(_=>_.options.foreignField))],M=Array.from(S);let D;m.length===1?D={[String(m[0])]:{$in:M}}:D={$or:m.map(_=>({[_]:{$in:M}}))};const C=yield h.find(D,s).lean();for(const _ of d.virtuals){const{name:R,options:N}=_,b=C.filter(E=>{const g=E[N.foreignField];return g!=null&&S.has(String(g))});if(N.count){const E=new Map;b.forEach(g=>{var p;const y=(p=g[N.foreignField])==null?void 0:p.toString();y&&E.set(y,(E.get(y)||0)+1)}),d.localValueSets.get(R).forEach(g=>{const p=d.docsByLocalValue.get(g)||[],y=E.get(g)||0;p.forEach(w=>{const x=u[w];x[R]===void 0&&(x[R]=y)})})}else{const E=new Map;b.forEach(g=>{var p;const y=(p=g[N.foreignField])==null?void 0:p.toString();y&&(E.has(y)||E.set(y,[]),E.get(y).push(g))}),d.localValueSets.get(R).forEach(g=>{const p=d.docsByLocalValue.get(g)||[],y=E.get(g)||[],w=N.justOne?y[0]||null:y;p.forEach(x=>{const L=u[x];L[R]=w})})}}}))),u})}class ne{constructor(t,e){ee(this,"collection"),this.collection=t.collection(e)}createOne(t){return a(this,null,function*(){try{const e=O(O({},T.createGenericFields()),t);return(yield this.collection.insertOne(e)).acknowledged?{success:!0,message:"Document created successfully",result:e}:{success:!1,message:"Document creation failed",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}}catch(e){return f.catchError(e)}})}createMany(t){return a(this,null,function*(){try{const e=t.map(s=>O(O({},T.createGenericFields()),s)),r=yield this.collection.insertMany(e);return r.insertedCount===0?{success:!1,message:"No documents were inserted",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:`${r.insertedCount} documents created successfully`,result:e}}catch(e){return f.catchError(e)}})}findOne(t){return a(this,null,function*(){try{const e=yield this.collection.findOne(t);return e?{success:!0,message:"Document found",result:e}:{success:!1,message:"Document not found",code:v.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(e){return f.catchError(e)}})}findAll(){return a(this,arguments,function*(t={}){try{return{success:!0,message:"Documents retrieved successfully",result:yield this.collection.find(t).toArray()}}catch(e){return f.catchError(e)}})}count(){return a(this,arguments,function*(t={}){try{const e=yield this.collection.countDocuments(t);return{success:!0,message:`${e} documents counted successfully`,result:e}}catch(e){return f.catchError(e)}})}updateOne(t,e){return a(this,null,function*(){try{const r=yield this.collection.updateOne(t,{$set:e});return r.matchedCount===0?{success:!1,message:"No documents matched the filter",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Document updated successfully",result:r}}catch(r){return f.catchError(r)}})}updateMany(t,e){return a(this,null,function*(){try{const r=yield this.collection.updateMany(t,{$set:e});return r.matchedCount===0?{success:!1,message:"No documents matched the filter",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Documents updated successfully",result:r}}catch(r){return f.catchError(r)}})}deleteOne(t){return a(this,null,function*(){try{const e=yield this.collection.deleteOne(t);return e.deletedCount===0?{success:!1,message:"No documents matched the filter",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Document deleted successfully",result:e}}catch(e){return f.catchError(e)}})}deleteMany(t){return a(this,null,function*(){try{const e=yield this.collection.deleteMany(t);return e.deletedCount===0?{success:!1,message:"No documents matched the filter",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}:{success:!0,message:"Documents deleted successfully",result:e}}catch(e){return f.catchError(e)}})}}class ce{constructor(t){this.model=t}getModelName(){return this.model.modelName}findOne(){return a(this,arguments,function*(t={},e={},r={},s){try{const c=this.model.findOne(t,e,r),o=this.model.schema.statics._dynamicVirtuals;s&&(!o||o.length===0)&&c.populate(s);const i=yield c.exec();if(!i)return{success:!1,message:`No ${this.getModelName()} found.`,code:v.RESPONSE_STATUS.NOT_FOUND.CODE};let l=i;if(o&&o.length>0){const d=yield q(this.model.base,[i],o,s);l=d&&d[0]?d[0]:i}return{success:!0,result:l}}catch(c){return f.catchError(c)}})}findAll(){return a(this,arguments,function*(t={},e={},r={},s){try{const c=this.model.find(t,e,r),o=this.model.schema.statics._dynamicVirtuals;s&&(!o||o.length===0)&&c.populate(s);const i=yield c.exec();let l=i;return o&&o.length>0&&i.length>0&&(l=yield q(this.model.base,i,o,s)),{success:!0,result:l}}catch(c){return f.catchError(c)}})}findPaging(){return a(this,arguments,function*(t={},e={}){try{const s=this.model.schema.statics._dynamicVirtuals,c=O({},e);s&&s.length>0&&(c.populate=void 0);const u=yield this.model.paginate(t,c);let o=u.docs;return s&&s.length>0&&u.docs.length>0&&(o=yield q(this.model.base,u.docs,s,e.populate)),{success:!0,result:V(O({},u),{docs:o})}}catch(r){return f.catchError(r)}})}findPagingAggregate(t){return a(this,arguments,function*(e,r={}){try{const c=this.model.schema.statics._dynamicVirtuals,u=O({},r);c&&c.length>0&&(u.populate=void 0);const o=yield this.model.aggregatePaginate(this.model.aggregate(e),u);let i=o.docs;return c&&c.length>0&&o.docs.length>0&&(i=yield q(this.model.base,o.docs,c,r.populate)),{success:!0,result:V(O({},o),{docs:i})}}catch(s){return f.catchError(s)}})}count(){return a(this,arguments,function*(t={}){try{return{success:!0,result:yield this.model.countDocuments(t)}}catch(e){return f.catchError(e)}})}createOne(t){return a(this,null,function*(){try{return{success:!0,result:yield this.model.create(t)}}catch(e){return f.catchError(e)}})}createMany(t){return a(this,arguments,function*(e,r={}){try{return{success:!0,result:(yield this.model.insertMany(e,r)).map(u=>u instanceof k.Document?u.toObject():null).filter(u=>u!==null)}}catch(s){return f.catchError(s)}})}updateOne(){return a(this,arguments,function*(t={},e={},r={}){try{const s=yield this.model.findOneAndUpdate(t,e,O({new:!0},r)).exec();return s?{success:!0,result:s}:{success:!1,message:`Failed to update ${this.getModelName()}.`,code:v.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(s){return f.catchError(s)}})}updateMany(){return a(this,arguments,function*(t={},e={},r={}){try{return{success:!0,result:yield this.model.updateMany(t,e,r).exec()}}catch(s){return f.catchError(s)}})}deleteOne(){return a(this,arguments,function*(t={},e={}){try{const r=yield this.model.findOneAndDelete(t,e).exec();return r?{success:!0,result:r}:{success:!1,message:`No ${this.getModelName()} found to delete.`,code:v.RESPONSE_STATUS.NOT_FOUND.CODE}}catch(r){return f.catchError(r)}})}deleteMany(){return a(this,arguments,function*(t={},e={}){try{const r=yield this.model.deleteMany(t,e).exec();return r.deletedCount===0?{success:!1,message:"No documents found to delete.",code:v.RESPONSE_STATUS.NOT_FOUND.CODE}:{success:!0,result:r}}catch(r){return f.catchError(r)}})}createShortId(t,e=4){return a(this,null,function*(){try{const s=Array.from({length:10},(o,i)=>I.generateShortId(t,i+e)),u=(yield Promise.all(s.map(o=>this.model.exists({shortId:o})))).findIndex(o=>!o);if(u!==-1){const o=s[u];if(o)return{success:!0,result:o}}return{success:!1,message:"Failed to create a unique shortId",code:v.RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE}}catch(r){return f.catchError(r)}})}createSlugQuery({slug:t,field:e,isObject:r,filter:s}){const c=O({},s!=null?s:{});return r?V(O({},c),{$or:[{[`slug.${e}`]:t},{slugHistory:{$elemMatch:{[`slug.${e}`]:t}}}]}):V(O({},c),{$or:[{slug:t},{slugHistory:t}]})}createUniqueSlug(t){return a(this,arguments,function*({slug:e,field:r,isObject:s,filter:c}){const u=I.generateSlug(e),i=Array.from({length:100},(h,S)=>S===0?u:`${u}-${S}`),d=(yield Promise.all(i.map(h=>this.model.exists(this.createSlugQuery({slug:h,field:r,isObject:s,filter:c}))))).findIndex(h=>!h);if(d!==-1){const h=i[d];if(h)return h}return`${u}-${Date.now()}`})}createSlug(t){return a(this,arguments,function*({field:e,from:r,filter:s}){try{const c=r[e];return j.isObject(c)?{success:!0,result:Object.fromEntries(yield Promise.all(Object.entries(c).map(l=>a(this,[l],function*([d,h]){const S=yield this.createUniqueSlug({slug:h,field:d,isObject:!0,filter:s});return[d,S]}))))}:{success:!0,result:yield this.createUniqueSlug({slug:c,field:e,isObject:!1,filter:s})}}catch(c){return f.catchError(c)}})}checkSlug(t){return a(this,arguments,function*({slug:e,field:r,from:s,filter:c}){try{const u=s[r];if(j.isObject(u)){const h=Object.values(u).map(m=>I.generateSlug(m));return(yield Promise.all(h.map(m=>this.model.exists(this.createSlugQuery({slug:m,field:r,isObject:!0,filter:c}))))).some(m=>m)?{success:!0,result:!0}:{success:!0,result:!1}}const i=I.generateSlug(e);return{success:!0,result:(yield this.model.exists(this.createSlugQuery({slug:i,field:r,isObject:!1,filter:c})))!==null}}catch(u){return f.catchError(u)}})}aggregate(t){return a(this,null,function*(){try{return{success:!0,result:yield this.model.aggregate(t)}}catch(e){return f.catchError(e)}})}}exports.MongoController=ne;exports.MongooseController=ce;exports.mongo=T;

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

@@ -1,14 +1,46 @@
 import { default as mongooseRaw } from 'mongoose';
 import { default as migrate } from 'migrate-mongo';
-import { default as aggregatePaginate } from 'mongoose-aggregate-paginate-v2';
-import { default as mongoosePaginate } from 'mongoose-paginate-v2';
 import { I_Return } from '../../typescript/index.js';
-import { C_Db, C_Document, I_CreateModelOptions, I_CreateSchemaOptions, I_DeleteOptionsExtended, I_ExtendedModel, I_GenericDocument, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_MongooseModelMiddleware, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Filter, T_FilterQuery, T_Input_Populate, T_InsertManyOptions, T_MongoosePlugin, T_MongooseShema, T_PaginateOptionsWithPopulate, T_PaginateResult, T_PipelineStage, T_ProjectionType, T_QueryOptions, T_UpdateQuery, T_UpdateResult, T_WithId } from './mongo.type.js';
-export { aggregatePaginate, mongoosePaginate };
+import { C_Db, C_Document, I_CreateModelOptions, I_CreateSchemaOptions, I_DeleteOptionsExtended, I_DynamicVirtualOptions, I_ExtendedModel, I_GenericDocument, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_MongooseModelMiddleware, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Filter, T_FilterQuery, T_Input_Populate, T_InsertManyOptions, T_MongoosePlugin, T_MongooseShema, T_PaginateResult, T_PipelineStage, T_ProjectionType, T_QueryOptions, T_UpdateQuery, T_UpdateResult, T_VirtualOptions, T_WithId } from './mongo.type.js';
+/**
+ * MongoDB utility object providing comprehensive database operations and utilities.
+ * This object contains methods for creating generic fields, applying plugins and middlewares,
+ * creating schemas and models, validation functions, migration utilities, and regex filtering.
+ */
 export declare const mongo: {
+    /**
+     * Creates generic fields that are commonly used across MongoDB documents.
+     * This function generates standard fields including a UUID, deletion flag, and timestamps
+     * that can be applied to any document schema.
+     *
+     * @returns An object containing generic document fields (id, isDel, createdAt, updatedAt).
+     */
     createGenericFields(): I_GenericDocument;
+    /**
+     * Applies plugins to a Mongoose schema.
+     * This function filters out falsy plugins and applies the remaining valid plugins
+     * to the provided schema.
+     *
+     * @param schema - The Mongoose schema to apply plugins to.
+     * @param plugins - An array of plugin functions or false values to filter and apply.
+     */
     applyPlugins<T>(schema: T_MongooseShema<T>, plugins: Array<T_MongoosePlugin | false>): void;
+    /**
+     * Applies middleware functions to a Mongoose schema.
+     * This function configures pre and post middleware for specified methods on the schema.
+     *
+     * @param schema - The Mongoose schema to apply middleware to.
+     * @param middlewares - An array of middleware configurations with method, pre, and post functions.
+     */
     applyMiddlewares<T extends Partial<C_Document>>(schema: T_MongooseShema<T>, middlewares: I_MongooseModelMiddleware<T>[]): void;
+    /**
+     * Creates a generic Mongoose schema with common fields.
+     * This function creates a base schema with UUID field and deletion flag,
+     * configured with automatic timestamps.
+     *
+     * @param mongoose - The Mongoose instance to create the schema with.
+     * @returns A Mongoose schema with generic document fields.
+     */
     createGenericSchema(mongoose: typeof mongooseRaw): mongooseRaw.Schema<I_GenericDocument, mongooseRaw.Model<I_GenericDocument, any, any, any, mongooseRaw.Document<unknown, any, I_GenericDocument, any> & I_GenericDocument & Required<{
         _id: unknown;
     }> & {
@@ -18,58 +50,331 @@ export declare const mongo: {
     }> & {
         __v: number;
     }>;
-    createSchema<T>({ mongoose, schema, virtuals, standalone, }: I_CreateSchemaOptions<T>): T_MongooseShema<T>;
-    createModel<T extends Partial<C_Document>>({ mongoose: currentMongooseInstance, name, schema, pagination, aggregate, virtuals, middlewares, }: I_CreateModelOptions<T>): I_ExtendedModel<T>;
+    /**
+     * Creates a Mongoose schema with optional virtual fields and generic fields.
+     * This function creates a new Mongoose schema from the provided schema definition,
+     * optionally adds virtual fields, and includes generic fields (unless standalone is true).
+     *
+     * @param options - Configuration options including mongoose instance, schema definition, virtuals, and standalone flag.
+     * @param options.mongoose - The Mongoose instance to use for schema creation.
+     * @param options.schema - The schema definition object.
+     * @param options.virtuals - Optional array of virtual field configurations.
+     * @param options.standalone - Whether to exclude generic fields (default: false).
+     * @returns A configured Mongoose schema.
+     */
+    createSchema<T, R extends string = string>({ mongoose, schema, virtuals, standalone, }: I_CreateSchemaOptions<T, R>): T_MongooseShema<T>;
+    /**
+     * Creates a Mongoose model with plugins, middleware, and pagination support.
+     * This function creates a model from a schema with optional pagination and aggregation plugins,
+     * and applies any specified middleware. If a model with the same name already exists, it returns the existing model.
+     *
+     * @param options - Configuration options including mongoose instance, model name, schema, and feature flags.
+     * @param options.mongoose - The Mongoose instance to use for model creation.
+     * @param options.name - The name of the model to create.
+     * @param options.schema - The schema definition for the model.
+     * @param options.pagination - Whether to enable pagination plugin (default: false).
+     * @param options.aggregate - Whether to enable aggregation pagination plugin (default: false).
+     * @param options.virtuals - Optional array of virtual field configurations.
+     * @param options.middlewares - Optional array of middleware configurations.
+     * @returns A configured Mongoose model with extended functionality.
+     * @throws {Error} When the model name is not provided.
+     */
+    createModel<T extends Partial<C_Document>, R extends string = string>({ mongoose: currentMongooseInstance, name, schema, pagination, aggregate, virtuals, middlewares, }: I_CreateModelOptions<T, R>): I_ExtendedModel<T>;
+    /**
+     * Validation utilities for Mongoose schemas.
+     * This object provides common validation functions that can be used in Mongoose schema definitions.
+     */
     validator: {
+        /**
+         * Creates a required field validator.
+         * This function returns a validator that checks if a field value is not empty
+         * using the validate.isEmpty utility.
+         *
+         * @returns A validation function that returns true if the field is not empty.
+         */
         isRequired<T>(): (this: T, value: unknown) => Promise<boolean>;
+        /**
+         * Creates a unique field validator.
+         * This function returns a validator that checks if a field value is unique
+         * across the specified fields in the collection.
+         *
+         * @param fields - An array of field names to check for uniqueness.
+         * @returns A validation function that returns true if the value is unique across the specified fields.
+         * @throws {Error} When fields is not a non-empty array of strings.
+         */
         isUnique<T extends {
             constructor: {
-                exists: (query: Record<string, unknown>) => Promise<unknown>;
+                exists: (query: {
+                    [key: string]: unknown;
+                }) => Promise<unknown>;
             };
         }>(fields: string[]): (this: T, value: unknown) => Promise<boolean>;
+        /**
+         * Creates a regex pattern validator.
+         * This function returns a validator that checks if a string value matches
+         * all provided regular expressions.
+         *
+         * @param regexArray - An array of regular expressions to test against the value.
+         * @returns A validation function that returns true if the value matches all regex patterns.
+         * @throws {Error} When regexArray is not an array of valid RegExp objects.
+         */
         matchesRegex(regexArray: RegExp[]): (value: string) => Promise<boolean>;
     };
+    /**
+     * Migration utilities for MongoDB.
+     * This object extends the migrate-mongo library with additional configuration utilities.
+     */
     migrate: {
+        /**
+         * Sets the migration configuration and updates .gitignore.
+         * This function creates a migration configuration file and ensures it's properly
+         * excluded from version control.
+         *
+         * @param options - Migration configuration options to write to the config file.
+         */
         setConfig: (options: Partial<migrate.config.Config>) => void;
         init(): Promise<void>;
         create(description: string): Promise<string>;
-        up(db: mongooseRaw.mongo.Db, client: mongooseRaw.mongo.MongoClient): Promise<string[]>;
-        down(db: mongooseRaw.mongo.Db, client: mongooseRaw.mongo.MongoClient): Promise<string[]>;
-        status(db: mongooseRaw.mongo.Db): Promise<migrate.MigrationStatus[]>;
+        up(db: import('mongodb').Db, client: import('mongodb').MongoClient): Promise<string[]>;
+        down(db: import('mongodb').Db, client: import('mongodb').MongoClient): Promise<string[]>;
+        status(db: import('mongodb').Db): Promise<migrate.MigrationStatus[]>;
         database: typeof migrate.database;
         config: typeof migrate.config;
     };
+    /**
+     * Converts string values in a filter to regex patterns for case-insensitive search.
+     * This function recursively processes a filter object and converts string values in specified fields
+     * to MongoDB regex patterns that support accented character matching.
+     *
+     * @param filter - The filter object to process.
+     * @param fields - An array of field names to convert to regex patterns.
+     * @returns A new filter object with string values converted to regex patterns.
+     */
     regexify<T>(filter?: T_FilterQuery<T>, fields?: (keyof T | string)[]): T_FilterQuery<T>;
+    /**
+     * Checks if a virtual options object has a dynamic ref function.
+     *
+     * @param options - The virtual options to check.
+     * @returns True if the options contain a dynamic ref function.
+     */
+    isDynamicVirtual<T, R extends string = string>(options?: T_VirtualOptions<T, R>): options is I_DynamicVirtualOptions<T, R>;
 };
+/**
+ * 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.
+ */
 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;
+    /**
+     * 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_FilterQuery<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_FilterQuery<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T[]>>;
-    findPaging(filter?: T_FilterQuery<T>, options?: T_PaginateOptionsWithPopulate): Promise<I_Return<T_PaginateResult<T>>>;
-    findPagingAggregate(pipeline: T_PipelineStage[], options?: T_PaginateOptionsWithPopulate): Promise<I_Return<T_AggregatePaginateResult<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_FilterQuery<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_FilterQuery<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_FilterQuery<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_FilterQuery<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_FilterQuery<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_FilterQuery<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.filter - Additional filter conditions to apply to the query.
+     * @returns A MongoDB query object for checking slug existence.
+     */
     createSlugQuery({ slug, field, isObject, filter }: I_Input_GenerateSlug<T>): {
         $or: ({
             [x: string]: string;
@@ -226,8 +531,46 @@ export declare class MongooseController<T extends Partial<C_Document>> {
         $comment?: string;
         $expr?: Record<string, any>;
     };
+    /**
+     * 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.filter - Additional filter conditions to apply when checking slug existence.
+     * @returns A promise that resolves to a unique slug string.
+     */
     createUniqueSlug({ slug, field, isObject, 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.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 }: 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.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 }: 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[]>>;
 }