@cyberskill/shared 3.12.0 → 3.14.0

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

@@ -1 +1,2 @@
-export {}
+export * from './fs.type.js';
+export * from './fs.util.js';

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

@@ -1 +1,2 @@
-export {}
+export * from './log.type.js';
+export * from './log.util.js';

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

@@ -0,0 +1,46 @@
+import { I_Log as I_LogCommon } from '../../typescript/index.js';
+export type { I_CatchErrorOptions } from '../../util/log/index.js';
+/**
+ * Enum representing the type of issues for logging and error handling.
+ * - Error: Represents an error issue.
+ * - Warning: Represents a warning issue.
+ */
+export declare enum E_IssueType {
+    Error = "error",
+    Warning = "warning"
+}
+export interface I_IssueEntry {
+    type: E_IssueType;
+    file: string;
+    message: string;
+    position?: string;
+    rule?: string;
+}
+export interface I_ThrowError {
+    message?: string;
+    status?: {
+        CODE: string | number;
+        MESSAGE: string;
+    };
+    type?: 'graphql' | 'rest';
+}
+export interface I_Log extends I_LogCommon {
+    printBoxedLog: (title: string, issues: I_IssueEntry[], color?: string) => void;
+    /**
+     * Creates a context-aware logger that prefixes all messages with a correlation ID.
+     * Useful for distributed tracing across CyberSkill services.
+     *
+     * @param correlationId - A UUID correlation ID. If not provided, a new UUID is generated.
+     * @returns A logger with standard methods that prefix output with the correlation ID.
+     */
+    withContext: (correlationId?: string) => {
+        correlationId: string;
+        fatal: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        log: (...args: unknown[]) => void;
+        info: (...args: unknown[]) => void;
+        success: (...args: unknown[]) => void;
+        debug: (...args: unknown[]) => void;
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"log.type.js","names":[],"sources":["../../../src/node/log/log.type.ts"],"sourcesContent":["import type { I_Log as I_LogCommon } from '#typescript/index.js';\n\nexport type { I_CatchErrorOptions } from '#util/log/index.js';\n\n/**\n * Enum representing the type of issues for logging and error handling.\n * - Error: Represents an error issue.\n * - Warning: Represents a warning issue.\n */\nexport enum E_IssueType {\n    Error = 'error',\n    Warning = 'warning',\n}\n\nexport interface I_IssueEntry {\n    type: E_IssueType;\n    file: string;\n    message: string;\n    position?: string;\n    rule?: string;\n}\n\nexport interface I_ThrowError {\n    message?: string;\n    status?: {\n        CODE: string | number;\n        MESSAGE: string;\n    };\n    type?: 'graphql' | 'rest';\n}\n\nexport interface I_Log extends I_LogCommon {\n    printBoxedLog: (\n        title: string,\n        issues: I_IssueEntry[],\n        color?: string,\n    ) => void;\n}\n"],"mappings":";AASA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,UAAA;KACH"}
+{"version":3,"file":"log.type.js","names":[],"sources":["../../../src/node/log/log.type.ts"],"sourcesContent":["import type { I_Log as I_LogCommon } from '#typescript/index.js';\n\nexport type { I_CatchErrorOptions } from '#util/log/index.js';\n\n/**\n * Enum representing the type of issues for logging and error handling.\n * - Error: Represents an error issue.\n * - Warning: Represents a warning issue.\n */\nexport enum E_IssueType {\n    Error = 'error',\n    Warning = 'warning',\n}\n\nexport interface I_IssueEntry {\n    type: E_IssueType;\n    file: string;\n    message: string;\n    position?: string;\n    rule?: string;\n}\n\nexport interface I_ThrowError {\n    message?: string;\n    status?: {\n        CODE: string | number;\n        MESSAGE: string;\n    };\n    type?: 'graphql' | 'rest';\n}\n\nexport interface I_Log extends I_LogCommon {\n    printBoxedLog: (\n        title: string,\n        issues: I_IssueEntry[],\n        color?: string,\n    ) => void;\n    /**\n     * Creates a context-aware logger that prefixes all messages with a correlation ID.\n     * Useful for distributed tracing across CyberSkill services.\n     *\n     * @param correlationId - A UUID correlation ID. If not provided, a new UUID is generated.\n     * @returns A logger with standard methods that prefix output with the correlation ID.\n     */\n    withContext: (correlationId?: string) => {\n        correlationId: string;\n        fatal: (...args: unknown[]) => void;\n        error: (...args: unknown[]) => void;\n        warn: (...args: unknown[]) => void;\n        log: (...args: unknown[]) => void;\n        info: (...args: unknown[]) => void;\n        success: (...args: unknown[]) => void;\n        debug: (...args: unknown[]) => void;\n    };\n}\n"],"mappings":";AASA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,UAAA;KACH"}

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

@@ -1,4 +1,4 @@
-import { I_Return } from '../../../typescript/index.js';
+import { I_Return } from '../../typescript/index.js';
 import { I_CatchErrorOptions, I_Log, I_ThrowError } from './log.type.js';
 /**
  * Throws a standardized error with optional status information and type specification.

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

@@ -4,20 +4,21 @@ import { getEnv as n } from "../../config/env/env.util.js";
 import { GraphQLError as r } from "graphql";
 import i from "chalk";
 import a from "consola";
+import { randomUUID as o } from "node:crypto";
 //#region src/node/log/log.util.ts
-var o = !1;
-function s() {
-	o || (o = !0, n().DEBUG || (a.level = 4));
+var s = !1;
+function c() {
+	s || (s = !0, n().DEBUG || (a.level = 4));
 }
-function c({ message: t, status: n = e.INTERNAL_SERVER_ERROR, type: i = "graphql" }) {
+function l({ message: t, status: n = e.INTERNAL_SERVER_ERROR, type: i = "graphql" }) {
 	let a = t ?? n.MESSAGE ?? "Internal server error";
 	throw i === "graphql" ? new r(a, { extensions: { code: n.CODE } }) : Error(a);
 }
-function l(e) {
+function u(e) {
 	let t = i[e];
 	return typeof t == "function" ? t : i.green;
 }
-var u = {
+var d = {
 	silent: a.silent,
 	level: a.level,
 	fatal: a.fatal,
@@ -39,16 +40,29 @@ var u = {
 		}
 		t.forEach(({ file: e, position: t, rule: r, message: o }) => {
 			let s = `${e}${t ? `:${t}` : ""}`;
-			a.log(`${i.gray("File:")} ${i.blue(s)}`), r && a.log(`   ${l(n)("Rule:")} ${r}`), a.log(`   ${l(n)("Message:")} ${o}`);
-		}), a.box(l(n)(`${e} : ${t.length}`)), a.log(i.gray("─".repeat(40)));
+			a.log(`${i.gray("File:")} ${i.blue(s)}`), r && a.log(`   ${u(n)("Rule:")} ${r}`), a.log(`   ${u(n)("Message:")} ${o}`);
+		}), a.box(u(n)(`${e} : ${t.length}`)), a.log(i.gray("─".repeat(40)));
+	},
+	withContext(e) {
+		let t = e ?? o(), n = i.gray(`[${t}]`), r = (e) => (...t) => e(n, ...t);
+		return {
+			correlationId: t,
+			fatal: r(a.fatal),
+			error: r(a.error),
+			warn: r(a.warn),
+			log: r(a.log),
+			info: r(a.info),
+			success: r(a.success),
+			debug: r(a.debug)
+		};
 	}
 };
-function d(e, n) {
+function f(e, n) {
 	return t(e, n, (e) => {
-		s(), u.error(e);
+		c(), d.error(e);
 	});
 }
 //#endregion
-export { d as catchError, u as log, c as throwError };
+export { f as catchError, d as log, l as throwError };
 
 //# sourceMappingURL=log.util.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"log.util.js","names":[],"sources":["../../../src/node/log/log.util.ts"],"sourcesContent":["import type { ChalkInstance } from 'chalk';\n\nimport chalk from 'chalk';\nimport consola from 'consola';\nimport { GraphQLError } from 'graphql';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { getEnv } from '#config/env/index.js';\nimport { RESPONSE_STATUS } from '#constant/index.js';\nimport { baseCatchError } from '#util/log/index.js';\n\nimport type { I_CatchErrorOptions, I_IssueEntry, I_Log, I_ThrowError } from './log.type.js';\n\nlet _logLevelConfigured = false;\n\n/**\n * Lazily configures the consola log level based on the DEBUG environment variable.\n * Only runs once on first invocation to avoid repeated env loading.\n */\nfunction ensureLogLevel() {\n    if (!_logLevelConfigured) {\n        _logLevelConfigured = true;\n        const env = getEnv();\n\n        if (!env.DEBUG) {\n            consola.level = 4;\n        }\n    }\n}\n\n/**\n * Throws a standardized error with optional status information and type specification.\n * This function creates and throws errors that can be either GraphQL errors (with extensions)\n * or standard JavaScript errors, depending on the specified type.\n *\n * @param options - Error configuration including message, status information, and error type.\n * @param options.message - The error message to display.\n * @param options.status - The response status information (defaults to INTERNAL_SERVER_ERROR).\n * @param options.type - The type of error to throw ('graphql' or 'rest', defaults to 'graphql').\n * @throws {GraphQLError} When type is 'graphql', throws a GraphQL error with extensions.\n * @throws {Error} When type is 'rest' or unspecified, throws a standard JavaScript error.\n */\nexport function throwError({\n    message,\n    status = RESPONSE_STATUS.INTERNAL_SERVER_ERROR,\n    type = 'graphql',\n}: I_ThrowError): never {\n    const responseMessage\n        = message ?? status.MESSAGE ?? 'Internal server error';\n\n    if (type === 'graphql') {\n        throw new GraphQLError(responseMessage, {\n            extensions: { code: status.CODE },\n        });\n    }\n\n    throw new Error(responseMessage);\n}\n\n/**\n * Gets a chalk color instance by keyword name.\n * This function safely retrieves a chalk color function by name, falling back to green\n * if the specified color is not available or invalid.\n *\n * @param color - The color keyword to get the chalk instance for.\n * @returns A chalk instance for the specified color, or green as fallback.\n */\nfunction chalkKeyword(color: string): ChalkInstance {\n    const chalkColor = chalk[color as keyof typeof chalk];\n\n    return typeof chalkColor === 'function' ? (chalkColor as ChalkInstance) : chalk.green;\n}\n\n/**\n * Enhanced logging interface that extends consola with custom functionality.\n * This object provides all standard consola logging methods plus additional features\n * like boxed log printing for structured error/warning display.\n */\nexport const log: I_Log = {\n    silent: consola.silent,\n    level: consola.level,\n    fatal: consola.fatal,\n    error: consola.error,\n    warn: consola.warn,\n    log: consola.log,\n    info: consola.info,\n    success: consola.success,\n    ready: consola.ready,\n    start: consola.start,\n    box: consola.box,\n    debug: consola.debug,\n    trace: consola.trace,\n    verbose: consola.verbose,\n    /**\n     * Prints a boxed log with structured issue information.\n     * This method displays issues (errors or warnings) in a formatted box with:\n     * - File paths and line/column positions\n     * - Rule violations (if applicable)\n     * - Error/warning messages\n     * - Color-coded output based on issue type\n     *\n     * @param title - The title to display in the box header.\n     * @param issues - An array of issue entries to display.\n     * @param color - The color to use for highlighting (defaults to 'red').\n     */\n    printBoxedLog(title: string, issues: I_IssueEntry[], color = 'red') {\n        if (!issues?.length) {\n            consola.box(chalk.green(title));\n            return;\n        }\n\n        issues.forEach(({ file, position, rule, message }) => {\n            const positionSuffix = position ? `:${position}` : '';\n            const filePath = `${file}${positionSuffix}`;\n            consola.log(`${chalk.gray('File:')} ${chalk.blue(filePath)}`);\n\n            if (rule) {\n                consola.log(`   ${chalkKeyword(color)('Rule:')} ${rule}`);\n            }\n\n            consola.log(`   ${chalkKeyword(color)('Message:')} ${message}`);\n        });\n\n        consola.box(chalkKeyword(color)(`${title} : ${issues.length}`));\n\n        consola.log(chalk.gray('─'.repeat(40)));\n    },\n};\n\n/**\n * Catches and handles errors with configurable behavior.\n * Delegates to the shared `baseCatchError` implementation, adding Node-specific\n * log-level configuration via `ensureLogLevel()` before logging.\n *\n * @param errorInput - The error to catch and handle.\n * @param options - Configuration options for error handling behavior.\n * @returns Either the specified return value or a standardized error response object.\n */\nexport function catchError<T = unknown>(errorInput: unknown, options: I_CatchErrorOptions & { returnValue: T }): T;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T>;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T> | T {\n    return baseCatchError<T>(errorInput, options, (message) => {\n        ensureLogLevel();\n        log.error(message);\n    });\n}\n"],"mappings":";;;;;;;AAcA,IAAI,IAAsB;AAM1B,SAAS,IAAiB;AACtB,CAAK,MACD,IAAsB,IACV,GAAQ,CAEX,UACL,EAAQ,QAAQ;;AAiB5B,SAAgB,EAAW,EACvB,YACA,YAAS,EAAgB,uBACzB,UAAO,aACa;CACpB,IAAM,IACA,KAAW,EAAO,WAAW;AAQnC,OANI,MAAS,YACH,IAAI,EAAa,GAAiB,EACpC,YAAY,EAAE,MAAM,EAAO,MAAM,EACpC,CAAC,GAGI,MAAM,EAAgB;;AAWpC,SAAS,EAAa,GAA8B;CAChD,IAAM,IAAa,EAAM;AAEzB,QAAO,OAAO,KAAe,aAAc,IAA+B,EAAM;;AAQpF,IAAa,IAAa;CACtB,QAAQ,EAAQ;CAChB,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,MAAM,EAAQ;CACd,KAAK,EAAQ;CACb,MAAM,EAAQ;CACd,SAAS,EAAQ;CACjB,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,KAAK,EAAQ;CACb,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,SAAS,EAAQ;CAajB,cAAc,GAAe,GAAwB,IAAQ,OAAO;AAChE,MAAI,CAAC,GAAQ,QAAQ;AACjB,KAAQ,IAAI,EAAM,MAAM,EAAM,CAAC;AAC/B;;AAiBJ,EAdA,EAAO,SAAS,EAAE,SAAM,aAAU,SAAM,iBAAc;GAElD,IAAM,IAAW,GAAG,IADG,IAAW,IAAI,MAAa;AAQnD,GANA,EAAQ,IAAI,GAAG,EAAM,KAAK,QAAQ,CAAC,GAAG,EAAM,KAAK,EAAS,GAAG,EAEzD,KACA,EAAQ,IAAI,MAAM,EAAa,EAAM,CAAC,QAAQ,CAAC,GAAG,IAAO,EAG7D,EAAQ,IAAI,MAAM,EAAa,EAAM,CAAC,WAAW,CAAC,GAAG,IAAU;IACjE,EAEF,EAAQ,IAAI,EAAa,EAAM,CAAC,GAAG,EAAM,KAAK,EAAO,SAAS,CAAC,EAE/D,EAAQ,IAAI,EAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC;;CAE9C;AAaD,SAAgB,EAAwB,GAAqB,GAAgD;AACzG,QAAO,EAAkB,GAAY,IAAU,MAAY;AAEvD,EADA,GAAgB,EAChB,EAAI,MAAM,EAAQ;GACpB"}
+{"version":3,"file":"log.util.js","names":[],"sources":["../../../src/node/log/log.util.ts"],"sourcesContent":["import type { ChalkInstance } from 'chalk';\n\nimport chalk from 'chalk';\nimport consola from 'consola';\nimport { GraphQLError } from 'graphql';\nimport { randomUUID } from 'node:crypto';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { getEnv } from '#config/env/index.js';\nimport { RESPONSE_STATUS } from '#constant/index.js';\nimport { baseCatchError } from '#util/log/index.js';\n\nimport type { I_CatchErrorOptions, I_IssueEntry, I_Log, I_ThrowError } from './log.type.js';\n\nlet _logLevelConfigured = false;\n\n/**\n * Lazily configures the consola log level based on the DEBUG environment variable.\n * Only runs once on first invocation to avoid repeated env loading.\n */\nfunction ensureLogLevel() {\n    if (!_logLevelConfigured) {\n        _logLevelConfigured = true;\n        const env = getEnv();\n\n        if (!env.DEBUG) {\n            consola.level = 4;\n        }\n    }\n}\n\n/**\n * Throws a standardized error with optional status information and type specification.\n * This function creates and throws errors that can be either GraphQL errors (with extensions)\n * or standard JavaScript errors, depending on the specified type.\n *\n * @param options - Error configuration including message, status information, and error type.\n * @param options.message - The error message to display.\n * @param options.status - The response status information (defaults to INTERNAL_SERVER_ERROR).\n * @param options.type - The type of error to throw ('graphql' or 'rest', defaults to 'graphql').\n * @throws {GraphQLError} When type is 'graphql', throws a GraphQL error with extensions.\n * @throws {Error} When type is 'rest' or unspecified, throws a standard JavaScript error.\n */\nexport function throwError({\n    message,\n    status = RESPONSE_STATUS.INTERNAL_SERVER_ERROR,\n    type = 'graphql',\n}: I_ThrowError): never {\n    const responseMessage\n        = message ?? status.MESSAGE ?? 'Internal server error';\n\n    if (type === 'graphql') {\n        throw new GraphQLError(responseMessage, {\n            extensions: { code: status.CODE },\n        });\n    }\n\n    throw new Error(responseMessage);\n}\n\n/**\n * Gets a chalk color instance by keyword name.\n * This function safely retrieves a chalk color function by name, falling back to green\n * if the specified color is not available or invalid.\n *\n * @param color - The color keyword to get the chalk instance for.\n * @returns A chalk instance for the specified color, or green as fallback.\n */\nfunction chalkKeyword(color: string): ChalkInstance {\n    const chalkColor = chalk[color as keyof typeof chalk];\n\n    return typeof chalkColor === 'function' ? (chalkColor as ChalkInstance) : chalk.green;\n}\n\n/**\n * Enhanced logging interface that extends consola with custom functionality.\n * This object provides all standard consola logging methods plus additional features\n * like boxed log printing for structured error/warning display.\n */\nexport const log: I_Log = {\n    silent: consola.silent,\n    level: consola.level,\n    fatal: consola.fatal,\n    error: consola.error,\n    warn: consola.warn,\n    log: consola.log,\n    info: consola.info,\n    success: consola.success,\n    ready: consola.ready,\n    start: consola.start,\n    box: consola.box,\n    debug: consola.debug,\n    trace: consola.trace,\n    verbose: consola.verbose,\n    /**\n     * Prints a boxed log with structured issue information.\n     * This method displays issues (errors or warnings) in a formatted box with:\n     * - File paths and line/column positions\n     * - Rule violations (if applicable)\n     * - Error/warning messages\n     * - Color-coded output based on issue type\n     *\n     * @param title - The title to display in the box header.\n     * @param issues - An array of issue entries to display.\n     * @param color - The color to use for highlighting (defaults to 'red').\n     */\n    printBoxedLog(title: string, issues: I_IssueEntry[], color = 'red') {\n        if (!issues?.length) {\n            consola.box(chalk.green(title));\n            return;\n        }\n\n        issues.forEach(({ file, position, rule, message }) => {\n            const positionSuffix = position ? `:${position}` : '';\n            const filePath = `${file}${positionSuffix}`;\n            consola.log(`${chalk.gray('File:')} ${chalk.blue(filePath)}`);\n\n            if (rule) {\n                consola.log(`   ${chalkKeyword(color)('Rule:')} ${rule}`);\n            }\n\n            consola.log(`   ${chalkKeyword(color)('Message:')} ${message}`);\n        });\n\n        consola.box(chalkKeyword(color)(`${title} : ${issues.length}`));\n\n        consola.log(chalk.gray('─'.repeat(40)));\n    },\n    /**\n     * Creates a context-aware logger that prefixes all messages with a correlation ID.\n     * Useful for distributed tracing across CyberSkill services.\n     *\n     * @param correlationId - A UUID correlation ID. If not provided, a new UUID is generated.\n     * @returns A logger object with all standard methods that prefix output with the correlation ID.\n     */\n    withContext(correlationId?: string) {\n        const id = correlationId ?? randomUUID();\n        const prefix = chalk.gray(`[${id}]`);\n\n        const withPrefix = (fn: (...args: unknown[]) => void) => {\n            return (...args: unknown[]) => fn(prefix, ...args);\n        };\n\n        return {\n            correlationId: id,\n            fatal: withPrefix(consola.fatal),\n            error: withPrefix(consola.error),\n            warn: withPrefix(consola.warn),\n            log: withPrefix(consola.log),\n            info: withPrefix(consola.info),\n            success: withPrefix(consola.success),\n            debug: withPrefix(consola.debug),\n        };\n    },\n};\n\n/**\n * Catches and handles errors with configurable behavior.\n * Delegates to the shared `baseCatchError` implementation, adding Node-specific\n * log-level configuration via `ensureLogLevel()` before logging.\n *\n * @param errorInput - The error to catch and handle.\n * @param options - Configuration options for error handling behavior.\n * @returns Either the specified return value or a standardized error response object.\n */\nexport function catchError<T = unknown>(errorInput: unknown, options: I_CatchErrorOptions & { returnValue: T }): T;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T>;\nexport function catchError<T = unknown>(errorInput: unknown, options?: I_CatchErrorOptions): I_Return<T> | T {\n    return baseCatchError<T>(errorInput, options, (message) => {\n        ensureLogLevel();\n        log.error(message);\n    });\n}\n"],"mappings":";;;;;;;;AAeA,IAAI,IAAsB;AAM1B,SAAS,IAAiB;AACtB,CAAK,MACD,IAAsB,IACV,GAAQ,CAEX,UACL,EAAQ,QAAQ;;AAiB5B,SAAgB,EAAW,EACvB,YACA,YAAS,EAAgB,uBACzB,UAAO,aACa;CACpB,IAAM,IACA,KAAW,EAAO,WAAW;AAQnC,OANI,MAAS,YACH,IAAI,EAAa,GAAiB,EACpC,YAAY,EAAE,MAAM,EAAO,MAAM,EACpC,CAAC,GAGI,MAAM,EAAgB;;AAWpC,SAAS,EAAa,GAA8B;CAChD,IAAM,IAAa,EAAM;AAEzB,QAAO,OAAO,KAAe,aAAc,IAA+B,EAAM;;AAQpF,IAAa,IAAa;CACtB,QAAQ,EAAQ;CAChB,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,MAAM,EAAQ;CACd,KAAK,EAAQ;CACb,MAAM,EAAQ;CACd,SAAS,EAAQ;CACjB,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,KAAK,EAAQ;CACb,OAAO,EAAQ;CACf,OAAO,EAAQ;CACf,SAAS,EAAQ;CAajB,cAAc,GAAe,GAAwB,IAAQ,OAAO;AAChE,MAAI,CAAC,GAAQ,QAAQ;AACjB,KAAQ,IAAI,EAAM,MAAM,EAAM,CAAC;AAC/B;;AAiBJ,EAdA,EAAO,SAAS,EAAE,SAAM,aAAU,SAAM,iBAAc;GAElD,IAAM,IAAW,GAAG,IADG,IAAW,IAAI,MAAa;AAQnD,GANA,EAAQ,IAAI,GAAG,EAAM,KAAK,QAAQ,CAAC,GAAG,EAAM,KAAK,EAAS,GAAG,EAEzD,KACA,EAAQ,IAAI,MAAM,EAAa,EAAM,CAAC,QAAQ,CAAC,GAAG,IAAO,EAG7D,EAAQ,IAAI,MAAM,EAAa,EAAM,CAAC,WAAW,CAAC,GAAG,IAAU;IACjE,EAEF,EAAQ,IAAI,EAAa,EAAM,CAAC,GAAG,EAAM,KAAK,EAAO,SAAS,CAAC,EAE/D,EAAQ,IAAI,EAAM,KAAK,IAAI,OAAO,GAAG,CAAC,CAAC;;CAS3C,YAAY,GAAwB;EAChC,IAAM,IAAK,KAAiB,GAAY,EAClC,IAAS,EAAM,KAAK,IAAI,EAAG,GAAG,EAE9B,KAAc,OACR,GAAG,MAAoB,EAAG,GAAQ,GAAG,EAAK;AAGtD,SAAO;GACH,eAAe;GACf,OAAO,EAAW,EAAQ,MAAM;GAChC,OAAO,EAAW,EAAQ,MAAM;GAChC,MAAM,EAAW,EAAQ,KAAK;GAC9B,KAAK,EAAW,EAAQ,IAAI;GAC5B,MAAM,EAAW,EAAQ,KAAK;GAC9B,SAAS,EAAW,EAAQ,QAAQ;GACpC,OAAO,EAAW,EAAQ,MAAM;GACnC;;CAER;AAaD,SAAgB,EAAwB,GAAqB,GAAgD;AACzG,QAAO,EAAkB,GAAY,IAAU,MAAY;AAEvD,EADA,GAAgB,EAChB,EAAI,MAAM,EAAQ;GACpB"}

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

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

package/dist/node/mongo/index.js

@@ -1,8 +1,7 @@
-import { MONGO_MIGRATE_OPTIONS as e, MONGO_SLUG_MAX_ATTEMPTS as t } from "./mongo.constant.js";
-import { convertEnumToModelName as n, mongo as r } from "./mongo.util.js";
-import { applyNestedPopulate as i } from "./mongo.populate.js";
-import { filterDynamicVirtualsFromPopulate as a, isMongooseDoc as o, populateDynamicVirtuals as s, remapDynamicPopulate as c } from "./mongo.dynamic-populate.js";
-import { MongooseController as l } from "./mongo.controller.mongoose.js";
-import { MongoController as u } from "./mongo.controller.native.js";
-import { C_Collection as d, C_Db as f, C_Document as p, C_Model as m } from "./mongo.type.js";
-export { d as C_Collection, f as C_Db, p as C_Document, m as C_Model, e as MONGO_MIGRATE_OPTIONS, t as MONGO_SLUG_MAX_ATTEMPTS, u as MongoController, l as MongooseController, i as applyNestedPopulate, n as convertEnumToModelName, a as filterDynamicVirtualsFromPopulate, o as isMongooseDoc, r as mongo, s as populateDynamicVirtuals, c as remapDynamicPopulate };
+import { MONGO_MAX_TIME_MS as e, MONGO_MIGRATE_OPTIONS as t, MONGO_SLUG_MAX_ATTEMPTS as n } from "./mongo.constant.js";
+import { convertEnumToModelName as r, mongo as i } from "./mongo.util.js";
+import { applyNestedPopulate as a } from "./mongo.populate.js";
+import { filterDynamicVirtualsFromPopulate as o, isMongooseDoc as s, populateDynamicVirtuals as c, remapDynamicPopulate as l } from "./mongo.dynamic-populate.js";
+import { MongooseController as u } from "./mongo.controller.mongoose.js";
+import { MongoController as d, createMongoController as f } from "./mongo.controller.native.js";
+export { e as MONGO_MAX_TIME_MS, t as MONGO_MIGRATE_OPTIONS, n as MONGO_SLUG_MAX_ATTEMPTS, d as MongoController, u as MongooseController, a as applyNestedPopulate, r as convertEnumToModelName, f as createMongoController, o as filterDynamicVirtualsFromPopulate, s as isMongooseDoc, i as mongo, c as populateDynamicVirtuals, l as remapDynamicPopulate };

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

@@ -10,3 +10,8 @@ export declare const MONGO_MIGRATE_OPTIONS = "MONGO_MIGRATE_OPTIONS";
  * before giving up and returning a fallback slug.
  */
 export declare const MONGO_SLUG_MAX_ATTEMPTS = 100;
+/**
+ * Default maxTimeMS for MongoDB queries.
+ * This constant defines the default maximum execution time for MongoDB queries.
+ */
+export declare const MONGO_MAX_TIME_MS = 30000;

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

@@ -1,6 +1,6 @@
 //#region src/node/mongo/mongo.constant.ts
-var e = "MONGO_MIGRATE_OPTIONS", t = 100;
+var e = "MONGO_MIGRATE_OPTIONS", t = 100, n = 3e4;
 //#endregion
-export { e as MONGO_MIGRATE_OPTIONS, t as MONGO_SLUG_MAX_ATTEMPTS };
+export { n as MONGO_MAX_TIME_MS, e as MONGO_MIGRATE_OPTIONS, t as MONGO_SLUG_MAX_ATTEMPTS };
 
 //# sourceMappingURL=mongo.constant.js.map

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

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

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

@@ -1,4 +1,4 @@
-import { I_Return } from '../../../typescript/index.js';
+import { I_Return } from '../../typescript/index.js';
 /**
  * Shared helper functions for MongoDB controllers.
  *

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

@@ -1,4 +1,4 @@
-import { I_Return } from '../../../typescript/index.js';
+import { I_Return } from '../../typescript/index.js';
 import { C_Document, I_DeleteOptionsExtended, I_ExtendedModel, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Input_Populate, T_InsertManyOptions, T_PaginateResult, T_PipelineStage, T_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult } from './mongo.type.js';
 /**
  * Mongoose controller for database operations with advanced features.
@@ -8,15 +8,18 @@ import { C_Document, I_DeleteOptionsExtended, I_ExtendedModel, I_Input_CheckSlug
 export declare class MongooseController<T extends Partial<C_Document>> {
     private model;
     private defaultLimit;
+    private defaultProjection;
     /**
      * Creates a new Mongoose controller instance.
      *
      * @param model - The Mongoose model to operate on.
      * @param options - Optional configuration for the controller.
      * @param options.defaultLimit - Maximum documents returned by findAll when no limit is specified (default: 1,000).
+     * @param options.defaultProjection - Default projection to apply to findOne and findAll queries.
      */
     constructor(model: I_ExtendedModel<T>, options?: {
         defaultLimit?: number;
+        defaultProjection?: T_ProjectionType<T>;
     });
     /**
      * Gets the model name for logging and error messages.

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

@@ -3,16 +3,18 @@ import { RESPONSE_STATUS as t } from "../../constant/response-status.js";
 import { normalizeMongoFilter as n } from "../../util/object/object.util.js";
 import { generateRandomString as r, generateShortId as i, generateSlug as a } from "../../util/string/string.util.js";
 import { catchError as o, log as s } from "../log/log.util.js";
-import "./mongo.constant.js";
-import { filterDynamicVirtualsFromPopulate as c, populateDynamicVirtuals as l } from "./mongo.dynamic-populate.js";
+import { MONGO_MAX_TIME_MS as c } from "./mongo.constant.js";
+import { wrapNotFound as l } from "./mongo.controller.helpers.js";
+import { filterDynamicVirtualsFromPopulate as u, populateDynamicVirtuals as d } from "./mongo.dynamic-populate.js";
 //#region src/node/mongo/mongo.controller.mongoose.ts
-function u(e) {
+function f(e) {
 	return e?.toObject?.() ?? e;
 }
-var d = class {
+var p = class {
 	defaultLimit;
+	defaultProjection;
 	constructor(e, t) {
-		this.model = e, this.defaultLimit = t?.defaultLimit ?? 1e3;
+		this.model = e, this.defaultLimit = t?.defaultLimit ?? 1e3, this.defaultProjection = t?.defaultProjection ?? {};
 	}
 	getModelName() {
 		return this.model.modelName;
@@ -33,36 +35,32 @@ var d = class {
 	}
 	async populateDynamic(e, t) {
 		let n = this.getDynamicVirtuals();
-		return n && n.length > 0 && e.length > 0 ? await l(this.model.base, e, n, t, void 0, this.model) : e;
+		return n && n.length > 0 && e.length > 0 ? await d(this.model.base, e, n, t, void 0, this.model) : e;
 	}
-	async findOne(e = {}, r = {}, i = {}, a) {
+	async findOne(e = {}, t = {}, r = {}, i) {
 		try {
-			let o = n(e), s = this.model.findOne(o, r, i).maxTimeMS(3e4).lean(), l = c(a, this.getDynamicVirtuals());
-			l && s.populate(l);
-			let d = await s.exec();
+			let a = n(e), o = this.model.findOne(a, Object.keys(t).length > 0 ? t : Object.keys(this.defaultProjection).length > 0 ? this.defaultProjection : t, r).maxTimeMS(c).lean(), s = u(i, this.getDynamicVirtuals());
+			s && o.populate(s);
+			let d = await o.exec();
 			return d ? {
 				success: !0,
-				result: u(await this.populateDynamicVirtualsForDocument(d, a))
-			} : {
-				success: !1,
-				message: `No ${this.getModelName()} found.`,
-				code: t.NOT_FOUND.CODE
-			};
+				result: f(await this.populateDynamicVirtualsForDocument(d, i))
+			} : l(this.getModelName());
 		} catch (e) {
 			return o(e);
 		}
 	}
 	async findAll(e = {}, t = {}, r = {}, i) {
 		try {
-			let a = n(e), o = this.model.find(a, t, r).maxTimeMS(3e4).lean();
+			let a = n(e), o = this.model.find(a, Object.keys(t).length > 0 ? t : Object.keys(this.defaultProjection).length > 0 ? this.defaultProjection : t, r).maxTimeMS(c).lean();
 			r.limit || o.limit(this.defaultLimit);
-			let l = c(i, this.getDynamicVirtuals());
+			let l = u(i, this.getDynamicVirtuals());
 			l && o.populate(l);
-			let d = await o.exec(), f = await this.populateDynamicVirtualsForDocuments(d, i), p = f.length === this.defaultLimit && !r.limit;
-			return p && s.warn(`[${this.getModelName()}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
+			let d = await o.exec(), p = await this.populateDynamicVirtualsForDocuments(d, i), m = p.length === this.defaultLimit && !r.limit;
+			return m && s.warn(`[${this.getModelName()}] findAll returned exactly ${this.defaultLimit} documents (the default limit). Results may be truncated. Consider using pagination or setting an explicit limit.`), {
 				success: !0,
-				result: f.map((e) => u(e)),
-				truncated: p
+				result: p.map((e) => f(e)),
+				truncated: m
 			};
 		} catch (e) {
 			return o(e);
@@ -71,7 +69,7 @@ var d = class {
 	async findPaging(e = {}, t = {}) {
 		try {
 			let r = n(e), i = this.getDynamicVirtuals(), a = { ...t };
-			t.populate && (a.populate = c(t.populate, i));
+			t.populate && (a.populate = u(t.populate, i));
 			let o = await this.model.paginate(r, a);
 			if (i && i.length > 0) {
 				let e = await this.populateDynamicVirtualsForDocuments(o.docs, t.populate);
@@ -79,7 +77,7 @@ var d = class {
 					success: !0,
 					result: {
 						...o,
-						docs: e.map((e) => u(e))
+						docs: e.map((e) => f(e))
 					}
 				};
 			}
@@ -87,7 +85,7 @@ var d = class {
 				success: !0,
 				result: {
 					...o,
-					docs: o.docs.map((e) => u(e))
+					docs: o.docs.map((e) => f(e))
 				}
 			};
 		} catch (e) {
@@ -97,13 +95,13 @@ var d = class {
 	async findPagingAggregate(e, t = {}) {
 		try {
 			let n = this.getDynamicVirtuals(), r = { ...t };
-			t.populate && (r.populate = c(t.populate, n));
+			t.populate && (r.populate = u(t.populate, n));
 			let i = await this.model.aggregatePaginate(this.model.aggregate(e), r), a = await this.populateDynamicVirtualsForDocuments(i.docs, t.populate);
 			return {
 				success: !0,
 				result: {
 					...i,
-					docs: a.map((e) => u(e))
+					docs: a.map((e) => f(e))
 				}
 			};
 		} catch (e) {
@@ -142,20 +140,16 @@ var d = class {
 			return o(e);
 		}
 	}
-	async updateOne(e = {}, r = {}, i = {}) {
+	async updateOne(e = {}, t = {}, r = {}) {
 		try {
-			let a = n(e), o = await this.model.findOneAndUpdate(a, r, {
+			let i = n(e), a = await this.model.findOneAndUpdate(i, t, {
 				new: !0,
-				...i
+				...r
 			}).exec();
-			return o ? {
+			return a ? {
 				success: !0,
-				result: o?.toObject?.() ?? o
-			} : {
-				success: !1,
-				message: `Failed to update ${this.getModelName()}.`,
-				code: t.NOT_FOUND.CODE
-			};
+				result: a?.toObject?.() ?? a
+			} : l(this.getModelName());
 		} catch (e) {
 			return o(e);
 		}
@@ -171,31 +165,23 @@ var d = class {
 			return o(e);
 		}
 	}
-	async deleteOne(e = {}, r = {}) {
+	async deleteOne(e = {}, t = {}) {
 		try {
-			let i = n(e), a = await this.model.findOneAndDelete(i, r).exec();
-			return a ? {
+			let r = n(e), i = await this.model.findOneAndDelete(r, t).exec();
+			return i ? {
 				success: !0,
-				result: a?.toObject?.() ?? a
-			} : {
-				success: !1,
-				message: `No ${this.getModelName()} found to delete.`,
-				code: t.NOT_FOUND.CODE
-			};
+				result: i?.toObject?.() ?? i
+			} : l(this.getModelName());
 		} catch (e) {
 			return o(e);
 		}
 	}
-	async deleteMany(e = {}, r = {}) {
+	async deleteMany(e = {}, t = {}) {
 		try {
-			let i = n(e), a = await this.model.deleteMany(i, r).exec();
-			return a.deletedCount === 0 ? {
-				success: !1,
-				message: "No documents found to delete.",
-				code: t.NOT_FOUND.CODE
-			} : {
+			let r = n(e), i = await this.model.deleteMany(r, t).exec();
+			return i.deletedCount === 0 ? l("documents") : {
 				success: !0,
-				result: a
+				result: i
 			};
 		} catch (e) {
 			return o(e);
@@ -326,6 +312,6 @@ var d = class {
 	}
 };
 //#endregion
-export { d as MongooseController };
+export { p as MongooseController };
 
 //# sourceMappingURL=mongo.controller.mongoose.js.map