@cyberskill/shared 2.1.0 → 2.3.0

package/LICENSE

@@ -1,7 +1,7 @@
 
 MIT License
 
-Copyright (c) 2025 Stephen Cheng <https://github.com/zintaen>
+Copyright (c) 2025 CyberSkill JSC <https://github.com/cyberskill-world/shared>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,7 +8,7 @@
 [![📦 npm version](https://img.shields.io/npm/v/@cyberskill/shared?style=for-the-badge&logo=npm)](https://npmjs.com/package/@cyberskill/shared)
 [![📥 npm downloads](https://img.shields.io/npm/dm/@cyberskill/shared?style=for-the-badge&logo=npm)](https://npmjs.com/package/@cyberskill/shared)
 [![📚 JSDoc Documentation](https://img.shields.io/badge/JSDoc-Documentation-blue?style=for-the-badge&logo=javascript)](https://www.jsdocs.io/package/@cyberskill/shared)
-[![📄 License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/licenses/MIT)
+[![📄 License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](LICENSE)
 
 </div>
 

package/dist/config/vitest/vitest.e2e.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("@vitejs/plugin-react-swc"),i=require("lodash-es"),o=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.cjs");function s(e){const r={plugins:[t()],test:{include:["**/*.test.e2e.?(c|m)[jt]s?(x)"],browser:{enabled:!0,provider:"playwright",instances:[{browser:"chromium"},{browser:"firefox"},{browser:"webkit"}]}}};return o.defineConfig(i.merge(r,e))}exports.vitestE2E=s;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("@vitejs/plugin-react-swc"),i=require("lodash-es"),o=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.cjs");function s(e){const r={plugins:[t()],test:{include:["**/*.test.e2e.?(c|m)[jt]s?(x)"],browser:{enabled:!0,provider:"playwright",instances:[{browser:"chromium"},{browser:"firefox"},{browser:"webkit"}]}}};return o.defineConfig(i.merge(r,e))}exports.vitestE2E=s;

package/dist/config/vitest/vitest.e2e.js

@@ -1,6 +1,6 @@
 import t from "@vitejs/plugin-react-swc";
 import { merge as o } from "lodash-es";
-import { defineConfig as i } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.js";
+import { defineConfig as i } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.js";
 function f(r) {
   const e = {
     plugins: [t()],

package/dist/config/vitest/vitest.unit.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@vitejs/plugin-react-swc"),n=require("lodash-es"),s=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.cjs");function r(e){const t={plugins:[i()],test:{globals:!0,environment:"jsdom",pool:"vmThreads",include:["**/*.test.unit.?(c|m)[jt]s?(x)"],setupFiles:["./vitest.unit.setup.ts"]}};return s.defineConfig(n.merge(t,e))}exports.vitestUnit=r;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@vitejs/plugin-react-swc"),n=require("lodash-es"),s=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.cjs");function r(e){const t={plugins:[i()],test:{globals:!0,environment:"jsdom",pool:"vmThreads",include:["**/*.test.unit.?(c|m)[jt]s?(x)"],setupFiles:["./vitest.unit.setup.ts"]}};return s.defineConfig(n.merge(t,e))}exports.vitestUnit=r;

package/dist/config/vitest/vitest.unit.js

@@ -1,6 +1,6 @@
 import i from "@vitejs/plugin-react-swc";
 import { merge as o } from "lodash-es";
-import { defineConfig as n } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.js";
+import { defineConfig as n } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.js";
 function u(t) {
   const e = {
     plugins: [i()],

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

@@ -100,9 +100,9 @@ export interface I_MongooseModelMiddleware<T extends Partial<C_Document>> {
 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;
+    pagination?: boolean;
     aggregate?: boolean;
     middlewares?: I_MongooseModelMiddleware<T>[];
-    pagination?: boolean;
 }
 export type T_Input_Populate = string | string[] | T_PopulateOptions | T_PopulateOptions[];
 export interface I_PaginateOptionsWithPopulate extends T_PaginateOptions, Omit<T_PopulateOption, 'populate'> {
@@ -118,12 +118,10 @@ export interface I_Input_FindAll<T> extends T_PopulateOption {
     projection?: T_ProjectionType<T>;
     options?: T_QueryOptions<T>;
 }
-export type I_Input_FindPaging<T = undefined> = T extends undefined ? {
-    options?: I_PaginateOptionsWithPopulate;
-} : {
+export interface I_Input_FindPaging<T = undefined> {
     filter?: T_FilterQuery<T>;
     options?: I_PaginateOptionsWithPopulate;
-};
+}
 export interface I_Input_FindPagingAggregate {
     pipeline: T_PipelineStage[];
     options?: I_PaginateOptionsWithPopulate;

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

@@ -1,5 +1,5 @@
-"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.
+"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"),R=require("../../constant/response-status.cjs"),f=require("../log/log.util.cjs");var J=Object.defineProperty,z=Object.defineProperties,X=Object.getOwnPropertyDescriptors,G=Object.getOwnPropertySymbols,Y=Object.prototype.hasOwnProperty,Z=Object.prototype.propertyIsEnumerable,F=(n,t,e)=>t in n?J(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)=>z(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,{toJSON:{virtuals:!0},toObject:{virtuals:!0}});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,virtuals:r=[],pagination:s=!0,aggregate:c=!0,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:r});return(s||c)&&T.applyPlugins(o,[s&&K,c&&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;
+`).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 v=-1;const N=D;N.id!==void 0?v=u.findIndex(b=>b.id===N.id):N._id!==void 0&&(v=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))})),v!==-1&&(m.docsByLocalValue.has(_)||m.docsByLocalValue.set(_,[]),m.docsByLocalValue.get(_).push(v))}})}}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(v=>S.add(v))}),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:v,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(v).forEach(g=>{const p=d.docsByLocalValue.get(g)||[],y=E.get(g)||0;p.forEach(w=>{const x=u[w];x[v]===void 0&&(x[v]=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(v).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[v]=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:R.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:R.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:R.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:R.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:R.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:R.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:R.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:R.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:R.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:R.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:R.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:R.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

@@ -79,7 +79,7 @@ export declare const mongo: {
      * @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>;
+    createModel<T extends Partial<C_Document>, R extends string = string>({ mongoose: currentMongooseInstance, name, schema, virtuals, pagination, aggregate, 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.
@@ -132,7 +132,9 @@ export declare const mongo: {
          *
          * @param options - Migration configuration options to write to the config file.
          */
-        setConfig: (options: Partial<migrate.config.Config>) => void;
+        setConfig: (options: Partial<migrate.config.Config> & {
+            moduleSystem?: "commonjs" | "esm";
+        }) => void;
         init(): Promise<void>;
         create(description: string): Promise<string>;
         up(db: import('mongodb').Db, client: import('mongodb').MongoClient): Promise<string[]>;

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

@@ -4,8 +4,8 @@ import { Document as K } from "mongoose";
 import W from "mongoose-aggregate-paginate-v2";
 import Q from "mongoose-paginate-v2";
 import { v4 as F } from "uuid";
-import { getNestedValue as H, setNestedValue as z } from "../../util/object/object.util.js";
-import { regexSearchMapper as J } from "../../util/common/common.util.js";
+import { getNestedValue as H, setNestedValue as J } from "../../util/object/object.util.js";
+import { regexSearchMapper as z } from "../../util/common/common.util.js";
 import { writeFileSync as G, pathExistsSync as X, readFileSync as Y, appendFileSync as Z } from "../fs/fs.util.js";
 import { PATH as x, MIGRATE_MONGO_CONFIG as q } from "../path/path.constant.js";
 import { validate as ee } from "../../util/validate/validate.util.js";
@@ -112,7 +112,12 @@ const b = {
     virtuals: e = [],
     standalone: r = !1
   }) {
-    const s = new n.Schema(t);
+    const s = new n.Schema(t, {
+      toJSON: { virtuals: !0 },
+      // So `res.json()` and other `JSON.stringify()` functions include virtuals
+      toObject: { virtuals: !0 }
+      // So `console.log()` and other functions that use `toObject()` include virtuals
+    });
     return e.forEach(({ name: c, options: u, get: o }) => {
       if (b.isDynamicVirtual(u)) {
         const i = s.statics;
@@ -151,19 +156,19 @@ const b = {
     mongoose: n,
     name: t,
     schema: e,
-    pagination: r = !1,
-    aggregate: s = !1,
-    virtuals: c = [],
+    virtuals: r = [],
+    pagination: s = !0,
+    aggregate: c = !0,
     middlewares: u = []
   }) {
     if (!t)
       throw new Error("Model name is required.");
     if (n.models[t])
       return n.models[t];
-    const o = b.createSchema({ mongoose: n, schema: e, virtuals: c });
-    return b.applyPlugins(o, [
-      r && Q,
-      s && W
+    const o = b.createSchema({ mongoose: n, schema: e, virtuals: r });
+    return (s || c) && b.applyPlugins(o, [
+      s && Q,
+      c && W
     ]), b.applyMiddlewares(o, u), n.model(t, o);
   },
   /**
@@ -265,10 +270,10 @@ ${q}
       const s = r.toString().split("."), c = H(e, s);
       if (typeof c == "string" && c.length > 0) {
         const u = {
-          $regex: `.*${J(c)}.*`,
+          $regex: `.*${z(c)}.*`,
           $options: "i"
         };
-        e = z(e, s, u);
+        e = J(e, s, u);
       }
     }
     return e;
@@ -353,8 +358,8 @@ function P(n, t, e, r, s) {
             let v = -1;
             const D = N;
             D.id !== void 0 ? v = u.findIndex((V) => V.id === D.id) : D._id !== void 0 && (v = u.findIndex((V) => {
-              var O, g, S, y;
-              return ((g = (O = V._id) == null ? void 0 : O.toString) == null ? void 0 : g.call(O)) === ((y = (S = D._id) == null ? void 0 : S.toString) == null ? void 0 : y.call(S));
+              var O, y, S, g;
+              return ((y = (O = V._id) == null ? void 0 : O.toString) == null ? void 0 : y.call(O)) === ((g = (S = D._id) == null ? void 0 : S.toString) == null ? void 0 : g.call(S));
             })), v !== -1 && (h.docsByLocalValue.has(_) || h.docsByLocalValue.set(_, []), h.docsByLocalValue.get(_).push(v));
           }
         });
@@ -375,30 +380,30 @@ function P(n, t, e, r, s) {
       const C = yield m.find(N, s).lean();
       for (const _ of d.virtuals) {
         const { name: v, options: D } = _, V = C.filter((O) => {
-          const g = O[D.foreignField];
-          return g != null && p.has(String(g));
+          const y = O[D.foreignField];
+          return y != null && p.has(String(y));
         });
         if (D.count) {
           const O = /* @__PURE__ */ new Map();
-          V.forEach((g) => {
+          V.forEach((y) => {
             var S;
-            const y = (S = g[D.foreignField]) == null ? void 0 : S.toString();
-            y && O.set(y, (O.get(y) || 0) + 1);
-          }), d.localValueSets.get(v).forEach((g) => {
-            const S = d.docsByLocalValue.get(g) || [], y = O.get(g) || 0;
+            const g = (S = y[D.foreignField]) == null ? void 0 : S.toString();
+            g && O.set(g, (O.get(g) || 0) + 1);
+          }), d.localValueSets.get(v).forEach((y) => {
+            const S = d.docsByLocalValue.get(y) || [], g = O.get(y) || 0;
             S.forEach((A) => {
               const I = u[A];
-              I[v] === void 0 && (I[v] = y);
+              I[v] === void 0 && (I[v] = g);
             });
           });
         } else {
           const O = /* @__PURE__ */ new Map();
-          V.forEach((g) => {
+          V.forEach((y) => {
             var S;
-            const y = (S = g[D.foreignField]) == null ? void 0 : S.toString();
-            y && (O.has(y) || O.set(y, []), O.get(y).push(g));
-          }), d.localValueSets.get(v).forEach((g) => {
-            const S = d.docsByLocalValue.get(g) || [], y = O.get(g) || [], A = D.justOne ? y[0] || null : y;
+            const g = (S = y[D.foreignField]) == null ? void 0 : S.toString();
+            g && (O.has(g) || O.set(g, []), O.get(g).push(y));
+          }), d.localValueSets.get(v).forEach((y) => {
+            const S = d.docsByLocalValue.get(y) || [], g = O.get(y) || [], A = D.justOne ? g[0] || null : g;
             S.forEach((I) => {
               const B = u[I];
               B[v] = A;

package/dist/typescript/common.type.d.ts

@@ -22,17 +22,50 @@ export interface I_Log {
     trace: typeof consola['trace'];
     verbose: typeof consola['verbose'];
 }
-export interface I_ReturnSuccess<T, E = unknown> {
-    success: true;
-    result: T & E;
+/**
+ * Base interface for return types with common properties.
+ */
+export interface I_ReturnBase {
+    success: boolean;
     message?: string;
     code?: number | string;
 }
-export interface I_ReturnFailure {
+/**
+ * Success return type with result data.
+ * @template T - The main result type
+ * @template E - Additional properties to merge with the result (defaults to unknown)
+ */
+export interface I_ReturnSuccess<T, E = unknown> extends I_ReturnBase {
+    success: true;
+    result: T & E;
+}
+/**
+ * Failure return type with error information.
+ */
+export interface I_ReturnFailure extends I_ReturnBase {
     success: false;
     message: string;
     code: number | string;
 }
+/**
+ * Discriminated union type for function return values.
+ * Provides type-safe handling of success and failure cases.
+ *
+ * @template T - The success result type (defaults to void)
+ * @template E - Additional properties to merge with the result (defaults to unknown)
+ *
+ * @example
+ * ```typescript
+ * function fetchUser(id: string): I_Return<User> {
+ *   try {
+ *     const user = await getUser(id);
+ *     return { success: true, result: user };
+ *   } catch (error) {
+ *     return { success: false, message: error.message, code: 'USER_NOT_FOUND' };
+ *   }
+ * }
+ * ```
+ */
 export type I_Return<T = void, E = unknown> = I_ReturnSuccess<T, E> | I_ReturnFailure;
 export declare enum E_Environment {
     PRODUCTION = "production",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@cyberskill/shared",
     "type": "module",
-    "version": "2.1.0",
+    "version": "2.3.0",
     "description": "CyberSkill Shared",
     "author": "Stephen Cheng",
     "license": "MIT",
@@ -207,7 +207,7 @@
         "test:unit": "tsx src/node/cli/index.ts test:unit"
     },
     "dependencies": {
-        "@antfu/eslint-config": "4.19.0",
+        "@antfu/eslint-config": "5.0.0",
         "@apollo/client": "3.13.8",
         "@apollo/client-integration-nextjs": "0.12.2",
         "@apollo/server": "5.0.0",
@@ -271,7 +271,7 @@
         "@commitlint/cli": "19.8.1",
         "@commitlint/config-conventional": "19.8.1",
         "@eslint/config-inspector": "1.1.0",
-        "@next/eslint-plugin-next": "15.4.3",
+        "@next/eslint-plugin-next": "15.4.4",
         "@testing-library/jest-dom": "6.6.3",
         "@testing-library/react": "16.3.0",
         "@types/apollo-upload-client": "18.0.0",
@@ -297,7 +297,7 @@
         "@types/yargs": "17.0.33",
         "@vitest/browser": "3.2.4",
         "eslint": "9.31.0",
-        "eslint-config-next": "15.4.3",
+        "eslint-config-next": "15.4.4",
         "glob": "11.0.3",
         "lint-staged": "16.1.2",
         "node-modules-inspector": "1.0.0",