npm - @cyberskill/shared - Versions diffs - 3.12.0 → 3.14.0 - Mend

@cyberskill/shared 3.12.0 → 3.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (254) hide show

package/dist/node/storage/storage.util.js CHANGED Viewed

@@ -1,58 +1,59 @@
-import { getEnv as e } from "../../config/env/env.util.js";
-import { catchError as t, log as n } from "../log/log.util.js";
-import { STORAGE_KEY_EXTENSION as r } from "./storage.constant.js";
-import i from "node:path";
-import a from "node:fs/promises";
+import { createTtlEnvelope as e, isExpiredEnvelope as t, isTtlEnvelope as n } from "../../util/storage/storage-envelope.js";
+import { getEnv as r } from "../../config/env/env.util.js";
+import { catchError as i, log as a } from "../log/log.util.js";
+import { STORAGE_KEY_EXTENSION as o } from "./storage.constant.js";
+import s from "node:path";
+import c from "node:fs/promises";
 //#region src/node/storage/storage.util.ts
-var o = 200, s = { baseDir: "" };
-function c(e) {
-	if (e.length > o) throw RangeError(`Storage key exceeds maximum length of ${o} characters`);
-	return `${encodeURIComponent(e)}${r}`;
+var l = 200, u = { baseDir: "" };
+function d(e) {
+	if (e.length > l) throw RangeError(`Storage key exceeds maximum length of ${l} characters`);
+	return `${encodeURIComponent(e)}${o}`;
 }
-function l(e) {
-	return decodeURIComponent(e.slice(0, -r.length));
+function f(e) {
+	return decodeURIComponent(e.slice(0, -o.length));
 }
-function u(e, t) {
-	return i.join(t, c(e));
+function p(e, t) {
+	return s.join(t, d(e));
 }
-var d = {
-	async init(t) {
+var m = {
+	async init(e) {
 		try {
-			typeof t == "string" && t.length > 0 ? s.baseDir = t : s.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY, await a.mkdir(s.baseDir, { recursive: !0 });
+			typeof e == "string" && e.length > 0 ? u.baseDir = e : u.baseDir = r().CYBERSKILL_STORAGE_DIRECTORY, await c.mkdir(u.baseDir, { recursive: !0 });
 		} catch (e) {
-			throw n.error("[Storage:init]", e), e;
+			throw a.error("[Storage:init]", e), e;
 		}
 	},
 	async clear() {
-		let { baseDir: e } = s;
+		let { baseDir: e } = u;
 		if (!e) return;
 		let t = `${e}.trash.${Date.now()}`, n = `${e}.fresh.${Date.now()}`;
 		try {
-			await a.mkdir(n, { recursive: !0 });
+			await c.mkdir(n, { recursive: !0 });
 			try {
-				await a.rename(e, t);
+				await c.rename(e, t);
 			} catch {}
-			await a.rename(n, e), a.rm(t, {
+			await c.rename(n, e), c.rm(t, {
 				recursive: !0,
 				force: !0
 			}).catch(() => {});
 		} catch {
-			await a.rm(e, {
+			await c.rm(e, {
 				recursive: !0,
 				force: !0
-			}), await a.mkdir(e, { recursive: !0 }), a.rm(n, {
+			}), await c.mkdir(e, { recursive: !0 }), c.rm(n, {
 				recursive: !0,
 				force: !0
-			}).catch(() => {}), a.rm(t, {
+			}).catch(() => {}), c.rm(t, {
 				recursive: !0,
 				force: !0
 			}).catch(() => {});
 		}
 	},
 	async getItem(e) {
-		let { baseDir: t } = s, n = u(e, t);
+		let { baseDir: t } = u, n = p(e, t);
 		try {
-			let e = await a.readFile(n, "utf8");
+			let e = await c.readFile(n, "utf8");
 			return JSON.parse(e);
 		} catch (e) {
 			if (e.code === "ENOENT") return null;
@@ -60,70 +61,94 @@ var d = {
 		}
 	},
 	async keys() {
-		let { baseDir: e } = s;
+		let { baseDir: e } = u;
 		try {
-			return (await a.readdir(e)).filter((e) => e.endsWith(r)).map(l);
+			return (await c.readdir(e)).filter((e) => e.endsWith(o)).map(f);
 		} catch (e) {
 			if (e.code === "ENOENT") return [];
 			throw e;
 		}
 	},
 	async removeItem(e) {
-		let { baseDir: t } = s, n = u(e, t);
-		await a.rm(n, { force: !0 });
+		let { baseDir: t } = u, n = p(e, t);
+		await c.rm(n, { force: !0 });
 	},
 	async setItem(e, t) {
-		let { baseDir: n } = s, r = u(e, n);
-		return await a.mkdir(n, { recursive: !0 }), await a.writeFile(r, JSON.stringify(t), "utf8"), t;
+		let { baseDir: n } = u, r = p(e, n);
+		return await c.mkdir(n, { recursive: !0 }), await c.writeFile(r, JSON.stringify(t), "utf8"), t;
 	}
-}, f = null;
-async function p() {
-	return f ? (await f, d) : (f = d.init().catch((e) => {
-		throw f = null, e;
-	}), await f, d);
+}, h = null, g = m;
+async function _() {
+	return h ? (await h, g) : (h = g.init().catch((e) => {
+		throw h = null, e;
+	}), await h, g);
 }
-var m = {
+var v = {
+	async initDriver(e) {
+		g = e, h = null, await _();
+	},
 	async get(e) {
 		try {
-			return await (await p()).getItem(e) ?? null;
+			let r = await _(), i = await r.getItem(e);
+			return i === null ? null : n(i) ? t(i) ? (r.removeItem(e).catch(() => {}), null) : i.value : i;
 		} catch (e) {
-			return t(e, { returnValue: null });
+			return i(e, { returnValue: null });
 		}
 	},
-	async set(e, n) {
+	async set(t, n, r) {
 		try {
-			await (await p()).setItem(e, n);
+			let i = await _(), a = n;
+			r?.ttlMs && (a = e(n, r.ttlMs)), await i.setItem(t, a);
 		} catch (e) {
-			throw t(e), e;
+			throw i(e), e;
 		}
 	},
 	async remove(e) {
 		try {
-			await (await p()).removeItem(e);
+			await (await _()).removeItem(e);
+		} catch (e) {
+			i(e);
+		}
+	},
+	async has(e) {
+		try {
+			let r = await _(), i = await r.getItem(e);
+			return i === null ? !1 : n(i) && t(i) ? (r.removeItem(e).catch(() => {}), !1) : !0;
 		} catch (e) {
-			t(e);
+			return i(e, { returnValue: !1 });
+		}
+	},
+	async clear() {
+		try {
+			await (await _()).clear();
+		} catch (e) {
+			i(e);
 		}
 	},
 	async keys() {
 		try {
-			let e = await (await p()).keys();
-			return Array.isArray(e) ? e : (n.warn("[Storage:keys] Invalid keys response:", e), []);
+			let e = await (await _()).keys();
+			return Array.isArray(e) ? e : (a.warn("[Storage:keys] Invalid keys response:", e), []);
 		} catch (e) {
-			return t(e, { returnValue: [] });
+			return i(e, { returnValue: [] });
 		}
 	},
-	async getLogLink(n) {
+	async getLogLink(e) {
 		try {
-			return `${i.join(e().CYBERSKILL_STORAGE_DIRECTORY, c(n))} (key: ${n})`;
+			return `${s.join(r().CYBERSKILL_STORAGE_DIRECTORY, d(e))} (key: ${e})`;
 		} catch (e) {
-			return t(e, { returnValue: null });
+			return i(e, { returnValue: null });
 		}
+	},
+	async getOrSet(e, t, n) {
+		let r = await this.get(e);
+		return r === null && (r = await t(), await this.set(e, r, n)), r;
 	}
 };
-function h() {
-	f = null, s.baseDir = "";
+function y() {
+	h = null, g = m, u.baseDir = "";
 }
 //#endregion
-export { h as resetStorageForTesting, m as storage };
+export { y as resetStorageForTesting, v as storage };
 //# sourceMappingURL=storage.util.js.map

package/dist/node/storage/storage.util.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { STORAGE_KEY_EXTENSION } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\ninterface NodeFsDriverState {\n baseDir: string;\n}\n\nconst nodeFsDriverState: NodeFsDriverState = {\n baseDir: '',\n};\n\n/*\n Encodes a storage key into a filename-safe string.\n * Validates key length before encoding to prevent OS filename limits.\n \n @throws {RangeError} When key exceeds maximum length.\n /\nfunction encodeKey(key: string): string {\n if (key.length > MAX_KEY_LENGTH) {\n throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n }\n return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/\n Decodes a filename-safe key back to the original storage key.\n /\nfunction decodeKey(fileName: string): string {\n return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/\n Maps a storage key to an absolute file path inside the storage directory.\n /\nfunction getFilePath(key: string, baseDir: string): string {\n return path.join(baseDir, encodeKey(key));\n}\n\n/\n Filesystem-backed storage driver that stores JSON-encoded values on disk.\n * Directly implements all storage operations without any external dependencies.\n * storage operations without the unnecessary browser-oriented dependency.\n /\nconst fsDriver = {\n /* Ensures the storage directory exists. /\n async init(baseDir?: string) {\n try {\n if (typeof baseDir === 'string' && baseDir.length > 0) {\n nodeFsDriverState.baseDir = baseDir;\n }\n else {\n nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n }\n\n await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n }\n catch (error) {\n log.error('[Storage:init]', error);\n throw error;\n }\n },\n /* Deletes all stored entries atomically by swapping to a fresh directory. /\n async clear() {\n const { baseDir } = nodeFsDriverState;\n\n if (!baseDir) {\n return;\n }\n\n // Atomic swap: create a fresh temp dir, rename old→trash, rename fresh→baseDir, remove trash\n const trashDir = `${baseDir}.trash.${Date.now()}`;\n const freshDir = `${baseDir}.fresh.${Date.now()}`;\n\n try {\n await fs.mkdir(freshDir, { recursive: true });\n // Try atomic rename swap\n try {\n await fs.rename(baseDir, trashDir);\n }\n catch {\n // baseDir might not exist yet; no-op\n }\n await fs.rename(freshDir, baseDir);\n // Clean up trash in the background (non-blocking)\n fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n }\n catch {\n // Fallback: non-atomic clear (e.g., cross-device rename)\n await fs.rm(baseDir, { recursive: true, force: true });\n await fs.mkdir(baseDir, { recursive: true });\n // Clean up any leftover temp dirs\n fs.rm(freshDir, { recursive: true, force: true }).catch(() => {});\n fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n }\n },\n /* Reads and parses a stored value; returns null when the file is missing. /\n async getItem<T>(key: string): Promise<T \| null> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n try {\n const content = await fs.readFile(filePath, 'utf8');\n\n return JSON.parse(content) as T;\n }\n catch (error) {\n if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n return null;\n }\n throw error;\n }\n },\n /* Lists all stored keys. /\n async keys(): Promise<string[]> {\n const { baseDir } = nodeFsDriverState;\n\n try {\n const files = await fs.readdir(baseDir);\n\n return files\n .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n .map(decodeKey);\n }\n catch (error) {\n if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n return [];\n }\n throw error;\n }\n },\n /* Removes a stored value for the given key. /\n async removeItem(key: string): Promise<void> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n await fs.rm(filePath, { force: true });\n },\n /* Stores a value as JSON on disk. /\n async setItem<T>(key: string, value: T): Promise<T> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n await fs.mkdir(baseDir, { recursive: true });\n await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n return value;\n },\n};\n\nlet initPromise: Promise<void> \| null = null;\n\n/\n Initializes the filesystem storage driver (singleton, idempotent).\n * Ensures the storage directory exists before any read/write operations.\n /\nasync function ensureDriverReady(): Promise<typeof fsDriver> {\n if (initPromise) {\n await initPromise;\n return fsDriver;\n }\n\n initPromise = fsDriver.init().catch((error) => {\n initPromise = null;\n throw error;\n });\n\n await initPromise;\n\n return fsDriver;\n}\n\n/\n Persistent storage utility object for data persistence across application sessions.\n * Uses a filesystem-backed driver that stores JSON-encoded values on disk,\n * with automatic initialization and error handling.\n /\nexport const storage = {\n /\n Retrieves a value from persistent 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.\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 driver = await ensureDriverReady();\n const result = await driver.getItem<T>(key);\n\n return result ?? null;\n }\n catch (error) {\n return catchError(error, { returnValue: null });\n }\n },\n /\n Stores a value in persistent 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 and stored in the configured storage directory.\n \n @param key - The unique identifier for the value to store.\n * @param value - The data to store (will be automatically serialized).\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 const driver = await ensureDriverReady();\n\n await driver.setItem(key, value);\n }\n catch (error) {\n catchError(error);\n throw error;\n }\n },\n /\n Removes a value from persistent storage by key.\n * This method permanently deletes the stored data associated with the specified key.\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 const driver = await ensureDriverReady();\n\n await driver.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.\n \n @returns A promise that resolves to an array of storage keys.\n /\n async keys(): Promise<string[]> {\n try {\n const driver = await ensureDriverReady();\n const keys = await driver.keys();\n\n if (!Array.isArray(keys)) {\n log.warn(`[Storage:keys] Invalid keys response:`, keys);\n return [];\n }\n\n return keys;\n }\n catch (error) {\n return catchError(error, { returnValue: [] });\n }\n },\n /\n Gets a human-readable log link for a storage key.\n * This method provides a formatted string that shows the storage directory path\n * and the key name for debugging and manual inspection purposes.\n \n @param key - The storage key to generate a log link for.\n * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n /\n async getLogLink(key: string): Promise<string \| null> {\n try {\n const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n return `${storagePath} (key: ${key})`;\n }\n catch (error) {\n return catchError(error, { returnValue: null });\n }\n },\n\n};\n\n/\n Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n */\nexport function resetStorageForTesting(): void {\n initPromise = null;\n nodeFsDriverState.baseDir = '';\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport { createTtlEnvelope, isExpiredEnvelope, isTtlEnvelope } from '../../util/storage/storage-envelope.js';\nimport { catchError, log } from '../log/index.js';\nimport { STORAGE_KEY_EXTENSION } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\ninterface NodeFsDriverState {\n baseDir: string;\n}\n\nexport interface I_StorageDriver {\n init: (options?: unknown) => Promise<void>;\n clear: () => Promise<void>;\n getItem: <T>(key: string) => Promise<T \| null>;\n keys: () => Promise<string[]>;\n removeItem: (key: string) => Promise<void>;\n setItem: <T>(key: string, value: T) => Promise<T>;\n}\n\nconst nodeFsDriverState: NodeFsDriverState = {\n baseDir: '',\n};\n\n/*\n Encodes a storage key into a filename-safe string.\n * Validates key length before encoding to prevent OS filename limits.\n \n @throws {RangeError} When key exceeds maximum length.\n /\nfunction encodeKey(key: string): string {\n if (key.length > MAX_KEY_LENGTH) {\n throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n }\n return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/\n Decodes a filename-safe key back to the original storage key.\n /\nfunction decodeKey(fileName: string): string {\n return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/\n Maps a storage key to an absolute file path inside the storage directory.\n /\nfunction getFilePath(key: string, baseDir: string): string {\n return path.join(baseDir, encodeKey(key));\n}\n\n/\n Filesystem-backed storage driver that stores JSON-encoded values on disk.\n * Directly implements all storage operations without any external dependencies.\n /\nconst fsDriver: I_StorageDriver = {\n /* Ensures the storage directory exists. /\n async init(baseDir?: unknown) {\n try {\n if (typeof baseDir === 'string' && baseDir.length > 0) {\n nodeFsDriverState.baseDir = baseDir;\n }\n else {\n nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n }\n\n await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n }\n catch (error) {\n log.error('[Storage:init]', error);\n throw error;\n }\n },\n /* Deletes all stored entries atomically by swapping to a fresh directory. /\n async clear() {\n const { baseDir } = nodeFsDriverState;\n\n if (!baseDir) {\n return;\n }\n\n // Atomic swap: create a fresh temp dir, rename old→trash, rename fresh→baseDir, remove trash\n const trashDir = `${baseDir}.trash.${Date.now()}`;\n const freshDir = `${baseDir}.fresh.${Date.now()}`;\n\n try {\n await fs.mkdir(freshDir, { recursive: true });\n // Try atomic rename swap\n try {\n await fs.rename(baseDir, trashDir);\n }\n catch {\n // baseDir might not exist yet; no-op\n }\n await fs.rename(freshDir, baseDir);\n // Clean up trash in the background (non-blocking)\n fs.rm(trashDir, { recursive: true, force: true }).catch(() => { });\n }\n catch {\n // Fallback: non-atomic clear (e.g., cross-device rename)\n await fs.rm(baseDir, { recursive: true, force: true });\n await fs.mkdir(baseDir, { recursive: true });\n // Clean up any leftover temp dirs\n fs.rm(freshDir, { recursive: true, force: true }).catch(() => { });\n fs.rm(trashDir, { recursive: true, force: true }).catch(() => { });\n }\n },\n /* Reads and parses a stored value; returns null when the file is missing. /\n async getItem<T>(key: string): Promise<T \| null> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n try {\n const content = await fs.readFile(filePath, 'utf8');\n\n return JSON.parse(content) as T;\n }\n catch (error) {\n if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n return null;\n }\n throw error;\n }\n },\n /* Lists all stored keys. /\n async keys(): Promise<string[]> {\n const { baseDir } = nodeFsDriverState;\n\n try {\n const files = await fs.readdir(baseDir);\n\n return files\n .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n .map(decodeKey);\n }\n catch (error) {\n if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n return [];\n }\n throw error;\n }\n },\n /* Removes a stored value for the given key. /\n async removeItem(key: string): Promise<void> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n await fs.rm(filePath, { force: true });\n },\n /* Stores a value as JSON on disk. /\n async setItem<T>(key: string, value: T): Promise<T> {\n const { baseDir } = nodeFsDriverState;\n const filePath = getFilePath(key, baseDir);\n\n await fs.mkdir(baseDir, { recursive: true });\n await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n return value;\n },\n};\n\nlet initPromise: Promise<void> \| null = null;\nlet activeDriver: I_StorageDriver = fsDriver;\n\n/\n Initializes the storage driver (singleton, idempotent).\n /\nasync function ensureDriverReady(): Promise<I_StorageDriver> {\n if (initPromise) {\n await initPromise;\n return activeDriver;\n }\n\n initPromise = activeDriver.init().catch((error) => {\n initPromise = null;\n throw error;\n });\n\n await initPromise;\n\n return activeDriver;\n}\n\n/\n Persistent storage utility object for data persistence across application sessions.\n * Uses a filesystem-backed driver that stores JSON-encoded values on disk,\n * with automatic initialization and error handling.\n /\nexport const storage = {\n /\n Initializes the utility with a custom storage driver instead of the default filesystem driver.\n * This allows swapping to Redis, Memory, or cloud-based drivers.\n * Must optionally be called before the first read/write operation.\n \n @param driver - The custom storage driver object that adheres to I_StorageDriver.\n /\n async initDriver(driver: I_StorageDriver): Promise<void> {\n activeDriver = driver;\n initPromise = null;\n await ensureDriverReady();\n },\n /\n Retrieves a value from persistent 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.\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 driver = await ensureDriverReady();\n const result = await driver.getItem<unknown>(key);\n\n if (result === null) {\n return null;\n }\n\n if (isTtlEnvelope<T>(result)) {\n if (isExpiredEnvelope(result)) {\n driver.removeItem(key).catch(() => { });\n\n return null;\n }\n\n return result.value;\n }\n\n return result as T;\n }\n catch (error) {\n return catchError(error, { returnValue: null });\n }\n },\n /\n Stores a value in persistent 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 and stored in the configured storage directory.\n \n @param key - The unique identifier for the value to store.\n * @param value - The data to store (will be automatically serialized).\n * @param options - Optional settings, such as `ttlMs` for setting an expiration on the key.\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 const driver = await ensureDriverReady();\n\n let payloadToStore: unknown = value;\n\n if (options?.ttlMs) {\n payloadToStore = createTtlEnvelope(value, options.ttlMs);\n }\n\n await driver.setItem(key, payloadToStore);\n }\n catch (error) {\n catchError(error);\n throw error;\n }\n },\n /\n Removes a value from persistent storage by key.\n * This method permanently deletes the stored data associated with the specified key.\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 const driver = await ensureDriverReady();\n\n await driver.removeItem(key);\n }\n catch (error) {\n catchError(error);\n }\n },\n /\n Checks if a key exists in persistent storage.\n * This method efficiently checks for key existence and respects TTL parsing.\n * 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 * @since 3.13.0\n /\n async has(key: string): Promise<boolean> {\n try {\n const driver = await ensureDriverReady();\n const result = await driver.getItem<unknown>(key);\n\n if (result === null) {\n return false;\n }\n\n if (isTtlEnvelope<unknown>(result)) {\n if (isExpiredEnvelope(result)) {\n driver.removeItem(key).catch(() => { });\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 entries from storage atomically.\n * @returns A promise that resolves when the clearing operation is complete.\n /\n async clear(): Promise<void> {\n try {\n const driver = await ensureDriverReady();\n await driver.clear();\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.\n \n @returns A promise that resolves to an array of storage keys.\n /\n async keys(): Promise<string[]> {\n try {\n const driver = await ensureDriverReady();\n const keys = await driver.keys();\n\n if (!Array.isArray(keys)) {\n log.warn(`[Storage:keys] Invalid keys response:`, keys);\n return [];\n }\n\n return keys;\n }\n catch (error) {\n return catchError(error, { returnValue: [] });\n }\n },\n /\n Gets a human-readable log link for a storage key.\n * This method provides a formatted string that shows the storage directory path\n * and the key name for debugging and manual inspection purposes.\n \n @param key - The storage key to generate a log link for.\n * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n /\n async getLogLink(key: string): Promise<string \| null> {\n try {\n const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n return `${storagePath} (key: ${key})`;\n }\n catch (error) {\n return catchError(error, { returnValue: null });\n }\n },\n /\n Retrieves a value from persistent 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\n/\n Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n * @since 3.13.0\n */\nexport function resetStorageForTesting(): void {\n initPromise = null;\n activeDriver = fsDriver;\n nodeFsDriverState.baseDir = '';\n}\n"],"mappings":"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"}

package/dist/node/upload/index.d.ts CHANGED Viewed

@@ -1 +1,3 @@
-export {}
+export * from './upload.constant.js';
+export * from './upload.type.js';
+export * from './upload.util.js';

package/dist/{src/node → node}/upload/upload.type.d.ts RENAMED Viewed

@@ -8,6 +8,7 @@ export declare enum E_UploadType {
 export interface I_UploadValidationConfig {
     filename: string;
     fileSize?: number;
+    mimetype?: string;
 }
 export interface I_UploadTypeConfig {
     allowedExtensions: string[];
@@ -23,6 +24,7 @@ export interface I_UploadConfig {
 export interface I_UploadFileData {
     createReadStream: () => NodeJS.ReadableStream;
     filename: string;
+    mimetype?: string;
 }
 export interface I_UploadFile {
     file: I_UploadFileData;

package/dist/node/upload/upload.type.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n IMAGE = 'IMAGE',\n VIDEO = 'VIDEO',\n AUDIO = 'AUDIO',\n DOCUMENT = 'DOCUMENT',\n OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n filename: string;\n fileSize?: number;\n}\n\nexport interface I_UploadTypeConfig {\n allowedExtensions: string[];\n sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n [E_UploadType.IMAGE]: I_UploadTypeConfig;\n [E_UploadType.VIDEO]: I_UploadTypeConfig;\n [E_UploadType.AUDIO]: I_UploadTypeConfig;\n [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n createReadStream: () => NodeJS.ReadableStream;\n filename: string;\n}\n\nexport interface I_UploadFile {\n file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n file: Promise<I_UploadFile>;\n path: string;\n type: E_UploadType;\n config?: I_UploadConfig;\n /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */\n baseDir?: string;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}
1	+ {"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n IMAGE = 'IMAGE',\n VIDEO = 'VIDEO',\n AUDIO = 'AUDIO',\n DOCUMENT = 'DOCUMENT',\n OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n filename: string;\n fileSize?: number;\n mimetype?: string;\n}\n\nexport interface I_UploadTypeConfig {\n allowedExtensions: string[];\n sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n [E_UploadType.IMAGE]: I_UploadTypeConfig;\n [E_UploadType.VIDEO]: I_UploadTypeConfig;\n [E_UploadType.AUDIO]: I_UploadTypeConfig;\n [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n createReadStream: () => NodeJS.ReadableStream;\n filename: string;\n mimetype?: string;\n}\n\nexport interface I_UploadFile {\n file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n file: Promise<I_UploadFile>;\n path: string;\n type: E_UploadType;\n config?: I_UploadConfig;\n /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */\n baseDir?: string;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}

package/dist/{src/node → node}/upload/upload.util.d.ts RENAMED Viewed

@@ -1,5 +1,5 @@
 import { ReadableStream } from 'node:stream/web';
-import { I_Return } from '../../../typescript/index.js';
+import { I_Return } from '../../typescript/index.js';
 import { I_UploadConfig, I_UploadFile, I_UploadFileData, I_UploadOptions, I_UploadValidationConfig, E_UploadType } from './upload.type.js';
 /**
  * Calculates the size of a file from a readable stream.
@@ -73,6 +73,7 @@ export declare function validateUpload(config: I_UploadValidationConfig, uploadC
  *
  * @param overrides - Optional configuration overrides to merge with the default configuration.
  * @returns A complete upload configuration object with defaults and any provided overrides.
+ * @since 3.13.0
  */
 export declare function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig;
 /**

package/dist/node/upload/upload.util.js CHANGED Viewed

@@ -1,14 +1,15 @@
 import { RESPONSE_STATUS as e } from "../../constant/response-status.js";
-import { E_UploadType as t } from "./upload.type.js";
-import { BYTES_PER_MB as n, DEFAULT_UPLOAD_CONFIG as r } from "./upload.constant.js";
-import { createWriteStream as i, mkdirSync as a, pathExistsSync as o } from "../fs/fs.util.js";
-import { dirname as s } from "../path/path.util.js";
-import { Buffer as c } from "node:buffer";
+import { log as t } from "../log/log.util.js";
+import { E_UploadType as n } from "./upload.type.js";
+import { BYTES_PER_MB as r, DEFAULT_UPLOAD_CONFIG as i } from "./upload.constant.js";
+import { createWriteStream as a, mkdirSync as o, pathExistsSync as s } from "../fs/fs.util.js";
+import { dirname as c } from "../path/path.util.js";
 import l from "node:path";
-import { Transform as u } from "node:stream";
-import { ReadableStream as d } from "node:stream/web";
+import { Buffer as u } from "node:buffer";
+import { Transform as d } from "node:stream";
+import { ReadableStream as f } from "node:stream/web";
 //#region src/node/upload/upload.util.ts
-async function f(e) {
+async function p(e) {
 	return new Promise((t, n) => {
 		let r = 0;
 		e.on("data", (e) => {
@@ -16,10 +17,11 @@ async function f(e) {
 		}), e.on("end", () => t(r)), e.on("error", n);
 	});
 }
-async function p(t, n, r) {
-	let i = await (await n).file, a = await f(i.createReadStream()), o = r ?? _(), s = g({
+async function m(t, n, r) {
+	let i = await (await n).file, a = await p(i.createReadStream()), o = r ?? v(), s = _({
 		filename: i.filename,
-		fileSize: a
+		fileSize: a,
+		mimetype: i.mimetype
 	}, o, t);
 	return s.isValid ? {
 		success: !0,
@@ -31,59 +33,63 @@ async function p(t, n, r) {
 		code: e.BAD_REQUEST.CODE
 	};
 }
-async function m(e, t, r) {
-	let i = (r ?? _())[e], a = await p(e, t, r);
+async function h(e, t, n) {
+	let i = (n ?? v())[e], a = await m(e, t, n);
 	if (!a.success) return a;
-	let { createReadStream: o } = a.result, s = i.sizeLimit, l = new u({ transform(e, t, r) {
-		s -= e.length, s < 0 ? r(/* @__PURE__ */ Error(`File size exceeds limit of ${i.sizeLimit / n}MB`)) : r(null, e);
-	} }), f = o().pipe(l);
+	let { createReadStream: o } = a.result, s = i.sizeLimit, c = new d({ transform(e, t, n) {
+		s -= e.length, s < 0 ? n(/* @__PURE__ */ Error(`File size exceeds limit of ${i.sizeLimit / r}MB`)) : n(null, e);
+	} }), l = o().pipe(c);
 	return {
 		success: !0,
-		result: new d({ start(e) {
-			f.on("data", (t) => {
-				e.enqueue(typeof t == "string" ? c.from(t) : t);
-			}), f.on("end", () => e.close()), f.on("error", (t) => e.error(t));
+		result: new f({ start(e) {
+			l.on("data", (t) => {
+				e.enqueue(typeof t == "string" ? u.from(t) : t);
+			}), l.on("end", () => e.close()), l.on("error", (t) => e.error(t));
 		} })
 	};
 }
-function h(e, t) {
+function g(e, t) {
 	let n = e.lastIndexOf(".");
 	if (n === -1) return !1;
 	let r = e.substring(n + 1).toLowerCase();
 	return t.includes(r);
 }
-function g(e, t, n) {
-	let { filename: r, fileSize: i } = e, { allowedExtensions: a, sizeLimit: o } = t[n];
-	if (!h(r, a)) return {
+function _(e, r, i) {
+	let { filename: a, fileSize: o, mimetype: s } = e, { allowedExtensions: c, sizeLimit: l } = r[i];
+	if (!g(a, c)) return {
 		isValid: !1,
-		error: `File extension not allowed for ${n.toLowerCase()} files. Allowed extensions: ${a.join(", ")}`
+		error: `File extension not allowed for ${i.toLowerCase()} files. Allowed extensions: ${c.join(", ")}`
 	};
-	if (i !== void 0 && i > o) {
-		let e = Math.round(o / (1024 * 1024));
+	if (o !== void 0 && o > l) {
+		let e = Math.round(l / (1024 * 1024));
 		return {
 			isValid: !1,
-			error: `File size exceeds limit for ${n.toLowerCase()} files. Maximum size: ${e}MB`
+			error: `File size exceeds limit for ${i.toLowerCase()} files. Maximum size: ${e}MB`
 		};
 	}
+	if (s) {
+		let e = "";
+		i === n.IMAGE ? e = "image/" : i === n.VIDEO ? e = "video/" : i === n.AUDIO && (e = "audio/"), e && !s.startsWith(e) && t.warn(`Advisory Mimetype Warning: File '${a}' (type: ${i}) has unexpected mimetype '${s}'. Expected prefix: '${e}'`);
+	}
 	return { isValid: !0 };
 }
-function _(e) {
+function v(e) {
 	return {
-		...r,
+		...i,
 		...e
 	};
 }
-async function v(n) {
-	let { path: r, file: c, config: u, type: d, baseDir: f } = n;
+async function y(t) {
+	let { path: r, file: i, config: u, type: d, baseDir: f } = t;
 	if (!r || typeof r != "string") return {
 		success: !1,
 		message: "Invalid path provided",
 		code: e.BAD_REQUEST.CODE
 	};
-	let m = l.resolve(r);
+	let p = l.resolve(r);
 	if (f) {
 		let t = l.resolve(f) + l.sep;
-		if (!m.startsWith(t) && m !== l.resolve(f)) return {
+		if (!p.startsWith(t) && p !== l.resolve(f)) return {
 			success: !1,
 			message: "Path traversal detected: path resolves outside the allowed base directory",
 			code: e.BAD_REQUEST.CODE
@@ -93,39 +99,43 @@ async function v(n) {
 		message: "Path traversal detected: \"..\" segments are not allowed",
 		code: e.BAD_REQUEST.CODE
 	};
-	if (!c || typeof c != "object") return {
+	if (!i || typeof i != "object") return {
 		success: !1,
 		message: "Invalid file provided",
 		code: e.BAD_REQUEST.CODE
 	};
 	if (u) {
-		let n = [
-			t.IMAGE,
-			t.VIDEO,
-			t.DOCUMENT,
-			t.OTHER
+		let t = [
+			n.IMAGE,
+			n.VIDEO,
+			n.DOCUMENT,
+			n.OTHER
 		];
-		for (let t of n) {
-			if (!u[t] || !Array.isArray(u[t].allowedExtensions) || u[t].allowedExtensions.length === 0) return {
+		for (let n of t) {
+			if (!u[n] || !Array.isArray(u[n].allowedExtensions) || u[n].allowedExtensions.length === 0) return {
 				success: !1,
-				message: `Invalid config for ${t.toLowerCase()} files`,
+				message: `Invalid config for ${n.toLowerCase()} files`,
 				code: e.BAD_REQUEST.CODE
 			};
-			if (typeof u[t].sizeLimit != "number" || u[t].sizeLimit <= 0) return {
+			if (typeof u[n].sizeLimit != "number" || u[n].sizeLimit <= 0) return {
 				success: !1,
-				message: `Invalid size limit for ${t.toLowerCase()} files`,
+				message: `Invalid size limit for ${n.toLowerCase()} files`,
 				code: e.BAD_REQUEST.CODE
 			};
 		}
 	}
 	try {
-		let t = await p(d, await c, u);
+		let t = await m(d, await i, u);
 		if (!t.success) return t;
-		let { createReadStream: n } = t.result, l = s(r);
-		o(l) || a(l, { recursive: !0 });
-		let f = n(), m = i(r);
-		return f.pipe(m), await new Promise((e, t) => {
-			m.on("finish", () => e()), m.on("error", t), f.on("error", t);
+		let { createReadStream: n } = t.result, l = c(r);
+		s(l) || o(l, { recursive: !0 });
+		let f = n(), p = a(r);
+		return f.pipe(p), await new Promise((e, t) => {
+			p.on("finish", () => e()), p.on("error", (e) => {
+				"destroy" in f && typeof f.destroy == "function" && f.destroy(), t(e);
+			}), f.on("error", (e) => {
+				p.destroy(), t(e);
+			});
 		}), {
 			success: !0,
 			result: r,
@@ -141,6 +151,6 @@ async function v(n) {
 	}
 }
 //#endregion
-export { _ as createUploadConfig, p as getAndValidateFile, f as getFileSizeFromStream, m as getFileWebStream, v as upload, h as validateFileExtension, g as validateUpload };
+export { v as createUploadConfig, m as getAndValidateFile, p as getFileSizeFromStream, h as getFileWebStream, y as upload, g as validateFileExtension, _ as validateUpload };
 //# sourceMappingURL=upload.util.js.map

package/dist/node/upload/upload.util.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"upload.util.js","names":[],"sources":["../../../src/node/upload/upload.util.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport nodePath from 'node:path';\nimport { Transform } from 'node:stream';\nimport { ReadableStream } from 'node:stream/web';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { I_UploadConfig, I_UploadFile, I_UploadFileData, I_UploadOptions, I_UploadTypeConfig, I_UploadValidationConfig } from './upload.type.js';\n\nimport { createWriteStream, mkdirSync, pathExistsSync } from '../fs/index.js';\nimport { dirname } from '../path/index.js';\nimport { BYTES_PER_MB, DEFAULT_UPLOAD_CONFIG } from './upload.constant.js';\nimport { E_UploadType } from './upload.type.js';\n\n/*\n Calculates the size of a file from a readable stream.\n * This function reads through the entire stream to determine the total byte size\n * by accumulating the length of each data chunk.\n \n @param stream - The readable stream to calculate the size for.\n * @returns A promise that resolves to the total size of the stream in bytes.\n /\nexport async function getFileSizeFromStream(stream: NodeJS.ReadableStream): Promise<number> {\n return new Promise((resolve, reject) => {\n let size = 0;\n stream.on('data', (chunk) => {\n size += chunk.length;\n });\n stream.on('end', () => resolve(size));\n stream.on('error', reject);\n });\n}\n\n/\n Extracts and validates file data from an upload file.\n * This function processes upload files by:\n * - Extracting file metadata and creating a readable stream\n * - Calculating the file size from the stream\n * - Validating file size and extension against upload configuration\n * - Returning a standardized response with success status and error codes\n * - Providing validated file data for further processing\n \n @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing validated file data or error information.\n /\nexport async function getAndValidateFile(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<I_UploadFileData>> {\n const fileData = await (await file).file;\n const stream = fileData.createReadStream();\n // Stream is consumed here for validation; callers use createReadStream() again for the actual write.\n // This is intentional — createReadStream() is a factory that yields a new stream per call.\n const fileSize = await getFileSizeFromStream(stream);\n const uploadConfig = config ?? createUploadConfig();\n\n const validationResult = validateUpload(\n { filename: fileData.filename, fileSize },\n uploadConfig,\n type,\n );\n\n if (!validationResult.isValid) {\n return {\n success: false,\n message: validationResult.error \|\| 'File validation failed',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n return {\n success: true,\n result: fileData,\n message: 'File validated successfully',\n };\n}\n\n/\n Creates a validated web-readable stream from an upload file with size validation.\n * This function processes file uploads for web environments by:\n * - Validating file data using getAndValidateFile function\n * - Creating a size validation transform stream to monitor upload progress\n * - Returning a web-compatible ReadableStream with real-time validation\n * - Providing standardized error responses for validation failures\n * - Wrapping the stream in a standardized response format\n \n @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing either a web ReadableStream or error information.\n /\nexport async function getFileWebStream(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<ReadableStream<Uint8Array>>> {\n const uploadConfig = config ?? createUploadConfig();\n const typeConfig = uploadConfig[type];\n\n const fileData = await getAndValidateFile(type, file, config);\n\n if (!fileData.success) {\n return fileData;\n }\n\n const { createReadStream } = fileData.result;\n\n let remainingBytes = typeConfig.sizeLimit;\n\n const sizeValidationStream = new Transform({\n transform(chunk: Buffer, _enc: BufferEncoding, cb) {\n remainingBytes -= chunk.length;\n\n if (remainingBytes < 0) {\n cb(new Error(`File size exceeds limit of ${typeConfig.sizeLimit / BYTES_PER_MB}MB`));\n }\n else {\n cb(null, chunk);\n }\n },\n });\n const originalStream = createReadStream();\n const validatedStream = originalStream.pipe(sizeValidationStream);\n\n return {\n success: true,\n result: new ReadableStream<Uint8Array>({\n start(controller) {\n validatedStream.on('data', (chunk: Buffer \| string) => {\n controller.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);\n });\n validatedStream.on('end', () => controller.close());\n validatedStream.on('error', (err: unknown) => controller.error(err));\n },\n }),\n };\n}\n\n/\n Validates if a file has an allowed extension.\n * This function extracts the file extension from the filename and checks if it's\n * included in the list of allowed extensions (case-insensitive comparison).\n \n @param filename - The filename to check for valid extension.\n * @param allowedExtensions - An array of allowed file extensions (without dots).\n * @returns True if the file extension is allowed, false otherwise.\n /\nexport function validateFileExtension(filename: string, allowedExtensions: string[]): boolean {\n const lastDotIndex = filename.lastIndexOf('.');\n\n if (lastDotIndex === -1) {\n return false;\n }\n\n const extension = filename.substring(lastDotIndex + 1).toLowerCase();\n\n return allowedExtensions.includes(extension);\n}\n\n/\n Validates an upload against the specified configuration.\n * This function performs comprehensive validation including:\n * - File extension validation against allowed extensions\n * - File size validation against size limits\n * - Returns detailed error messages for validation failures\n \n @param config - The validation configuration including filename and optional file size.\n * @param uploadConfig - The upload configuration containing allowed extensions and size limits.\n * @param uploadType - The type of upload being validated.\n * @returns An object indicating validation success and optional error message.\n /\nexport function validateUpload(\n config: I_UploadValidationConfig,\n uploadConfig: I_UploadConfig,\n uploadType: E_UploadType,\n): { isValid: boolean; error?: string } {\n const { filename, fileSize } = config;\n const typeConfig: I_UploadTypeConfig = uploadConfig[uploadType];\n\n const { allowedExtensions, sizeLimit } = typeConfig;\n\n if (!validateFileExtension(filename, allowedExtensions)) {\n return {\n isValid: false,\n error: `File extension not allowed for ${uploadType.toLowerCase()} files. Allowed extensions: ${allowedExtensions.join(', ')}`,\n };\n }\n\n if (fileSize !== undefined && fileSize > sizeLimit) {\n const maxSizeMB = Math.round(sizeLimit / (1024 1024));\n\n return {\n isValid: false,\n error: `File size exceeds limit for ${uploadType.toLowerCase()} files. Maximum size: ${maxSizeMB}MB`,\n };\n }\n\n return { isValid: true };\n}\n\n/*\n Creates a default upload configuration with predefined settings for different file types.\n * This function provides sensible defaults for image, video, document, and other file types,\n * including allowed extensions and size limits. The configuration can be customized with overrides.\n \n @param overrides - Optional configuration overrides to merge with the default configuration.\n * @returns A complete upload configuration object with defaults and any provided overrides.\n /\nexport function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig {\n return { ...DEFAULT_UPLOAD_CONFIG, ...overrides };\n}\n\n/\n Uploads a file with comprehensive validation and error handling.\n * This function processes file uploads with the following features:\n * - Input validation for path and file parameters\n * - Configuration validation for all upload types\n * - File validation using getAndValidateFile function\n * - Automatic directory creation\n * - Stream-based file writing\n * - Comprehensive error handling with standardized response codes\n \n @param options - Upload configuration including file, path, type, and optional validation config.\n * @returns A promise that resolves to a standardized response with success status, message, file path, and response codes.\n */\nexport async function upload(options: I_UploadOptions): Promise<I_Return<string>> {\n const { path, file, config, type, baseDir } = options;\n\n if (!path \|\| typeof path !== 'string') {\n return {\n success: false,\n message: 'Invalid path provided',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n // Security: Validate path is within allowed base directory to prevent path traversal.\n // When baseDir is provided, the resolved path must start with it.\n // When baseDir is not provided, reject any path containing \"..\" segments.\n const resolvedPath = nodePath.resolve(path);\n\n if (baseDir) {\n const resolvedBase = nodePath.resolve(baseDir) + nodePath.sep;\n if (!resolvedPath.startsWith(resolvedBase) && resolvedPath !== nodePath.resolve(baseDir)) {\n return {\n success: false,\n message: 'Path traversal detected: path resolves outside the allowed base directory',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n }\n else if (path.includes('..')) {\n return {\n success: false,\n message: 'Path traversal detected: \"..\" segments are not allowed',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n if (!file \|\| typeof file !== 'object') {\n return {\n success: false,\n message: 'Invalid file provided',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n if (config) {\n const requiredTypes = [E_UploadType.IMAGE, E_UploadType.VIDEO, E_UploadType.DOCUMENT, E_UploadType.OTHER];\n\n for (const requiredType of requiredTypes) {\n if (!config[requiredType] \|\| !Array.isArray(config[requiredType].allowedExtensions) \|\| config[requiredType].allowedExtensions.length === 0) {\n return {\n success: false,\n message: `Invalid config for ${requiredType.toLowerCase()} files`,\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n if (typeof config[requiredType].sizeLimit !== 'number' \|\| config[requiredType].sizeLimit <= 0) {\n return {\n success: false,\n message: `Invalid size limit for ${requiredType.toLowerCase()} files`,\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n }\n }\n\n try {\n const fileData = await getAndValidateFile(type, await file, config);\n\n if (!fileData.success) {\n return fileData;\n }\n\n const { createReadStream } = fileData.result;\n\n const dir = dirname(path);\n\n if (!pathExistsSync(dir)) {\n mkdirSync(dir, { recursive: true });\n }\n\n const writeStream = createReadStream();\n const out = createWriteStream(path);\n writeStream.pipe(out);\n\n await new Promise<void>((resolve, reject) => {\n out.on('finish', () => resolve());\n out.on('error', reject);\n writeStream.on('error', reject);\n });\n\n return {\n success: true,\n result: path,\n message: 'File uploaded successfully',\n code: RESPONSE_STATUS.OK.CODE,\n };\n }\n catch (error) {\n return {\n success: false,\n message: error instanceof Error ? error.message : 'File upload failed',\n code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n };\n }\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"upload.util.js","names":[],"sources":["../../../src/node/upload/upload.util.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport nodePath from 'node:path';\nimport { Transform } from 'node:stream';\nimport { ReadableStream } from 'node:stream/web';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { I_UploadConfig, I_UploadFile, I_UploadFileData, I_UploadOptions, I_UploadTypeConfig, I_UploadValidationConfig } from './upload.type.js';\n\nimport { createWriteStream, mkdirSync, pathExistsSync } from '../fs/index.js';\nimport { log } from '../log/index.js';\nimport { dirname } from '../path/index.js';\nimport { BYTES_PER_MB, DEFAULT_UPLOAD_CONFIG } from './upload.constant.js';\nimport { E_UploadType } from './upload.type.js';\n\n/*\n Calculates the size of a file from a readable stream.\n * This function reads through the entire stream to determine the total byte size\n * by accumulating the length of each data chunk.\n \n @param stream - The readable stream to calculate the size for.\n * @returns A promise that resolves to the total size of the stream in bytes.\n /\nexport async function getFileSizeFromStream(stream: NodeJS.ReadableStream): Promise<number> {\n return new Promise((resolve, reject) => {\n let size = 0;\n stream.on('data', (chunk) => {\n size += chunk.length;\n });\n stream.on('end', () => resolve(size));\n stream.on('error', reject);\n });\n}\n\n/\n Extracts and validates file data from an upload file.\n * This function processes upload files by:\n * - Extracting file metadata and creating a readable stream\n * - Calculating the file size from the stream\n * - Validating file size and extension against upload configuration\n * - Returning a standardized response with success status and error codes\n * - Providing validated file data for further processing\n \n @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing validated file data or error information.\n /\nexport async function getAndValidateFile(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<I_UploadFileData>> {\n const fileData = await (await file).file;\n const stream = fileData.createReadStream();\n // Stream is consumed here for validation; callers use createReadStream() again for the actual write.\n // This is intentional — createReadStream() is a factory that yields a new stream per call.\n const fileSize = await getFileSizeFromStream(stream);\n const uploadConfig = config ?? createUploadConfig();\n\n const validationResult = validateUpload(\n { filename: fileData.filename, fileSize, mimetype: fileData.mimetype },\n uploadConfig,\n type,\n );\n\n if (!validationResult.isValid) {\n return {\n success: false,\n message: validationResult.error \|\| 'File validation failed',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n return {\n success: true,\n result: fileData,\n message: 'File validated successfully',\n };\n}\n\n/\n Creates a validated web-readable stream from an upload file with size validation.\n * This function processes file uploads for web environments by:\n * - Validating file data using getAndValidateFile function\n * - Creating a size validation transform stream to monitor upload progress\n * - Returning a web-compatible ReadableStream with real-time validation\n * - Providing standardized error responses for validation failures\n * - Wrapping the stream in a standardized response format\n \n @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing either a web ReadableStream or error information.\n /\nexport async function getFileWebStream(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<ReadableStream<Uint8Array>>> {\n const uploadConfig = config ?? createUploadConfig();\n const typeConfig = uploadConfig[type];\n\n const fileData = await getAndValidateFile(type, file, config);\n\n if (!fileData.success) {\n return fileData;\n }\n\n const { createReadStream } = fileData.result;\n\n let remainingBytes = typeConfig.sizeLimit;\n\n const sizeValidationStream = new Transform({\n transform(chunk: Buffer, _enc: BufferEncoding, cb) {\n remainingBytes -= chunk.length;\n\n if (remainingBytes < 0) {\n cb(new Error(`File size exceeds limit of ${typeConfig.sizeLimit / BYTES_PER_MB}MB`));\n }\n else {\n cb(null, chunk);\n }\n },\n });\n const originalStream = createReadStream();\n const validatedStream = originalStream.pipe(sizeValidationStream);\n\n return {\n success: true,\n result: new ReadableStream<Uint8Array>({\n start(controller) {\n validatedStream.on('data', (chunk: Buffer \| string) => {\n controller.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);\n });\n validatedStream.on('end', () => controller.close());\n validatedStream.on('error', (err: unknown) => controller.error(err));\n },\n }),\n };\n}\n\n/\n Validates if a file has an allowed extension.\n * This function extracts the file extension from the filename and checks if it's\n * included in the list of allowed extensions (case-insensitive comparison).\n \n @param filename - The filename to check for valid extension.\n * @param allowedExtensions - An array of allowed file extensions (without dots).\n * @returns True if the file extension is allowed, false otherwise.\n /\nexport function validateFileExtension(filename: string, allowedExtensions: string[]): boolean {\n const lastDotIndex = filename.lastIndexOf('.');\n\n if (lastDotIndex === -1) {\n return false;\n }\n\n const extension = filename.substring(lastDotIndex + 1).toLowerCase();\n\n return allowedExtensions.includes(extension);\n}\n\n/\n Validates an upload against the specified configuration.\n * This function performs comprehensive validation including:\n * - File extension validation against allowed extensions\n * - File size validation against size limits\n * - Returns detailed error messages for validation failures\n \n @param config - The validation configuration including filename and optional file size.\n * @param uploadConfig - The upload configuration containing allowed extensions and size limits.\n * @param uploadType - The type of upload being validated.\n * @returns An object indicating validation success and optional error message.\n /\nexport function validateUpload(\n config: I_UploadValidationConfig,\n uploadConfig: I_UploadConfig,\n uploadType: E_UploadType,\n): { isValid: boolean; error?: string } {\n const { filename, fileSize, mimetype } = config;\n const typeConfig: I_UploadTypeConfig = uploadConfig[uploadType];\n\n const { allowedExtensions, sizeLimit } = typeConfig;\n\n if (!validateFileExtension(filename, allowedExtensions)) {\n return {\n isValid: false,\n error: `File extension not allowed for ${uploadType.toLowerCase()} files. Allowed extensions: ${allowedExtensions.join(', ')}`,\n };\n }\n\n if (fileSize !== undefined && fileSize > sizeLimit) {\n const maxSizeMB = Math.round(sizeLimit / (1024 1024));\n\n return {\n isValid: false,\n error: `File size exceeds limit for ${uploadType.toLowerCase()} files. Maximum size: ${maxSizeMB}MB`,\n };\n }\n\n if (mimetype) {\n let expectedPrefix = '';\n\n if (uploadType === E_UploadType.IMAGE) {\n expectedPrefix = 'image/';\n }\n else if (uploadType === E_UploadType.VIDEO) {\n expectedPrefix = 'video/';\n }\n else if (uploadType === E_UploadType.AUDIO) {\n expectedPrefix = 'audio/';\n }\n\n if (expectedPrefix && !mimetype.startsWith(expectedPrefix)) {\n // Advisory MIME validation - log warning but DO NOT reject\n log.warn(`Advisory Mimetype Warning: File '${filename}' (type: ${uploadType}) has unexpected mimetype '${mimetype}'. Expected prefix: '${expectedPrefix}'`);\n }\n }\n\n return { isValid: true };\n}\n\n/*\n Creates a default upload configuration with predefined settings for different file types.\n * This function provides sensible defaults for image, video, document, and other file types,\n * including allowed extensions and size limits. The configuration can be customized with overrides.\n \n @param overrides - Optional configuration overrides to merge with the default configuration.\n * @returns A complete upload configuration object with defaults and any provided overrides.\n * @since 3.13.0\n /\nexport function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig {\n return { ...DEFAULT_UPLOAD_CONFIG, ...overrides };\n}\n\n/\n Uploads a file with comprehensive validation and error handling.\n * This function processes file uploads with the following features:\n * - Input validation for path and file parameters\n * - Configuration validation for all upload types\n * - File validation using getAndValidateFile function\n * - Automatic directory creation\n * - Stream-based file writing\n * - Comprehensive error handling with standardized response codes\n \n @param options - Upload configuration including file, path, type, and optional validation config.\n * @returns A promise that resolves to a standardized response with success status, message, file path, and response codes.\n */\nexport async function upload(options: I_UploadOptions): Promise<I_Return<string>> {\n const { path, file, config, type, baseDir } = options;\n\n if (!path \|\| typeof path !== 'string') {\n return {\n success: false,\n message: 'Invalid path provided',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n // Security: Validate path is within allowed base directory to prevent path traversal.\n // When baseDir is provided, the resolved path must start with it.\n // When baseDir is not provided, reject any path containing \"..\" segments.\n const resolvedPath = nodePath.resolve(path);\n\n if (baseDir) {\n const resolvedBase = nodePath.resolve(baseDir) + nodePath.sep;\n if (!resolvedPath.startsWith(resolvedBase) && resolvedPath !== nodePath.resolve(baseDir)) {\n return {\n success: false,\n message: 'Path traversal detected: path resolves outside the allowed base directory',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n }\n else if (path.includes('..')) {\n return {\n success: false,\n message: 'Path traversal detected: \"..\" segments are not allowed',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n if (!file \|\| typeof file !== 'object') {\n return {\n success: false,\n message: 'Invalid file provided',\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n\n if (config) {\n const requiredTypes = [E_UploadType.IMAGE, E_UploadType.VIDEO, E_UploadType.DOCUMENT, E_UploadType.OTHER];\n\n for (const requiredType of requiredTypes) {\n if (!config[requiredType] \|\| !Array.isArray(config[requiredType].allowedExtensions) \|\| config[requiredType].allowedExtensions.length === 0) {\n return {\n success: false,\n message: `Invalid config for ${requiredType.toLowerCase()} files`,\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n if (typeof config[requiredType].sizeLimit !== 'number' \|\| config[requiredType].sizeLimit <= 0) {\n return {\n success: false,\n message: `Invalid size limit for ${requiredType.toLowerCase()} files`,\n code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n };\n }\n }\n }\n\n try {\n const fileData = await getAndValidateFile(type, await file, config);\n\n if (!fileData.success) {\n return fileData;\n }\n\n const { createReadStream } = fileData.result;\n\n const dir = dirname(path);\n\n if (!pathExistsSync(dir)) {\n mkdirSync(dir, { recursive: true });\n }\n\n const readStream = createReadStream();\n const out = createWriteStream(path);\n readStream.pipe(out);\n\n await new Promise<void>((resolve, reject) => {\n out.on('finish', () => resolve());\n out.on('error', (err) => {\n // Destroy the read stream to release resources if write fails\n if ('destroy' in readStream && typeof readStream.destroy === 'function') {\n readStream.destroy();\n }\n reject(err);\n });\n readStream.on('error', (err) => {\n out.destroy();\n reject(err);\n });\n });\n\n return {\n success: true,\n result: path,\n message: 'File uploaded successfully',\n code: RESPONSE_STATUS.OK.CODE,\n };\n }\n catch (error) {\n return {\n success: false,\n message: error instanceof Error ? error.message : 'File upload failed',\n code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n };\n }\n}\n"],"mappings":"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"}

package/dist/node/ws/index.d.ts CHANGED Viewed

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

package/dist/{src/node → node}/ws/ws.util.d.ts RENAMED Viewed

@@ -5,6 +5,13 @@ import { I_GraphqlWSOptions, I_WSOptions } from './ws.type.js';
  * This function creates a WebSocket server instance that can be attached to an HTTP server
  * and configured with a specific path for WebSocket connections.
  *
+ * @remarks
+ * **Authentication Warning:** When `sessionParser` is not provided, the WebSocket server
+ * has **no session-based authentication**. Any client that can reach the endpoint can
+ * establish a connection. Only omit `sessionParser` for truly public WebSocket endpoints
+ * (e.g., health-check or anonymous broadcast channels). For authenticated subscriptions,
+ * always provide a `sessionParser` to validate sessions on upgrade.
+ *
  * @param options - Configuration options including the HTTP server instance and WebSocket path.
  * @returns A configured WebSocket server instance ready to handle connections.
  */