@cyberskill/shared 3.12.0 → 3.14.0

package/dist/react/storage/storage.util.js

@@ -1,17 +1,21 @@
 import { catchError as e } from "../log/log.util.js";
+import { createTtlEnvelope as t, isExpiredEnvelope as n, isTtlEnvelope as r } from "../../util/storage/storage-envelope.js";
 //#region src/react/storage/storage.util.ts
-var t = {
+var i = {
 	async get(t) {
 		try {
 			let e = localStorage.getItem(t);
-			return e === null ? null : JSON.parse(e);
+			if (e === null) return null;
+			let i = JSON.parse(e);
+			return r(i) ? n(i) ? (localStorage.removeItem(t), null) : i.value : i;
 		} catch (t) {
 			return e(t, { returnValue: null });
 		}
 	},
-	async set(t, n) {
+	async set(n, r, i) {
 		try {
-			localStorage.setItem(t, JSON.stringify(n));
+			let e = r;
+			i?.ttlMs && (e = t(r, i.ttlMs)), localStorage.setItem(n, JSON.stringify(e));
 		} catch (t) {
 			e(t);
 		}
@@ -34,9 +38,30 @@ var t = {
 		} catch (t) {
 			return e(t, { returnValue: [] });
 		}
+	},
+	async has(t) {
+		try {
+			let e = localStorage.getItem(t);
+			if (e === null) return !1;
+			let i = JSON.parse(e);
+			return r(i) && n(i) ? (localStorage.removeItem(t), !1) : !0;
+		} catch (t) {
+			return e(t, { returnValue: !1 });
+		}
+	},
+	async clear() {
+		try {
+			localStorage.clear();
+		} catch (t) {
+			e(t);
+		}
+	},
+	async getOrSet(e, t, n) {
+		let r = await this.get(e);
+		return r === null && (r = await t(), await this.set(e, r, n)), r;
 	}
 };
 //#endregion
-export { t as storage };
+export { i as storage };
 
 //# sourceMappingURL=storage.util.js.map

package/dist/react/storage/storage.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/react/storage/storage.util.ts"],"sourcesContent":["import { catchError } from '../log/index.js';\n\n/**\n * Browser storage utility object using native localStorage.\n * This object provides a unified interface for browser storage operations\n * with comprehensive error handling and type safety.\n * Values are stored as JSON strings for consistent serialization.\n */\nexport const storage = {\n    /**\n     * Retrieves a value from browser storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs during retrieval.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        try {\n            const raw = localStorage.getItem(key);\n\n            if (raw === null) {\n                return null;\n            }\n\n            return JSON.parse(raw) as T;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in browser storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized to JSON.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized to JSON).\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T): Promise<void> {\n        try {\n            localStorage.setItem(key, JSON.stringify(value));\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Removes a value from browser storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     * If the key doesn't exist, the operation completes successfully without error.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            localStorage.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs during retrieval.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const keys: string[] = [];\n\n            for (let i = 0; i < localStorage.length; i++) {\n                const key = localStorage.key(i);\n\n                if (key !== null) {\n                    keys.push(key);\n                }\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n};\n"],"mappings":";;AAQA,IAAa,IAAU;CASnB,MAAM,IAAiB,GAAgC;AACnD,MAAI;GACA,IAAM,IAAM,aAAa,QAAQ,EAAI;AAMrC,UAJI,MAAQ,OACD,OAGJ,KAAK,MAAM,EAAI;WAEnB,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAYvD,MAAM,IAAiB,GAAa,GAAyB;AACzD,MAAI;AACA,gBAAa,QAAQ,GAAK,KAAK,UAAU,EAAM,CAAC;WAE7C,GAAO;AACV,KAAW,EAAM;;;CAWzB,MAAM,OAAO,GAA4B;AACrC,MAAI;AACA,gBAAa,WAAW,EAAI;WAEzB,GAAO;AACV,KAAW,EAAM;;;CAUzB,MAAM,OAA0B;AAC5B,MAAI;GACA,IAAM,IAAiB,EAAE;AAEzB,QAAK,IAAI,IAAI,GAAG,IAAI,aAAa,QAAQ,KAAK;IAC1C,IAAM,IAAM,aAAa,IAAI,EAAE;AAE/B,IAAI,MAAQ,QACR,EAAK,KAAK,EAAI;;AAItB,UAAO;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,EAAE,EAAE,CAAC;;;CAGxD"}
+{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/react/storage/storage.util.ts"],"sourcesContent":["import { createTtlEnvelope, isExpiredEnvelope, isTtlEnvelope } from '../../util/storage/storage-envelope.js';\nimport { catchError } from '../log/index.js';\n\n/**\n * Browser storage utility object using native localStorage.\n * This object provides a unified interface for browser storage operations\n * with comprehensive error handling and type safety.\n * Values are stored as JSON strings for consistent serialization.\n */\nexport const storage = {\n    /**\n     * Retrieves a value from browser storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs during retrieval.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        try {\n            const raw = localStorage.getItem(key);\n\n            if (raw === null) {\n                return null;\n            }\n\n            const obj = JSON.parse(raw);\n\n            if (isTtlEnvelope<T>(obj)) {\n                if (isExpiredEnvelope(obj)) {\n                    localStorage.removeItem(key);\n\n                    return null;\n                }\n\n                return obj.value;\n            }\n\n            return obj as T;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in browser storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized to JSON.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized to JSON).\n     * @param options - Optional settings.\n     * @param options.ttlMs - The time-to-live in milliseconds.\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T, options?: { ttlMs?: number }): Promise<void> {\n        try {\n            let payloadToStore: unknown = value;\n\n            if (options?.ttlMs) {\n                payloadToStore = createTtlEnvelope(value, options.ttlMs);\n            }\n\n            localStorage.setItem(key, JSON.stringify(payloadToStore));\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Removes a value from browser storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     * If the key doesn't exist, the operation completes successfully without error.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            localStorage.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs during retrieval.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const keys: string[] = [];\n\n            for (let i = 0; i < localStorage.length; i++) {\n                const key = localStorage.key(i);\n\n                if (key !== null) {\n                    keys.push(key);\n                }\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n    /**\n     * Checks if a key exists in browser storage.\n     * This method efficiently checks for key existence without deserializing the value.\n     * It also respects TTL — returns false if the key exists but has expired.\n     *\n     * @param key - The unique identifier to check.\n     * @returns A promise that resolves to true if the key exists and has not expired.\n     */\n    async has(key: string): Promise<boolean> {\n        try {\n            const raw = localStorage.getItem(key);\n\n            if (raw === null) {\n                return false;\n            }\n\n            const obj = JSON.parse(raw);\n\n            if (isTtlEnvelope<unknown>(obj)) {\n                if (isExpiredEnvelope(obj)) {\n                    localStorage.removeItem(key);\n\n                    return false;\n                }\n            }\n\n            return true;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: false });\n        }\n    },\n    /**\n     * Clears all values from browser storage.\n     * This method permanently removes all stored data.\n     *\n     * @returns A promise that resolves when the clear operation is complete.\n     */\n    async clear(): Promise<void> {\n        try {\n            localStorage.clear();\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves a value from browser storage, or creates and stores it if it doesn't exist.\n     * This method combines check, creation, and storage into a single convenient operation.\n     *\n     * @param key - The unique identifier for the value.\n     * @param factory - A function (sync or async) that generates the value if it's missing or expired.\n     * @param options - Optional storage options.\n     * @param options.ttlMs - The time-to-live in milliseconds.\n     * @returns A promise that resolves to the retrieved or newly created value.\n     */\n    async getOrSet<T = unknown>(key: string, factory: () => T | Promise<T>, options?: { ttlMs?: number }): Promise<T> {\n        let value = await this.get<T>(key);\n\n        if (value === null) {\n            value = await factory();\n            await this.set(key, value, options);\n        }\n\n        return value;\n    },\n};\n"],"mappings":";;;AASA,IAAa,IAAU;CASnB,MAAM,IAAiB,GAAgC;AACnD,MAAI;GACA,IAAM,IAAM,aAAa,QAAQ,EAAI;AAErC,OAAI,MAAQ,KACR,QAAO;GAGX,IAAM,IAAM,KAAK,MAAM,EAAI;AAY3B,UAVI,EAAiB,EAAI,GACjB,EAAkB,EAAI,IACtB,aAAa,WAAW,EAAI,EAErB,QAGJ,EAAI,QAGR;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAcvD,MAAM,IAAiB,GAAa,GAAU,GAA6C;AACvF,MAAI;GACA,IAAI,IAA0B;AAM9B,GAJI,GAAS,UACT,IAAiB,EAAkB,GAAO,EAAQ,MAAM,GAG5D,aAAa,QAAQ,GAAK,KAAK,UAAU,EAAe,CAAC;WAEtD,GAAO;AACV,KAAW,EAAM;;;CAWzB,MAAM,OAAO,GAA4B;AACrC,MAAI;AACA,gBAAa,WAAW,EAAI;WAEzB,GAAO;AACV,KAAW,EAAM;;;CAUzB,MAAM,OAA0B;AAC5B,MAAI;GACA,IAAM,IAAiB,EAAE;AAEzB,QAAK,IAAI,IAAI,GAAG,IAAI,aAAa,QAAQ,KAAK;IAC1C,IAAM,IAAM,aAAa,IAAI,EAAE;AAE/B,IAAI,MAAQ,QACR,EAAK,KAAK,EAAI;;AAItB,UAAO;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,EAAE,EAAE,CAAC;;;CAWrD,MAAM,IAAI,GAA+B;AACrC,MAAI;GACA,IAAM,IAAM,aAAa,QAAQ,EAAI;AAErC,OAAI,MAAQ,KACR,QAAO;GAGX,IAAM,IAAM,KAAK,MAAM,EAAI;AAU3B,UARI,EAAuB,EAAI,IACvB,EAAkB,EAAI,IACtB,aAAa,WAAW,EAAI,EAErB,MAIR;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,IAAO,CAAC;;;CASxD,MAAM,QAAuB;AACzB,MAAI;AACA,gBAAa,OAAO;WAEjB,GAAO;AACV,KAAW,EAAM;;;CAazB,MAAM,SAAsB,GAAa,GAA+B,GAA0C;EAC9G,IAAI,IAAQ,MAAM,KAAK,IAAO,EAAI;AAOlC,SALI,MAAU,SACV,IAAQ,MAAM,GAAS,EACvB,MAAM,KAAK,IAAI,GAAK,GAAO,EAAQ,GAGhC;;CAEd"}

package/dist/react/toast/index.d.ts

@@ -1 +1 @@
-export {}
+export { toast, Toaster } from 'react-hot-toast';

package/dist/react/userback/index.d.ts

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

package/dist/react/userback/userback.component.js.map

@@ -1 +1 @@
-{"version":3,"file":"userback.component.js","names":[],"sources":["../../../src/react/userback/userback.component.tsx"],"sourcesContent":["import UserbackWidget from '@userback/widget';\nimport { useEffect } from 'react';\n\nimport type { I_UserBackProps } from './userback.type.js';\n\n/**\n * Userback feedback widget component for collecting user feedback.\n * This component integrates the Userback feedback widget into React applications,\n * providing a customizable feedback collection interface for users to submit\n * bug reports, feature requests, and general feedback.\n *\n * Features:\n * - Userback widget integration\n * - Customizable feedback collection\n * - Automatic widget initialization\n * - Token-based configuration\n * - Responsive design support\n *\n * @param props - Component props containing token and options.\n * @param props.token - The Userback token for widget authentication.\n * @param props.options - Optional configuration options for the Userback widget.\n * @returns A React component that renders the Userback feedback widget.\n */\nexport function Userback({ token, options }: I_UserBackProps) {\n    useEffect(() => {\n        if (!token) {\n            return;\n        }\n\n        let observer: MutationObserver;\n\n        const loadUserback = async () => {\n            const { hide, ...rest } = options || {};\n\n            await UserbackWidget(token, rest);\n\n            if (hide && hide.length > 0) {\n                hide.forEach((selector: string) => {\n                    document.querySelectorAll(selector).forEach(el => el.remove());\n                });\n            }\n\n            observer = new MutationObserver(() => {\n                if (hide && hide.length > 0) {\n                    hide.forEach((selector: string) => {\n                        document.querySelectorAll(selector).forEach(el => el.remove());\n                    });\n                }\n            });\n\n            observer.observe(document.body, {\n                childList: true,\n                subtree: true,\n            });\n        };\n\n        loadUserback();\n\n        return () => {\n            observer?.disconnect();\n        };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- options is intentionally excluded to prevent infinite re-renders (object ref changes each render)\n    }, [token]);\n\n    return null;\n}\n"],"mappings":";;;AAuBA,SAAgB,EAAS,EAAE,UAAO,cAA4B;AAyC1D,QAxCA,QAAgB;AACZ,MAAI,CAAC,EACD;EAGJ,IAAI;AA6BJ,UA3BqB,YAAY;GAC7B,IAAM,EAAE,SAAM,GAAG,MAAS,KAAW,EAAE;AAkBvC,GAhBA,MAAM,EAAe,GAAO,EAAK,EAE7B,KAAQ,EAAK,SAAS,KACtB,EAAK,SAAS,MAAqB;AAC/B,aAAS,iBAAiB,EAAS,CAAC,SAAQ,MAAM,EAAG,QAAQ,CAAC;KAChE,EAGN,IAAW,IAAI,uBAAuB;AAClC,IAAI,KAAQ,EAAK,SAAS,KACtB,EAAK,SAAS,MAAqB;AAC/B,cAAS,iBAAiB,EAAS,CAAC,SAAQ,MAAM,EAAG,QAAQ,CAAC;MAChE;KAER,EAEF,EAAS,QAAQ,SAAS,MAAM;IAC5B,WAAW;IACX,SAAS;IACZ,CAAC;MAGQ,QAED;AACT,MAAU,YAAY;;IAG3B,CAAC,EAAM,CAAC,EAEJ"}
+{"version":3,"file":"userback.component.js","names":[],"sources":["../../../src/react/userback/userback.component.tsx"],"sourcesContent":["import UserbackWidget from '@userback/widget';\nimport { useEffect } from 'react';\n\nimport type { I_UserBackProps } from './userback.type.js';\n\n/**\n * Userback feedback widget component for collecting user feedback.\n * This component integrates the Userback feedback widget into React applications,\n * providing a customizable feedback collection interface for users to submit\n * bug reports, feature requests, and general feedback.\n *\n * Features:\n * - Userback widget integration\n * - Customizable feedback collection\n * - Automatic widget initialization\n * - Token-based configuration\n * - Responsive design support\n *\n * @param props - Component props containing token and options.\n * @param props.token - The Userback token for widget authentication.\n * @param props.options - Optional configuration options for the Userback widget.\n * @returns A React component that renders the Userback feedback widget.\n */\nexport function Userback({ token, options }: I_UserBackProps) {\n    useEffect(() => {\n        if (!token) {\n            return;\n        }\n\n        let observer: MutationObserver;\n\n        const loadUserback = async () => {\n            const { hide, ...rest } = options || {};\n\n            await UserbackWidget(token, rest);\n\n            if (hide && hide.length > 0) {\n                hide.forEach((selector: string) => {\n                    document.querySelectorAll(selector).forEach(el => el.remove());\n                });\n            }\n\n            observer = new MutationObserver(() => {\n                if (hide && hide.length > 0) {\n                    hide.forEach((selector: string) => {\n                        document.querySelectorAll(selector).forEach(el => el.remove());\n                    });\n                }\n            });\n\n            observer.observe(document.body, {\n                childList: true,\n                subtree: true,\n            });\n        };\n\n        loadUserback();\n\n        return () => {\n            observer?.disconnect();\n        };\n        // eslint-disable-next-line react/exhaustive-deps -- intended to only load Userback on token change\n    }, [token]);\n\n    return null;\n}\n"],"mappings":";;;AAuBA,SAAgB,EAAS,EAAE,UAAO,cAA4B;AAyC1D,QAxCA,QAAgB;AACZ,MAAI,CAAC,EACD;EAGJ,IAAI;AA6BJ,UA3BqB,YAAY;GAC7B,IAAM,EAAE,SAAM,GAAG,MAAS,KAAW,EAAE;AAkBvC,GAhBA,MAAM,EAAe,GAAO,EAAK,EAE7B,KAAQ,EAAK,SAAS,KACtB,EAAK,SAAS,MAAqB;AAC/B,aAAS,iBAAiB,EAAS,CAAC,SAAQ,MAAM,EAAG,QAAQ,CAAC;KAChE,EAGN,IAAW,IAAI,uBAAuB;AAClC,IAAI,KAAQ,EAAK,SAAS,KACtB,EAAK,SAAS,MAAqB;AAC/B,cAAS,iBAAiB,EAAS,CAAC,SAAQ,MAAM,EAAG,QAAQ,CAAC;MAChE;KAER,EAEF,EAAS,QAAQ,SAAS,MAAM;IAC5B,WAAW;IACX,SAAS;IACZ,CAAC;MAGQ,QAED;AACT,MAAU,YAAY;;IAG3B,CAAC,EAAM,CAAC,EAEJ"}

package/dist/{src/typescript → typescript}/common.type.d.ts

@@ -85,6 +85,10 @@ export declare function isSuccess<T, E = unknown>(result: I_Return<T, E>): resul
  * @throws {Error} When the result is a failure.
  */
 export declare function unwrapResult<T, E = unknown>(result: I_Return<T, E>): T & E;
+/**
+ * Alias for `unwrapResult` to improve discoverability.
+ */
+export declare const unwrapOrThrow: typeof unwrapResult;
 export declare enum E_Environment {
     PRODUCTION = "production",
     STAGING = "staging",

package/dist/typescript/common.type.js

@@ -6,10 +6,10 @@ function t(e) {
 	if (!e.success) throw Error(e.message);
 	return e.result;
 }
-var n = /* @__PURE__ */ function(e) {
+var n = t, r = /* @__PURE__ */ function(e) {
 	return e.PRODUCTION = "production", e.STAGING = "staging", e.DEVELOPMENT = "development", e;
 }({});
 //#endregion
-export { n as E_Environment, e as isSuccess, t as unwrapResult };
+export { r as E_Environment, e as isSuccess, n as unwrapOrThrow, t as unwrapResult };
 
 //# sourceMappingURL=common.type.js.map

package/dist/typescript/common.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.type.js","names":[],"sources":["../../src/typescript/common.type.ts"],"sourcesContent":["import type consola from 'consola';\n\n/**\n * Generic object type with string keys and values of type T (defaults to unknown).\n */\nexport type T_Object<T = unknown> = Record<string, T>;\n\n/**\n * Logging interface for browser and Node.js environments, compatible with consola.\n */\nexport interface I_Log {\n    silent: typeof consola['silent'];\n    level: typeof consola['level'];\n    fatal: typeof consola['fatal'];\n    error: typeof consola['error'];\n    warn: typeof consola['warn'];\n    log: typeof consola['log'];\n    info: typeof consola['info'];\n    success: typeof consola['success'];\n    ready: typeof consola['ready'];\n    start: typeof consola['start'];\n    box: typeof consola['box'];\n    debug: typeof consola['debug'];\n    trace: typeof consola['trace'];\n    verbose: typeof consola['verbose'];\n}\n\n/**\n * Base interface for return types with common properties.\n */\nexport interface I_ReturnBase {\n    success: boolean;\n    message?: string;\n    code?: number | string;\n}\n\n/**\n * Success return type with result data.\n * @template T - The main result type\n * @template E - Additional properties to merge with the result (defaults to unknown)\n */\nexport interface I_ReturnSuccess<T, E = unknown> extends I_ReturnBase {\n    success: true;\n    result: T & E;\n    /** True when results were limited by a default cap and may not include all matching documents. */\n    truncated?: boolean;\n}\n\n/**\n * Failure return type with error information.\n */\nexport interface I_ReturnFailure extends I_ReturnBase {\n    success: false;\n    message: string;\n    code: number | string;\n}\n\n/**\n * Discriminated union type for function return values.\n * Provides type-safe handling of success and failure cases.\n *\n * @template T - The success result type (defaults to void)\n * @template E - Additional properties to merge with the result (defaults to unknown)\n *\n * @example\n * ```typescript\n * function fetchUser(id: string): I_Return<User> {\n *   try {\n *     const user = await getUser(id);\n *     return { success: true, result: user };\n *   } catch (error) {\n *     return { success: false, message: error.message, code: 'USER_NOT_FOUND' };\n *   }\n * }\n * ```\n */\nexport type I_Return<T = void, E = unknown> = I_ReturnSuccess<T, E> | I_ReturnFailure;\n\n/**\n * Type guard that narrows an `I_Return` to `I_ReturnSuccess`.\n *\n * @param result - The result to check.\n * @returns True if the result is a success.\n */\nexport function isSuccess<T, E = unknown>(result: I_Return<T, E>): result is I_ReturnSuccess<T, E> {\n    return result.success;\n}\n\n/**\n * Unwraps a successful `I_Return`, throwing an error for failure cases.\n * Useful when a failure is unexpected and should abort execution.\n *\n * @param result - The result to unwrap.\n * @returns The success result value.\n * @throws {Error} When the result is a failure.\n */\nexport function unwrapResult<T, E = unknown>(result: I_Return<T, E>): T & E {\n    if (!result.success) {\n        throw new Error(result.message);\n    }\n\n    return result.result;\n}\n\nexport enum E_Environment {\n    PRODUCTION = 'production',\n    STAGING = 'staging',\n    DEVELOPMENT = 'development',\n}\n"],"mappings":";AAoFA,SAAgB,EAA0B,GAAyD;AAC/F,QAAO,EAAO;;AAWlB,SAAgB,EAA6B,GAA+B;AACxE,KAAI,CAAC,EAAO,QACR,OAAU,MAAM,EAAO,QAAQ;AAGnC,QAAO,EAAO;;AAGlB,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,aAAA,cACA,EAAA,UAAA,WACA,EAAA,cAAA;KACH"}
+{"version":3,"file":"common.type.js","names":[],"sources":["../../src/typescript/common.type.ts"],"sourcesContent":["import type consola from 'consola';\n\n/**\n * Generic object type with string keys and values of type T (defaults to unknown).\n */\nexport type T_Object<T = unknown> = Record<string, T>;\n\n/**\n * Logging interface for browser and Node.js environments, compatible with consola.\n */\nexport interface I_Log {\n    silent: typeof consola['silent'];\n    level: typeof consola['level'];\n    fatal: typeof consola['fatal'];\n    error: typeof consola['error'];\n    warn: typeof consola['warn'];\n    log: typeof consola['log'];\n    info: typeof consola['info'];\n    success: typeof consola['success'];\n    ready: typeof consola['ready'];\n    start: typeof consola['start'];\n    box: typeof consola['box'];\n    debug: typeof consola['debug'];\n    trace: typeof consola['trace'];\n    verbose: typeof consola['verbose'];\n}\n\n/**\n * Base interface for return types with common properties.\n */\nexport interface I_ReturnBase {\n    success: boolean;\n    message?: string;\n    code?: number | string;\n}\n\n/**\n * Success return type with result data.\n * @template T - The main result type\n * @template E - Additional properties to merge with the result (defaults to unknown)\n */\nexport interface I_ReturnSuccess<T, E = unknown> extends I_ReturnBase {\n    success: true;\n    result: T & E;\n    /** True when results were limited by a default cap and may not include all matching documents. */\n    truncated?: boolean;\n}\n\n/**\n * Failure return type with error information.\n */\nexport interface I_ReturnFailure extends I_ReturnBase {\n    success: false;\n    message: string;\n    code: number | string;\n}\n\n/**\n * Discriminated union type for function return values.\n * Provides type-safe handling of success and failure cases.\n *\n * @template T - The success result type (defaults to void)\n * @template E - Additional properties to merge with the result (defaults to unknown)\n *\n * @example\n * ```typescript\n * function fetchUser(id: string): I_Return<User> {\n *   try {\n *     const user = await getUser(id);\n *     return { success: true, result: user };\n *   } catch (error) {\n *     return { success: false, message: error.message, code: 'USER_NOT_FOUND' };\n *   }\n * }\n * ```\n */\nexport type I_Return<T = void, E = unknown> = I_ReturnSuccess<T, E> | I_ReturnFailure;\n\n/**\n * Type guard that narrows an `I_Return` to `I_ReturnSuccess`.\n *\n * @param result - The result to check.\n * @returns True if the result is a success.\n */\nexport function isSuccess<T, E = unknown>(result: I_Return<T, E>): result is I_ReturnSuccess<T, E> {\n    return result.success;\n}\n\n/**\n * Unwraps a successful `I_Return`, throwing an error for failure cases.\n * Useful when a failure is unexpected and should abort execution.\n *\n * @param result - The result to unwrap.\n * @returns The success result value.\n * @throws {Error} When the result is a failure.\n */\nexport function unwrapResult<T, E = unknown>(result: I_Return<T, E>): T & E {\n    if (!result.success) {\n        throw new Error(result.message);\n    }\n\n    return result.result;\n}\n\n/**\n * Alias for `unwrapResult` to improve discoverability.\n */\nexport const unwrapOrThrow = unwrapResult;\n\nexport enum E_Environment {\n    PRODUCTION = 'production',\n    STAGING = 'staging',\n    DEVELOPMENT = 'development',\n}\n"],"mappings":";AAoFA,SAAgB,EAA0B,GAAyD;AAC/F,QAAO,EAAO;;AAWlB,SAAgB,EAA6B,GAA+B;AACxE,KAAI,CAAC,EAAO,QACR,OAAU,MAAM,EAAO,QAAQ;AAGnC,QAAO,EAAO;;AAMlB,IAAa,IAAgB,GAEjB,IAAL,yBAAA,GAAA;QACH,EAAA,aAAA,cACA,EAAA,UAAA,WACA,EAAA,cAAA;KACH"}

package/dist/typescript/index.d.ts

@@ -1 +1,5 @@
-export {}
+/**
+ * Re-exports all common TypeScript types for shared usage across the codebase.
+ */
+export * from './common.type.js';
+export * from './react.type.js';

package/dist/typescript/index.js

@@ -1,2 +1,2 @@
-import { E_Environment as e, isSuccess as t, unwrapResult as n } from "./common.type.js";
-export { e as E_Environment, t as isSuccess, n as unwrapResult };
+import { E_Environment as e, isSuccess as t, unwrapOrThrow as n, unwrapResult as r } from "./common.type.js";
+export { e as E_Environment, t as isSuccess, n as unwrapOrThrow, r as unwrapResult };

package/dist/util/common/index.d.ts

@@ -1 +1,5 @@
-export {}
+/**
+ * Re-exports all common utility types for shared usage across the codebase.
+ */
+export * from './common.type.js';
+export * from './common.util.js';

package/dist/util/index.d.ts

@@ -1 +1,9 @@
-export {}
+/**
+ * Re-exports all utility modules for shared usage across the codebase.
+ */
+export * from './common/index.js';
+export * from './log/index.js';
+export * from './object/index.js';
+export * from './serializer/index.js';
+export * from './string/index.js';
+export * from './validate/index.js';

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

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

package/dist/{src/util → util}/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 } from './log.type.js';
 /**
  * Core error-catching implementation shared between Node and React environments.

package/dist/util/object/index.d.ts

@@ -1 +1,4 @@
-export {}
+/**
+ * Re-exports all object manipulation utilities.
+ */
+export * from './object.util.js';

package/dist/util/object/object.util.js

@@ -64,12 +64,12 @@ function o(...e) {
 			for (let a of e) {
 				if (r.has(a)) throw Error("deepMerge: Circular reference detected.");
 				let e = a;
-				for (let r in e) if (Object.hasOwn(e, r)) {
-					let a = e[r];
-					if (Object.hasOwn(i, r)) {
-						let e = i[r];
-						typeof a == "object" && a && typeof e == "object" && e ? Array.isArray(a) && Array.isArray(e) ? i[r] = [...e, ...a] : !Array.isArray(a) && !Array.isArray(e) ? i[r] = t([e, a], n + 1, /* @__PURE__ */ new WeakSet()) : i[r] = a : i[r] = a;
-					} else i[r] = a;
+				for (let a in e) if (Object.hasOwn(e, a)) {
+					let o = e[a];
+					if (Object.hasOwn(i, a)) {
+						let e = i[a];
+						typeof o == "object" && o && typeof e == "object" && e ? Array.isArray(o) && Array.isArray(e) ? i[a] = [...e, ...o] : !Array.isArray(o) && !Array.isArray(e) ? i[a] = t([e, o], n + 1, r) : i[a] = o : i[a] = o;
+					} else i[a] = o;
 				}
 			}
 			return i;
@@ -82,26 +82,37 @@ function o(...e) {
 }
 function s(e) {
 	if (!e || typeof e != "object") return e;
-	let t = {};
-	function n(e, r) {
-		for (let i in e) {
-			if (!Object.hasOwn(e, i)) continue;
-			let a = e[i], o = r ? `${r}.${i}` : i;
-			if (a && typeof a == "object" && !Array.isArray(a)) {
-				if (!(a.constructor === Object || Object.getPrototypeOf(a) === null)) {
-					t[o] = a;
+	let t = !0;
+	for (let n in e) {
+		if (!Object.hasOwn(e, n)) continue;
+		let r = e[n];
+		if (r && typeof r == "object" && !Array.isArray(r)) {
+			t = !1;
+			break;
+		}
+	}
+	if (t) return e;
+	let n = {};
+	function r(e, t, i) {
+		if (i > 10) throw Error("normalizeMongoFilter: Maximum depth of 10 exceeded. Possible circular reference or excessively nested filter.");
+		for (let a in e) {
+			if (!Object.hasOwn(e, a)) continue;
+			let o = e[a], s = t ? `${t}.${a}` : a;
+			if (o && typeof o == "object" && !Array.isArray(o)) {
+				if (!(o.constructor === Object || Object.getPrototypeOf(o) === null)) {
+					n[s] = o;
 					continue;
 				}
 				let e = !1;
-				for (let t in a) if (Object.hasOwn(a, t) && t.startsWith("$")) {
+				for (let t in o) if (Object.hasOwn(o, t) && t.startsWith("$")) {
 					e = !0;
 					break;
 				}
-				e ? t[o] = a : n(a, o);
-			} else t[o] = a;
+				e ? n[s] = o : r(o, s, i + 1);
+			} else n[s] = o;
 		}
 	}
-	return n(e, ""), t;
+	return r(e, "", 0), n;
 }
 //#endregion
 export { i as deepClone, o as deepMerge, t as getNestedValue, e as isJSON, s as normalizeMongoFilter, r as setNestedValue };

package/dist/util/object/object.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"object.util.js","names":[],"sources":["../../../src/util/object/object.util.ts"],"sourcesContent":["/**\n * Check if a string is a valid JSON string.\n * This function attempts to parse the string as JSON and returns true if successful,\n * false if the string is not valid JSON.\n *\n * @param str - The string to check for valid JSON format.\n * @returns True if the string is a valid JSON string, false otherwise.\n */\nexport function isJSON(str: string): boolean {\n    try {\n        JSON.parse(str);\n        return true;\n    }\n    catch {\n        return false;\n    }\n}\n\n/**\n * Gets a nested value from an object using a path array.\n * This function traverses the object following the provided path and returns\n * the value at the specified location, or undefined if the path doesn't exist.\n *\n * @param obj - The object to get the value from.\n * @param path - An array of keys representing the path to the desired value.\n * @returns The value at the specified path, or undefined if the path doesn't exist.\n */\nexport function getNestedValue<T>(obj: T, path: (string | number)[]): unknown {\n    // Optimization: Loop is faster than reduce and allows early exit\n    let current: unknown = obj;\n    const len = path.length;\n\n    for (let i = 0; i < len; i++) {\n        // Optimization: Early return if current value is null/undefined or not an object\n        // This avoids unnecessary key lookups and type checks\n        if (current == null || typeof current !== 'object') {\n            return undefined;\n        }\n\n        const key = path[i];\n\n        if (key !== undefined && key in (current as Record<string | number, unknown>)) {\n            current = (current as Record<string | number, unknown>)[key];\n        }\n        else {\n            return undefined;\n        }\n    }\n\n    return current;\n}\n\n/**\n * Recursively sets a value at a nested path within an object, creating intermediate objects as needed.\n *\n * @param obj - The source object.\n * @param path - Array of keys forming the path.\n * @param value - The value to set.\n * @param index - Current recursion depth.\n * @returns A new object with the value set at the specified path.\n */\nfunction setNestedValueHelper<T>(obj: T, path: (string | number)[], value: unknown, index: number): T {\n    if (index >= path.length)\n        return obj;\n\n    const head = path[index];\n\n    if (index === path.length - 1) {\n        return {\n            ...(obj as Record<string | number, unknown>),\n            [head as string | number]: value,\n        } as T;\n    }\n\n    const current = (obj as Record<string | number, unknown>)[head as string | number];\n\n    return {\n        ...(obj as Record<string | number, unknown>),\n        [head as string | number | symbol]: setNestedValueHelper(\n            typeof current === 'object' && current !== null\n                ? (current as object)\n                : {},\n            path,\n            value,\n            index + 1,\n        ),\n    } as T;\n}\n\n/**\n * Sets a nested value in an object using a path array.\n * This function creates the path if it doesn't exist and sets the value at the specified location.\n * The function returns a new object with the updated value, maintaining immutability.\n *\n * @param obj - The object to set the value in.\n * @param path - An array of keys representing the path to the desired location.\n * @param value - The value to set at the specified path.\n * @returns A new object with the updated value at the specified path.\n */\nexport function setNestedValue<T>(obj: T, path: (string | number)[], value: unknown): T {\n    if (path.length === 0)\n        return obj;\n\n    return setNestedValueHelper(obj, path, value, 0);\n}\n\n/**\n * Deep clones an object or array.\n * This function creates a deep copy of the input, recursively cloning objects and arrays.\n * Primitive values, dates, and other non-plain objects are returned as is (or cloned if supported).\n *\n * @remarks\n * **Non-POJO objects are NOT cloned.** Objects with custom prototypes (e.g., Mongoose ObjectId,\n * class instances, Map, Set, Buffer) are returned **by reference** to preserve driver\n * compatibility. Mutations to these nested references will affect the original.\n * If you need full deep cloning of complex types, use `structuredClone()` or a dedicated library.\n *\n * @param obj - The object to clone.\n * @returns A deep copy of the object (with non-POJO objects returned by reference).\n */\nexport function deepClone<T>(obj: T): T {\n    return deepCloneInternal(obj, new WeakMap<object, unknown>());\n}\n\n/**\n * Internal recursive implementation of deepClone with shared-reference and circular-reference handling.\n *\n * Uses a WeakMap to track already-cloned objects. This correctly handles:\n * - **Shared references**: The same object appearing in multiple places returns\n *   the same clone (preserving the shared-reference topology).\n * - **Circular references**: Detected because the object is added to the map\n *   before* its children are recursed into; a back-edge will find itself in\n *   the map and return the (partially constructed) clone rather than recursing\n *   infinitely.\n *\n * @param obj - The value to clone.\n * @param seen - A WeakMap mapping original objects to their clones.\n * @returns A deep copy of the value.\n */\nfunction deepCloneInternal<T>(obj: T, seen: WeakMap<object, unknown>): T {\n    if (obj === null || typeof obj !== 'object') {\n        return obj;\n    }\n\n    // Return the already-cloned copy for shared (or circular) references\n    if (seen.has(obj as object)) {\n        return seen.get(obj as object) as T;\n    }\n\n    if (obj instanceof Date) {\n        return new Date(obj.getTime()) as unknown as T;\n    }\n\n    if (obj instanceof RegExp) {\n        return new RegExp(obj.source, obj.flags) as unknown as T;\n    }\n\n    if (Array.isArray(obj)) {\n        // Optimization: `new Array(len)` + `for` loop is ~10-15% faster than `Array.map` or `Array.from`\n        // for large arrays since it avoids callback overhead and pre-allocates memory.\n        const len = obj.length;\n        // eslint-disable-next-line unicorn/no-new-array -- Pre-allocating array size for performance\n        const arr = new Array(len);\n        // Register before recursing to handle circular references within arrays\n        seen.set(obj as object, arr);\n\n        for (let i = 0; i < len; i++) {\n            arr[i] = deepCloneInternal(obj[i], seen);\n        }\n\n        return arr as unknown as T;\n    }\n\n    // Handle Mongoose ObjectId and other custom classes by returning reference.\n    // structuredClone is not used here because it silently corrupts nested non-POJO\n    // types (e.g., ObjectId → plain object) and Date instances in jsdom environments.\n    const proto = Object.getPrototypeOf(obj);\n\n    if (proto !== Object.prototype && proto !== null) {\n        return obj;\n    }\n\n    const result = {} as Record<string, unknown>;\n    // Register before recursing to handle circular references within objects\n    seen.set(obj as object, result);\n\n    for (const key in obj) {\n        if (Object.hasOwn(obj, key)) {\n            result[key] = deepCloneInternal((obj as Record<string, unknown>)[key], seen);\n        }\n    }\n\n    return result as T;\n}\n\n/**\n * Deep merges multiple objects into a single object.\n * @param args - The objects to merge. Can be empty, in which case returns an empty object.\n * @returns The merged object.\n */\nexport function deepMerge<T = Record<string, unknown>>(\n    ...args: (object | null | undefined)[]\n): T;\n\n/**\n * Deep merges multiple arrays into a single array.\n * @param args - The arrays to merge. Can be empty, in which case returns an empty array.\n * @returns The merged array.\n */\nexport function deepMerge<T = unknown[]>(\n    ...args: (unknown[] | null | undefined)[]\n): T;\n\n/**\n * Implementation of deepMerge function.\n * @param args - The objects or arrays to merge.\n * @returns The merged result.\n */\nexport function deepMerge<T = Record<string, unknown> | unknown[]>(\n    ...args: (object | unknown[] | null | undefined)[]\n): T {\n    const MAX_DEPTH = 20;\n\n    /** Recursively merges an array of objects with depth and circular-reference tracking. */\n    function mergeRecursive(\n        validArgs: object[],\n        depth: number,\n        seen: WeakSet<object>,\n    ): unknown {\n        // Depth guard\n        if (depth > MAX_DEPTH) {\n            throw new Error(`deepMerge: Maximum depth of ${MAX_DEPTH} exceeded. Possible circular reference or excessively nested objects.`);\n        }\n\n        // Handle empty arguments\n        if (validArgs.length === 0) {\n            return {};\n        }\n\n        // If only one argument, return it directly\n        if (validArgs.length === 1) {\n            return validArgs[0];\n        }\n\n        // Check if all arguments are arrays\n        if (validArgs.every(Array.isArray)) {\n            return (validArgs as unknown[][]).flat();\n        }\n\n        // Check if all arguments are objects (but not arrays)\n        if (validArgs.every(arg => typeof arg === 'object' && arg !== null && !Array.isArray(arg))) {\n            const result = {} as Record<string, unknown>;\n\n            for (const arg of validArgs) {\n                // Circular reference protection (per-arg scope prevents false\n                // positives when the same object appears in multiple branches)\n                if (seen.has(arg)) {\n                    throw new Error('deepMerge: Circular reference detected.');\n                }\n\n                const obj = arg as Record<string, unknown>;\n                for (const key in obj) {\n                    if (Object.hasOwn(obj, key)) {\n                        const value = obj[key];\n                        if (Object.hasOwn(result, key)) {\n                            const existingValue = result[key];\n                            if (\n                                typeof value === 'object' && value !== null\n                                && typeof existingValue === 'object' && existingValue !== null\n                            ) {\n                                if (Array.isArray(value) && Array.isArray(existingValue)) {\n                                    result[key] = [...existingValue, ...value];\n                                }\n                                else if (!Array.isArray(value) && !Array.isArray(existingValue)) {\n                                    result[key] = mergeRecursive(\n                                        [existingValue as Record<string, unknown>, value as Record<string, unknown>],\n                                        depth + 1,\n                                        new WeakSet<object>(),\n                                    );\n                                }\n                                else {\n                                    // One is array, other is object — overwrite\n                                    result[key] = value;\n                                }\n                            }\n                            else {\n                                result[key] = value;\n                            }\n                        }\n                        else {\n                            result[key] = value;\n                        }\n                    }\n                }\n            }\n            return result;\n        }\n\n        // Check if all arguments are primitive values\n        if (validArgs.every(arg => typeof arg !== 'object' || arg === null)) {\n            throw new Error(\n                'deepMerge: Cannot merge primitive values. All arguments must be objects or arrays.',\n            );\n        }\n\n        // Mixed types error\n        const hasArrays = validArgs.some(Array.isArray);\n        const hasObjects = validArgs.some(arg =>\n            typeof arg === 'object' && arg !== null && !Array.isArray(arg),\n        );\n\n        if (hasArrays && hasObjects) {\n            throw new Error(\n                'deepMerge: Cannot mix arrays and objects. All arguments must be either arrays or objects.',\n            );\n        }\n\n        // Fallback for unexpected cases\n        throw new Error(\n            'deepMerge: Invalid arguments provided. All arguments must be objects or arrays of the same type.',\n        );\n    }\n\n    // Filter out null/undefined\n    const validArgs = args.filter((arg): arg is object => arg !== null && arg !== undefined);\n\n    return mergeRecursive(validArgs, 0, new WeakSet<object>()) as T;\n}\n\n/**\n * Normalizes MongoDB filters to support both dot notation strings and nested objects.\n * This function converts nested object filters to dot notation format while preserving\n * MongoDB operators to ensure consistent behavior across different filter input formats.\n *\n * @param filter - The filter object to normalize.\n * @returns A normalized filter object with nested objects converted to dot notation,\n *          while preserving MongoDB operators as nested objects.\n *\n * @example\n * ```typescript\n * // Both of these will work the same way:\n * normalizeMongoFilter({ \"location.countryId\": \"240\" })\n * normalizeMongoFilter({ location: { countryId: \"240\" } })\n * // Both return: { \"location.countryId\": \"240\" }\n *\n * // MongoDB operators are preserved:\n * normalizeMongoFilter({ id: { $in: [\"240\", \"59\"] } })\n * // Returns: { id: { $in: [\"240\", \"59\"] } }\n * ```\n */\nexport function normalizeMongoFilter<T extends Record<string, unknown>>(filter: T): T {\n    if (!filter || typeof filter !== 'object') {\n        return filter;\n    }\n\n    const normalized: Record<string, unknown> = {};\n\n    /**\n     * Recursively flattens nested objects into dot-notation keys, preserving MongoDB operators.\n     */\n    function flatten(current: Record<string, unknown>, prefix: string) {\n        for (const key in current) {\n            if (!Object.hasOwn(current, key))\n                continue;\n\n            const value = current[key];\n            const newKey = prefix ? `${prefix}.${key}` : key;\n\n            if (value && typeof value === 'object' && !Array.isArray(value)) {\n                // Fast-path POJO check: `.constructor` is safe even on null-prototype objects\n                // (returns undefined, so the === Object check simply fails and falls through\n                // to the getPrototypeOf check which correctly identifies it as a POJO).\n                const isPojo = (value as object).constructor === Object\n                    || Object.getPrototypeOf(value) === null;\n\n                if (!isPojo) {\n                    normalized[newKey] = value;\n                    continue;\n                }\n\n                // Check for Mongo operator\n                let hasMongoOperator = false;\n                for (const subKey in value as Record<string, unknown>) {\n                    if (Object.hasOwn(value, subKey) && subKey.startsWith('$')) {\n                        hasMongoOperator = true;\n                        break;\n                    }\n                }\n\n                if (hasMongoOperator) {\n                    normalized[newKey] = value;\n                }\n                else {\n                    flatten(value as Record<string, unknown>, newKey);\n                }\n            }\n            else {\n                normalized[newKey] = value;\n            }\n        }\n    }\n\n    flatten(filter, '');\n\n    return normalized as T;\n}\n"],"mappings":"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"}
+{"version":3,"file":"object.util.js","names":[],"sources":["../../../src/util/object/object.util.ts"],"sourcesContent":["/**\n * Check if a string is a valid JSON string.\n * This function attempts to parse the string as JSON and returns true if successful,\n * false if the string is not valid JSON.\n *\n * @param str - The string to check for valid JSON format.\n * @returns True if the string is a valid JSON string, false otherwise.\n */\nexport function isJSON(str: string): boolean {\n    try {\n        JSON.parse(str);\n        return true;\n    }\n    catch {\n        /* Intentionally empty — invalid JSON returns false */\n        return false;\n    }\n}\n\n/**\n * Gets a nested value from an object using a path array.\n * This function traverses the object following the provided path and returns\n * the value at the specified location, or undefined if the path doesn't exist.\n *\n * @param obj - The object to get the value from.\n * @param path - An array of keys representing the path to the desired value.\n * @returns The value at the specified path, or undefined if the path doesn't exist.\n */\nexport function getNestedValue<T>(obj: T, path: (string | number)[]): unknown {\n    // Optimization: Loop is faster than reduce and allows early exit\n    let current: unknown = obj;\n    const len = path.length;\n\n    for (let i = 0; i < len; i++) {\n        // Optimization: Early return if current value is null/undefined or not an object\n        // This avoids unnecessary key lookups and type checks\n        if (current == null || typeof current !== 'object') {\n            return undefined;\n        }\n\n        const key = path[i];\n\n        if (key !== undefined && key in (current as Record<string | number, unknown>)) {\n            current = (current as Record<string | number, unknown>)[key];\n        }\n        else {\n            return undefined;\n        }\n    }\n\n    return current;\n}\n\n/**\n * Recursively sets a value at a nested path within an object, creating intermediate objects as needed.\n *\n * @param obj - The source object.\n * @param path - Array of keys forming the path.\n * @param value - The value to set.\n * @param index - Current recursion depth.\n * @returns A new object with the value set at the specified path.\n */\nfunction setNestedValueHelper<T>(obj: T, path: (string | number)[], value: unknown, index: number): T {\n    if (index >= path.length)\n        return obj;\n\n    const head = path[index];\n\n    if (index === path.length - 1) {\n        return {\n            ...(obj as Record<string | number, unknown>),\n            [head as string | number]: value,\n        } as T;\n    }\n\n    const current = (obj as Record<string | number, unknown>)[head as string | number];\n\n    return {\n        ...(obj as Record<string | number, unknown>),\n        [head as string | number | symbol]: setNestedValueHelper(\n            typeof current === 'object' && current !== null\n                ? (current as object)\n                : {},\n            path,\n            value,\n            index + 1,\n        ),\n    } as T;\n}\n\n/**\n * Sets a nested value in an object using a path array.\n * This function creates the path if it doesn't exist and sets the value at the specified location.\n * The function returns a new object with the updated value, maintaining immutability.\n *\n * @param obj - The object to set the value in.\n * @param path - An array of keys representing the path to the desired location.\n * @param value - The value to set at the specified path.\n * @returns A new object with the updated value at the specified path.\n */\nexport function setNestedValue<T>(obj: T, path: (string | number)[], value: unknown): T {\n    if (path.length === 0)\n        return obj;\n\n    return setNestedValueHelper(obj, path, value, 0);\n}\n\n/**\n * Deep clones an object or array.\n * This function creates a deep copy of the input, recursively cloning objects and arrays.\n * Primitive values, dates, and other non-plain objects are returned as is (or cloned if supported).\n *\n * @remarks\n * **Non-POJO objects are NOT cloned.** Objects with custom prototypes (e.g., Mongoose ObjectId,\n * class instances, Map, Set, Buffer) are returned **by reference** to preserve driver\n * compatibility. Mutations to these nested references will affect the original.\n * If you need full deep cloning of complex types, use `structuredClone()` or a dedicated library.\n *\n * @param obj - The object to clone.\n * @returns A deep copy of the object (with non-POJO objects returned by reference).\n */\nexport function deepClone<T>(obj: T): T {\n    return deepCloneInternal(obj, new WeakMap<object, unknown>());\n}\n\n/**\n * Internal recursive implementation of deepClone with shared-reference and circular-reference handling.\n *\n * Uses a WeakMap to track already-cloned objects. This correctly handles:\n * - **Shared references**: The same object appearing in multiple places returns\n *   the same clone (preserving the shared-reference topology).\n * - **Circular references**: Detected because the object is added to the map\n *   before* its children are recursed into; a back-edge will find itself in\n *   the map and return the (partially constructed) clone rather than recursing\n *   infinitely.\n *\n * @param obj - The value to clone.\n * @param seen - A WeakMap mapping original objects to their clones.\n * @returns A deep copy of the value.\n */\nfunction deepCloneInternal<T>(obj: T, seen: WeakMap<object, unknown>): T {\n    if (obj === null || typeof obj !== 'object') {\n        return obj;\n    }\n\n    // Return the already-cloned copy for shared (or circular) references\n    if (seen.has(obj as object)) {\n        return seen.get(obj as object) as T;\n    }\n\n    if (obj instanceof Date) {\n        return new Date(obj.getTime()) as unknown as T;\n    }\n\n    if (obj instanceof RegExp) {\n        return new RegExp(obj.source, obj.flags) as unknown as T;\n    }\n\n    if (Array.isArray(obj)) {\n        // Optimization: `new Array(len)` + `for` loop is ~10-15% faster than `Array.map` or `Array.from`\n        // for large arrays since it avoids callback overhead and pre-allocates memory.\n        const len = obj.length;\n        // eslint-disable-next-line unicorn/no-new-array -- Pre-allocating array size for performance\n        const arr = new Array(len);\n        // Register before recursing to handle circular references within arrays\n        seen.set(obj as object, arr);\n\n        for (let i = 0; i < len; i++) {\n            arr[i] = deepCloneInternal(obj[i], seen);\n        }\n\n        return arr as unknown as T;\n    }\n\n    // Handle Mongoose ObjectId and other custom classes by returning reference.\n    // structuredClone is not used here because it silently corrupts nested non-POJO\n    // types (e.g., ObjectId → plain object) and Date instances in jsdom environments.\n    const proto = Object.getPrototypeOf(obj);\n\n    if (proto !== Object.prototype && proto !== null) {\n        return obj;\n    }\n\n    const result = {} as Record<string, unknown>;\n    // Register before recursing to handle circular references within objects\n    seen.set(obj as object, result);\n\n    for (const key in obj) {\n        if (Object.hasOwn(obj, key)) {\n            result[key] = deepCloneInternal((obj as Record<string, unknown>)[key], seen);\n        }\n    }\n\n    return result as T;\n}\n\n/**\n * Deep merges multiple objects into a single object.\n * @param args - The objects to merge. Can be empty, in which case returns an empty object.\n * @returns The merged object.\n */\nexport function deepMerge<T = Record<string, unknown>>(\n    ...args: (object | null | undefined)[]\n): T;\n\n/**\n * Deep merges multiple arrays into a single array.\n * @param args - The arrays to merge. Can be empty, in which case returns an empty array.\n * @returns The merged array.\n */\nexport function deepMerge<T = unknown[]>(\n    ...args: (unknown[] | null | undefined)[]\n): T;\n\n/**\n * Implementation of deepMerge function.\n * @param args - The objects or arrays to merge.\n * @returns The merged result.\n */\nexport function deepMerge<T = Record<string, unknown> | unknown[]>(\n    ...args: (object | unknown[] | null | undefined)[]\n): T {\n    const MAX_DEPTH = 20;\n\n    /** Recursively merges an array of objects with depth and circular-reference tracking. */\n    function mergeRecursive(\n        validArgs: object[],\n        depth: number,\n        seen: WeakSet<object>,\n    ): unknown {\n        // Depth guard\n        if (depth > MAX_DEPTH) {\n            throw new Error(`deepMerge: Maximum depth of ${MAX_DEPTH} exceeded. Possible circular reference or excessively nested objects.`);\n        }\n\n        // Handle empty arguments\n        if (validArgs.length === 0) {\n            return {};\n        }\n\n        // If only one argument, return it directly\n        if (validArgs.length === 1) {\n            return validArgs[0];\n        }\n\n        // Check if all arguments are arrays\n        if (validArgs.every(Array.isArray)) {\n            return (validArgs as unknown[][]).flat();\n        }\n\n        // Check if all arguments are objects (but not arrays)\n        if (validArgs.every(arg => typeof arg === 'object' && arg !== null && !Array.isArray(arg))) {\n            const result = {} as Record<string, unknown>;\n\n            for (const arg of validArgs) {\n                // Circular reference protection (per-arg scope prevents false\n                // positives when the same object appears in multiple branches)\n                if (seen.has(arg)) {\n                    throw new Error('deepMerge: Circular reference detected.');\n                }\n\n                const obj = arg as Record<string, unknown>;\n\n                for (const key in obj) {\n                    if (Object.hasOwn(obj, key)) {\n                        const value = obj[key];\n\n                        if (Object.hasOwn(result, key)) {\n                            const existingValue = result[key];\n\n                            if (\n                                typeof value === 'object' && value !== null\n                                && typeof existingValue === 'object' && existingValue !== null\n                            ) {\n                                if (Array.isArray(value) && Array.isArray(existingValue)) {\n                                    result[key] = [...existingValue, ...value];\n                                }\n                                else if (!Array.isArray(value) && !Array.isArray(existingValue)) {\n                                    result[key] = mergeRecursive(\n                                        [existingValue as Record<string, unknown>, value as Record<string, unknown>],\n                                        depth + 1,\n                                        seen,\n                                    );\n                                }\n                                else {\n                                    // One is array, other is object — overwrite\n                                    result[key] = value;\n                                }\n                            }\n                            else {\n                                result[key] = value;\n                            }\n                        }\n                        else {\n                            result[key] = value;\n                        }\n                    }\n                }\n            }\n\n            return result;\n        }\n\n        // Check if all arguments are primitive values\n        if (validArgs.every(arg => typeof arg !== 'object' || arg === null)) {\n            throw new Error(\n                'deepMerge: Cannot merge primitive values. All arguments must be objects or arrays.',\n            );\n        }\n\n        // Mixed types error\n        const hasArrays = validArgs.some(Array.isArray);\n        const hasObjects = validArgs.some(arg =>\n            typeof arg === 'object' && arg !== null && !Array.isArray(arg),\n        );\n\n        if (hasArrays && hasObjects) {\n            throw new Error(\n                'deepMerge: Cannot mix arrays and objects. All arguments must be either arrays or objects.',\n            );\n        }\n\n        // Fallback for unexpected cases\n        throw new Error(\n            'deepMerge: Invalid arguments provided. All arguments must be objects or arrays of the same type.',\n        );\n    }\n\n    // Filter out null/undefined\n    const validArgs = args.filter((arg): arg is object => arg !== null && arg !== undefined);\n\n    return mergeRecursive(validArgs, 0, new WeakSet<object>()) as T;\n}\n\n/**\n * Normalizes MongoDB filters to support both dot notation strings and nested objects.\n * This function converts nested object filters to dot notation format while preserving\n * MongoDB operators to ensure consistent behavior across different filter input formats.\n *\n * @param filter - The filter object to normalize.\n * @returns A normalized filter object with nested objects converted to dot notation,\n *          while preserving MongoDB operators as nested objects.\n *\n * @example\n * ```typescript\n * // Both of these will work the same way:\n * normalizeMongoFilter({ \"location.countryId\": \"240\" })\n * normalizeMongoFilter({ location: { countryId: \"240\" } })\n * // Both return: { \"location.countryId\": \"240\" }\n *\n * // MongoDB operators are preserved:\n * normalizeMongoFilter({ id: { $in: [\"240\", \"59\"] } })\n * // Returns: { id: { $in: [\"240\", \"59\"] } }\n * ```\n */\nexport function normalizeMongoFilter<T extends Record<string, unknown>>(filter: T): T {\n    if (!filter || typeof filter !== 'object') {\n        return filter;\n    }\n\n    let isFlat = true;\n\n    for (const key in filter) {\n        if (!Object.hasOwn(filter, key)) {\n            continue;\n        }\n        const value = filter[key];\n\n        if (value && typeof value === 'object' && !Array.isArray(value)) {\n            isFlat = false;\n            break;\n        }\n    }\n\n    if (isFlat) {\n        return filter;\n    }\n\n    const normalized: Record<string, unknown> = {};\n    const MAX_DEPTH = 10;\n\n    /**\n     * Recursively flattens nested objects into dot-notation keys, preserving MongoDB operators.\n     */\n    function flatten(current: Record<string, unknown>, prefix: string, depth: number) {\n        if (depth > MAX_DEPTH) {\n            throw new Error(`normalizeMongoFilter: Maximum depth of ${MAX_DEPTH} exceeded. Possible circular reference or excessively nested filter.`);\n        }\n\n        for (const key in current) {\n            if (!Object.hasOwn(current, key)) {\n                continue;\n            }\n            const value = current[key];\n            const newKey = prefix ? `${prefix}.${key}` : key;\n\n            if (value && typeof value === 'object' && !Array.isArray(value)) {\n                // Fast-path POJO check: `.constructor` is safe even on null-prototype objects\n                // (returns undefined, so the === Object check simply fails and falls through\n                // to the getPrototypeOf check which correctly identifies it as a POJO).\n                const isPojo = (value as object).constructor === Object\n                    || Object.getPrototypeOf(value) === null;\n\n                if (!isPojo) {\n                    normalized[newKey] = value;\n                    continue;\n                }\n\n                // Check for Mongo operator\n                let hasMongoOperator = false;\n\n                for (const subKey in value as Record<string, unknown>) {\n                    if (Object.hasOwn(value, subKey) && subKey.startsWith('$')) {\n                        hasMongoOperator = true;\n                        break;\n                    }\n                }\n\n                if (hasMongoOperator) {\n                    normalized[newKey] = value;\n                }\n                else {\n                    flatten(value as Record<string, unknown>, newKey, depth + 1);\n                }\n            }\n            else {\n                normalized[newKey] = value;\n            }\n        }\n    }\n\n    flatten(filter, '', 0);\n\n    return normalized as T;\n}\n"],"mappings":"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"}

package/dist/util/serializer/index.d.ts

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

package/dist/{src/util → util}/serializer/serializer.util.d.ts

@@ -16,6 +16,14 @@ import { I_Serializer } from './serializer.type.js';
  * - RegExp → `{ __type: 'RegExp', value: { source: '...', flags: '...' } }`
  * - BigInt → `{ __type: 'BigInt', value: '12345' }`
  *
+ * **Security:** Only types in the `ALLOWED_TYPES` allowlist are reconstructed during
+ * deserialization. Unknown `__type` values are returned as-is to prevent prototype pollution.
+ * RegExp sources are length-limited (1000 chars) and flags are validated to mitigate ReDoS.
+ *
+ * **⚠️ NOT for untrusted input:** This serializer is designed for internal service-to-service
+ * communication. Do NOT use it to deserialize user-controlled payloads (e.g., raw WebSocket
+ * messages, API request bodies from external clients) without additional validation.
+ *
  * **Cross-service compatibility:** Any service that deserializes data produced by this serializer
  * must use the same `__type` protocol. Plain `JSON.parse` will return the wrapper objects as-is
  * without reconstructing the original types.

package/dist/util/serializer/serializer.util.js

@@ -1,74 +1,61 @@
 //#region src/util/serializer/serializer.util.ts
-var e = {
-	Date: {
-		is: (e) => e instanceof Date,
-		serialize: (e) => ({
-			__type: "Date",
-			value: e.toISOString()
-		}),
-		deserialize: (e) => new Date(e)
-	},
-	Map: {
-		is: (e) => e instanceof Map,
-		serialize: (e) => ({
-			__type: "Map",
-			value: [...e.entries()]
-		}),
-		deserialize: (e) => new Map(e)
-	},
-	Set: {
-		is: (e) => e instanceof Set,
-		serialize: (e) => ({
-			__type: "Set",
-			value: [...e]
-		}),
-		deserialize: (e) => new Set(e)
-	},
-	RegExp: {
-		is: (e) => e instanceof RegExp,
-		serialize: (e) => ({
-			__type: "RegExp",
-			value: {
-				source: e.source,
-				flags: e.flags
-			}
-		}),
-		deserialize: (e) => {
-			let { source: t, flags: n } = e;
-			return new RegExp(t, n);
-		}
-	},
-	BigInt: {
-		is: (e) => typeof e == "bigint",
-		serialize: (e) => ({
-			__type: "BigInt",
-			value: e.toString()
-		}),
-		deserialize: (e) => BigInt(e)
-	}
-}, t = Object.entries(e).filter(([e]) => e !== "Date").map(([, e]) => e), n = {
-	serialize(n) {
-		return JSON.stringify(n, function(n, r) {
-			let i = this[n];
-			if (i instanceof Date) return e.Date.serialize(i);
-			for (let e = 0; e < t.length; e++) {
-				let n = t[e];
-				if (n.is(r)) return n.serialize(r);
-			}
-			return r;
+var e = new Set([
+	"Date",
+	"Map",
+	"Set",
+	"RegExp",
+	"BigInt"
+]), t = 1e3, n = /^[dgimsuvy]*$/, r = {
+	serialize(e) {
+		return JSON.stringify(e, function(e, t) {
+			let n = this[e];
+			if (n instanceof Date) return {
+				__type: "Date",
+				value: n.toISOString()
+			};
+			if (typeof t == "object" && t) {
+				if (t instanceof Map) return {
+					__type: "Map",
+					value: Array.from(t.entries())
+				};
+				if (t instanceof Set) return {
+					__type: "Set",
+					value: Array.from(t)
+				};
+				if (t instanceof RegExp) return {
+					__type: "RegExp",
+					value: {
+						source: t.source,
+						flags: t.flags
+					}
+				};
+			} else if (typeof t == "bigint") return {
+				__type: "BigInt",
+				value: t.toString()
+			};
+			return t;
 		});
 	},
-	deserialize(t) {
-		return JSON.parse(t, (t, n) => {
-			if (n && typeof n == "object" && "__type" in n && typeof n.__type == "string") {
-				let t = e[n.__type];
-				if (t) return t.deserialize(n.value);
+	deserialize(r) {
+		return JSON.parse(r, (r, i) => {
+			if (typeof i == "object" && i && typeof i.__type == "string") {
+				let r = i.__type;
+				if (!e.has(r)) return i;
+				let a = i.value;
+				if (r === "Date") return new Date(a);
+				if (r === "Map") return new Map(a);
+				if (r === "Set") return new Set(a);
+				if (r === "RegExp") {
+					let { source: e, flags: r } = a;
+					return typeof e != "string" || typeof r != "string" || e.length > t || !n.test(r) ? i : new RegExp(e, r);
+				}
+				if (r === "BigInt") return BigInt(a);
 			}
-			return n;
+			return i;
 		});
 	}
 };
 //#endregion
-export { n as serializer };
+export { r as serializer };
 
 //# sourceMappingURL=serializer.util.js.map

package/dist/util/serializer/serializer.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.util.js","names":[],"sources":["../../../src/util/serializer/serializer.util.ts"],"sourcesContent":["import type {\n    I_Serializer,\n    I_SerializerTypeWrapper,\n    I_SerializerValueMap,\n    T_SerializerKnownTypes,\n} from './serializer.type.js';\n\n/**\n * Interface for handling serialization and deserialization of specific types.\n * Each handler provides methods to check if a value is of the specific type,\n * serialize it to a format that can be JSON stringified, and deserialize it back.\n */\ninterface I_Handler<T extends T_SerializerKnownTypes> {\n    /** Checks if a value is of the specific type */\n    is: (value: unknown) => value is I_SerializerValueMap[T];\n    /** Serializes a value of the specific type to a format that can be JSON stringified */\n    serialize: (value: I_SerializerValueMap[T]) => I_SerializerTypeWrapper<T>;\n    /** Deserializes a value back to the specific type */\n    deserialize: (value: unknown) => I_SerializerValueMap[T];\n}\n\n/**\n * Type handlers for different JavaScript types that cannot be directly serialized to JSON.\n * Each handler provides methods to serialize and deserialize specific types like Date, Map, Set, etc.\n */\nconst typeHandlers: {\n    [K in T_SerializerKnownTypes]: I_Handler<K>;\n} = {\n    Date: {\n        is: (v): v is Date => v instanceof Date,\n        serialize: v => ({ __type: 'Date', value: v.toISOString() }),\n        deserialize: v => new Date(v as string),\n    },\n    Map: {\n        is: (v): v is Map<unknown, unknown> => v instanceof Map,\n        serialize: v => ({ __type: 'Map', value: [...v.entries()] }),\n        deserialize: v => new Map(v as [unknown, unknown][]),\n    },\n    Set: {\n        is: (v): v is Set<unknown> => v instanceof Set,\n        serialize: v => ({ __type: 'Set', value: [...v] }),\n        deserialize: v => new Set(v as unknown[]),\n    },\n    RegExp: {\n        is: (v): v is RegExp => v instanceof RegExp,\n        serialize: v => ({\n            __type: 'RegExp',\n            value: { source: v.source, flags: v.flags },\n        }),\n        deserialize: (v) => {\n            const { source, flags } = v as { source: string; flags: string };\n            return new RegExp(source, flags);\n        },\n    },\n    BigInt: {\n        is: (v): v is bigint => typeof v === 'bigint',\n        serialize: v => ({ __type: 'BigInt', value: v.toString() }),\n        deserialize: v => BigInt(v as string),\n    },\n};\n\nconst typeHandlersValues = (Object.entries(typeHandlers) as [\n    T_SerializerKnownTypes,\n    I_Handler<T_SerializerKnownTypes>,\n][])\n    .filter(([key]) => key !== 'Date')\n    .map(([, handler]) => handler);\n\n/**\n * A serializer that can handle complex JavaScript types that cannot be directly JSON stringified.\n * This serializer extends JSON.stringify and JSON.parse to handle types like Date, Map, Set, RegExp, and BigInt.\n *\n * The serializer works by:\n * 1. During serialization: Wrapping special types with type information before JSON stringification\n * 2. During deserialization: Detecting wrapped types and reconstructing them to their original form\n *\n * @remarks\n * **Wire format protocol:** Non-JSON-native types are serialized as wrapper objects with the shape\n * `{ __type: string, value: unknown }`. For example:\n * - Date → `{ __type: 'Date', value: '2024-01-01T00:00:00.000Z' }`\n * - Map → `{ __type: 'Map', value: [['key', 'val']] }`\n * - Set → `{ __type: 'Set', value: [1, 2, 3] }`\n * - RegExp → `{ __type: 'RegExp', value: { source: '...', flags: '...' } }`\n * - BigInt → `{ __type: 'BigInt', value: '12345' }`\n *\n * **Cross-service compatibility:** Any service that deserializes data produced by this serializer\n * must use the same `__type` protocol. Plain `JSON.parse` will return the wrapper objects as-is\n * without reconstructing the original types.\n */\nexport const serializer: I_Serializer<unknown> = {\n    /**\n     * Serializes a value to a JSON string.\n     * If the value is of a known type (Date, Map, Set, RegExp, BigInt),\n     * it will be serialized using the corresponding handler.\n     * Otherwise, it will be serialized as is.\n     *\n     * @param value - The value to serialize to a JSON string.\n     * @returns The serialized JSON string that can be safely stored or transmitted.\n     */\n    serialize(value) {\n        return JSON.stringify(value, function (_key, val) {\n            // eslint-disable-next-line ts/no-this-alias\n            const context = this;\n            const originalValue = context[_key];\n\n            if (originalValue instanceof Date) {\n                return typeHandlers.Date.serialize(originalValue);\n            }\n\n            for (let i = 0; i < typeHandlersValues.length; i++) {\n                const handler = typeHandlersValues[i]!;\n\n                if (handler.is(val)) {\n                    return handler.serialize(val as I_SerializerValueMap[T_SerializerKnownTypes]);\n                }\n            }\n\n            return val;\n        });\n    },\n    /**\n     * Deserializes a JSON string to its original value.\n     * If the value is of a known type (Date, Map, Set, RegExp, BigInt),\n     * it will be deserialized using the corresponding handler.\n     * Otherwise, it will be deserialized as is.\n     *\n     * @param json - The JSON string to deserialize back to its original form.\n     * @returns The deserialized value with all special types reconstructed.\n     */\n    deserialize(json) {\n        return JSON.parse(json, (_key, val) => {\n            if (\n                val\n                && typeof val === 'object'\n                && '__type' in val\n                && typeof val.__type === 'string'\n            ) {\n                const type = val.__type as T_SerializerKnownTypes;\n                const handler = typeHandlers[type];\n\n                if (handler) {\n                    return handler.deserialize(val.value);\n                }\n            }\n            return val;\n        });\n    },\n};\n"],"mappings":";AAyBA,IAAM,IAEF;CACA,MAAM;EACF,KAAK,MAAiB,aAAa;EACnC,YAAW,OAAM;GAAE,QAAQ;GAAQ,OAAO,EAAE,aAAa;GAAE;EAC3D,cAAa,MAAK,IAAI,KAAK,EAAY;EAC1C;CACD,KAAK;EACD,KAAK,MAAkC,aAAa;EACpD,YAAW,OAAM;GAAE,QAAQ;GAAO,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC;GAAE;EAC3D,cAAa,MAAK,IAAI,IAAI,EAA0B;EACvD;CACD,KAAK;EACD,KAAK,MAAyB,aAAa;EAC3C,YAAW,OAAM;GAAE,QAAQ;GAAO,OAAO,CAAC,GAAG,EAAE;GAAE;EACjD,cAAa,MAAK,IAAI,IAAI,EAAe;EAC5C;CACD,QAAQ;EACJ,KAAK,MAAmB,aAAa;EACrC,YAAW,OAAM;GACb,QAAQ;GACR,OAAO;IAAE,QAAQ,EAAE;IAAQ,OAAO,EAAE;IAAO;GAC9C;EACD,cAAc,MAAM;GAChB,IAAM,EAAE,WAAQ,aAAU;AAC1B,UAAO,IAAI,OAAO,GAAQ,EAAM;;EAEvC;CACD,QAAQ;EACJ,KAAK,MAAmB,OAAO,KAAM;EACrC,YAAW,OAAM;GAAE,QAAQ;GAAU,OAAO,EAAE,UAAU;GAAE;EAC1D,cAAa,MAAK,OAAO,EAAY;EACxC;CACJ,EAEK,IAAsB,OAAO,QAAQ,EAAa,CAInD,QAAQ,CAAC,OAAS,MAAQ,OAAO,CACjC,KAAK,GAAG,OAAa,EAAQ,EAuBrB,IAAoC;CAU7C,UAAU,GAAO;AACb,SAAO,KAAK,UAAU,GAAO,SAAU,GAAM,GAAK;GAG9C,IAAM,IADU,KACc;AAE9B,OAAI,aAAyB,KACzB,QAAO,EAAa,KAAK,UAAU,EAAc;AAGrD,QAAK,IAAI,IAAI,GAAG,IAAI,EAAmB,QAAQ,KAAK;IAChD,IAAM,IAAU,EAAmB;AAEnC,QAAI,EAAQ,GAAG,EAAI,CACf,QAAO,EAAQ,UAAU,EAAoD;;AAIrF,UAAO;IACT;;CAWN,YAAY,GAAM;AACd,SAAO,KAAK,MAAM,IAAO,GAAM,MAAQ;AACnC,OACI,KACG,OAAO,KAAQ,YACf,YAAY,KACZ,OAAO,EAAI,UAAW,UAC3B;IAEE,IAAM,IAAU,EADH,EAAI;AAGjB,QAAI,EACA,QAAO,EAAQ,YAAY,EAAI,MAAM;;AAG7C,UAAO;IACT;;CAET"}
+{"version":3,"file":"serializer.util.js","names":[],"sources":["../../../src/util/serializer/serializer.util.ts"],"sourcesContent":["import type {\n    I_Serializer,\n} from './serializer.type.js';\n\nconst ALLOWED_TYPES = new Set(['Date', 'Map', 'Set', 'RegExp', 'BigInt']);\nconst MAX_REGEXP_SOURCE_LENGTH = 1_000;\nconst VALID_REGEXP_FLAGS = /^[dgimsuvy]*$/;\n\n/**\n * A serializer that can handle complex JavaScript types that cannot be directly JSON stringified.\n * This serializer extends JSON.stringify and JSON.parse to handle types like Date, Map, Set, RegExp, and BigInt.\n *\n * The serializer works by:\n * 1. During serialization: Wrapping special types with type information before JSON stringification\n * 2. During deserialization: Detecting wrapped types and reconstructing them to their original form\n *\n * @remarks\n * **Wire format protocol:** Non-JSON-native types are serialized as wrapper objects with the shape\n * `{ __type: string, value: unknown }`. For example:\n * - Date → `{ __type: 'Date', value: '2024-01-01T00:00:00.000Z' }`\n * - Map → `{ __type: 'Map', value: [['key', 'val']] }`\n * - Set → `{ __type: 'Set', value: [1, 2, 3] }`\n * - RegExp → `{ __type: 'RegExp', value: { source: '...', flags: '...' } }`\n * - BigInt → `{ __type: 'BigInt', value: '12345' }`\n *\n * **Security:** Only types in the `ALLOWED_TYPES` allowlist are reconstructed during\n * deserialization. Unknown `__type` values are returned as-is to prevent prototype pollution.\n * RegExp sources are length-limited (1000 chars) and flags are validated to mitigate ReDoS.\n *\n * **⚠️ NOT for untrusted input:** This serializer is designed for internal service-to-service\n * communication. Do NOT use it to deserialize user-controlled payloads (e.g., raw WebSocket\n * messages, API request bodies from external clients) without additional validation.\n *\n * **Cross-service compatibility:** Any service that deserializes data produced by this serializer\n * must use the same `__type` protocol. Plain `JSON.parse` will return the wrapper objects as-is\n * without reconstructing the original types.\n */\nexport const serializer: I_Serializer<unknown> = {\n    /**\n     * Serializes a value to a JSON string.\n     * If the value is of a known type (Date, Map, Set, RegExp, BigInt),\n     * it will be serialized using the corresponding handler.\n     * Otherwise, it will be serialized as is.\n     *\n     * @param value - The value to serialize to a JSON string.\n     * @returns The serialized JSON string that can be safely stored or transmitted.\n     */\n    serialize(value) {\n        return JSON.stringify(value, function (this: Record<string, unknown>, _key, val) {\n            // Date#toJSON fires before the replacer, converting a Date to an ISO string.\n            // We must read this[_key] to detect the original Date object.\n            const originalValue = this[_key];\n            if (originalValue instanceof Date) {\n                return { __type: 'Date', value: originalValue.toISOString() };\n            }\n\n            // For all other special types, val is already the original value\n            // (they have no toJSON), so use val directly to avoid the extra property access.\n            if (val !== null && typeof val === 'object') {\n                if (val instanceof Map) {\n                    return { __type: 'Map', value: Array.from(val.entries()) };\n                }\n                if (val instanceof Set) {\n                    return { __type: 'Set', value: Array.from(val) };\n                }\n                if (val instanceof RegExp) {\n                    return { __type: 'RegExp', value: { source: val.source, flags: val.flags } };\n                }\n            }\n            else if (typeof val === 'bigint') {\n                return { __type: 'BigInt', value: val.toString() };\n            }\n\n            return val;\n        });\n    },\n    /**\n     * Deserializes a JSON string to its original value.\n     * If the value is of a known type (Date, Map, Set, RegExp, BigInt),\n     * it will be deserialized using the corresponding handler.\n     * Otherwise, it will be deserialized as is.\n     * Unknown `__type` values are ignored (returned as-is) for security.\n     *\n     * @param json - The JSON string to deserialize back to its original form.\n     * @returns The deserialized value with all special types reconstructed.\n     */\n    deserialize(json) {\n        return JSON.parse(json, (_key, val) => {\n            if (val !== null && typeof val === 'object' && typeof val.__type === 'string') {\n                const type = val.__type;\n\n                // Security: Only reconstruct types in the allowlist\n                if (!ALLOWED_TYPES.has(type)) {\n                    return val;\n                }\n\n                const value = val.value;\n\n                if (type === 'Date') {\n                    return new Date(value as string);\n                }\n                if (type === 'Map') {\n                    return new Map(value as [unknown, unknown][]);\n                }\n                if (type === 'Set') {\n                    return new Set(value as unknown[]);\n                }\n                if (type === 'RegExp') {\n                    const { source, flags } = value as { source: string; flags: string };\n                    if (\n                        typeof source !== 'string'\n                        || typeof flags !== 'string'\n                        || source.length > MAX_REGEXP_SOURCE_LENGTH\n                        || !VALID_REGEXP_FLAGS.test(flags)\n                    ) {\n                        return val;\n                    }\n                    return new RegExp(source, flags);\n                }\n                if (type === 'BigInt') {\n                    return BigInt(value as string);\n                }\n            }\n            return val;\n        });\n    },\n};\n"],"mappings":";AAIA,IAAM,IAAgB,IAAI,IAAI;CAAC;CAAQ;CAAO;CAAO;CAAU;CAAS,CAAC,EACnE,IAA2B,KAC3B,IAAqB,iBA+Bd,IAAoC;CAU7C,UAAU,GAAO;AACb,SAAO,KAAK,UAAU,GAAO,SAAyC,GAAM,GAAK;GAG7E,IAAM,IAAgB,KAAK;AAC3B,OAAI,aAAyB,KACzB,QAAO;IAAE,QAAQ;IAAQ,OAAO,EAAc,aAAa;IAAE;AAKjE,OAAoB,OAAO,KAAQ,YAA/B,GAAyC;AACzC,QAAI,aAAe,IACf,QAAO;KAAE,QAAQ;KAAO,OAAO,MAAM,KAAK,EAAI,SAAS,CAAC;KAAE;AAE9D,QAAI,aAAe,IACf,QAAO;KAAE,QAAQ;KAAO,OAAO,MAAM,KAAK,EAAI;KAAE;AAEpD,QAAI,aAAe,OACf,QAAO;KAAE,QAAQ;KAAU,OAAO;MAAE,QAAQ,EAAI;MAAQ,OAAO,EAAI;MAAO;KAAE;cAG3E,OAAO,KAAQ,SACpB,QAAO;IAAE,QAAQ;IAAU,OAAO,EAAI,UAAU;IAAE;AAGtD,UAAO;IACT;;CAYN,YAAY,GAAM;AACd,SAAO,KAAK,MAAM,IAAO,GAAM,MAAQ;AACnC,OAAoB,OAAO,KAAQ,YAA/B,KAA2C,OAAO,EAAI,UAAW,UAAU;IAC3E,IAAM,IAAO,EAAI;AAGjB,QAAI,CAAC,EAAc,IAAI,EAAK,CACxB,QAAO;IAGX,IAAM,IAAQ,EAAI;AAElB,QAAI,MAAS,OACT,QAAO,IAAI,KAAK,EAAgB;AAEpC,QAAI,MAAS,MACT,QAAO,IAAI,IAAI,EAA8B;AAEjD,QAAI,MAAS,MACT,QAAO,IAAI,IAAI,EAAmB;AAEtC,QAAI,MAAS,UAAU;KACnB,IAAM,EAAE,WAAQ,aAAU;AAS1B,YAPI,OAAO,KAAW,YACf,OAAO,KAAU,YACjB,EAAO,SAAS,KAChB,CAAC,EAAmB,KAAK,EAAM,GAE3B,IAEJ,IAAI,OAAO,GAAQ,EAAM;;AAEpC,QAAI,MAAS,SACT,QAAO,OAAO,EAAgB;;AAGtC,UAAO;IACT;;CAET"}

package/dist/util/storage/storage-envelope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Represents a wrapped storage value that includes Time-to-Live (TTL) expiration metadata.
+ * @since 3.13.0
+ */
+export interface I_StorageEnvelope<T> {
+    __isTtlEnvelope: true;
+    expiresAt?: number;
+    value: T;
+}
+/**
+ * Checks whether an unknown storage payload is a valid TTL envelope.
+ * @since 3.13.0
+ */
+export declare function isTtlEnvelope<T>(payload: unknown): payload is I_StorageEnvelope<T>;
+/**
+ * Checks if a TTL envelope has expired based on its timestamp.
+ * Returns true if the envelope has an expiration time and that time has passed.
+ * @since 3.13.0
+ */
+export declare function isExpiredEnvelope<T>(envelope: I_StorageEnvelope<T>): boolean;
+/**
+ * Wraps a value in a TTL envelope with the specified expiration duration.
+ * @since 3.13.0
+ */
+export declare function createTtlEnvelope<T>(value: T, ttlMs: number): I_StorageEnvelope<T>;