@catbee/utils 0.0.1

package/build/esm/utils/dir.utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
+ *
+ * @param {string} dirPath - The directory path to ensure.
+ * @returns {Promise<void>} Resolves when the directory exists.
+ * @throws {Error} If directory cannot be created.
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Recursively lists all files in a directory.
+ *
+ * @param {string} dirPath - The base directory.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @returns {Promise<string[]>} Array of absolute file paths.
+ * @throws {Error} If the directory cannot be read.
+ */
+export declare function listFiles(dirPath: string, recursive?: boolean): Promise<string[]>;
+/**
+ * Deletes a directory and all its contents recursively (like `rm -rf`).
+ *
+ * @param {string} dirPath - Directory to delete.
+ * @returns {Promise<void>} Resolves when deletion is complete.
+ * @throws {Error} If deletion fails.
+ */
+export declare function deleteDirRecursive(dirPath: string): Promise<void>;
+/**
+ * Checks whether a given path is a directory.
+ *
+ * @param {string} pathStr - Path to check.
+ * @returns {Promise<boolean>} True if the path is a directory, else false.
+ */
+export declare function isDirectory(pathStr: string): Promise<boolean>;
+/**
+ * Recursively copies a directory and all its contents to a destination.
+ *
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ * @returns {Promise<void>} Resolves when copy is complete.
+ * @throws {Error} If source does not exist or copy fails.
+ */
+export declare function copyDir(src: string, dest: string): Promise<void>;
+/**
+ * Moves a directory to a new location by copying and deleting the original.
+ *
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ * @returns {Promise<void>} Resolves when move is complete.
+ * @throws {Error} If copy or deletion fails.
+ */
+export declare function moveDir(src: string, dest: string): Promise<void>;
+/**
+ * Empties a directory by deleting all files and subdirectories inside it.
+ *
+ * @param {string} dirPath - Path to the directory to empty.
+ * @returns {Promise<void>} Resolves when the directory has been emptied.
+ * @throws {Error} If files or subdirectories cannot be removed.
+ */
+export declare function emptyDir(dirPath: string): Promise<void>;
+/**
+ * Calculates the total size (in bytes) of all files in a directory (recursive).
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<number>} Total size in bytes.
+ * @throws {Error} If any file stats cannot be read.
+ */
+export declare function getDirSize(dirPath: string): Promise<number>;
+/**
+ * Watches a directory for file changes and calls a callback on each event.
+ *
+ * @param {string} dirPath - Directory path to watch.
+ * @param {(eventType: "rename" | "change", filename: string | null) => void} callback - Callback for each change event.
+ * @returns {() => void} A function to stop watching the directory.
+ */
+export declare function watchDir(dirPath: string, callback: (eventType: "rename" | "change", filename: string | null) => void): () => void;
+//# sourceMappingURL=dir.utils.d.ts.map

package/build/esm/utils/dir.utils.js

@@ -0,0 +1,400 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+/**
+ * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
+ *
+ * @param {string} dirPath - The directory path to ensure.
+ * @returns {Promise<void>} Resolves when the directory exists.
+ * @throws {Error} If directory cannot be created.
+ */
+export function ensureDir(dirPath) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fsp.mkdir(dirPath, { recursive: true })];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Recursively lists all files in a directory.
+ *
+ * @param {string} dirPath - The base directory.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @returns {Promise<string[]>} Array of absolute file paths.
+ * @throws {Error} If the directory cannot be read.
+ */
+export function listFiles(dirPath_1) {
+    return __awaiter(this, arguments, void 0, function (dirPath, recursive) {
+        var entries, files, entries_1, entries_1_1, entry, fullPath, nestedFiles, e_1_1;
+        var e_1, _a;
+        if (recursive === void 0) { recursive = false; }
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, fsp.readdir(dirPath, { withFileTypes: true })];
+                case 1:
+                    entries = _b.sent();
+                    files = [];
+                    _b.label = 2;
+                case 2:
+                    _b.trys.push([2, 8, 9, 10]);
+                    entries_1 = __values(entries), entries_1_1 = entries_1.next();
+                    _b.label = 3;
+                case 3:
+                    if (!!entries_1_1.done) return [3 /*break*/, 7];
+                    entry = entries_1_1.value;
+                    fullPath = path.join(dirPath, entry.name);
+                    if (!entry.isFile()) return [3 /*break*/, 4];
+                    files.push(fullPath);
+                    return [3 /*break*/, 6];
+                case 4:
+                    if (!(recursive && entry.isDirectory())) return [3 /*break*/, 6];
+                    return [4 /*yield*/, listFiles(fullPath, true)];
+                case 5:
+                    nestedFiles = _b.sent();
+                    files.push.apply(files, __spreadArray([], __read(nestedFiles), false));
+                    _b.label = 6;
+                case 6:
+                    entries_1_1 = entries_1.next();
+                    return [3 /*break*/, 3];
+                case 7: return [3 /*break*/, 10];
+                case 8:
+                    e_1_1 = _b.sent();
+                    e_1 = { error: e_1_1 };
+                    return [3 /*break*/, 10];
+                case 9:
+                    try {
+                        if (entries_1_1 && !entries_1_1.done && (_a = entries_1.return)) _a.call(entries_1);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                    return [7 /*endfinally*/];
+                case 10: return [2 /*return*/, files];
+            }
+        });
+    });
+}
+/**
+ * Deletes a directory and all its contents recursively (like `rm -rf`).
+ *
+ * @param {string} dirPath - Directory to delete.
+ * @returns {Promise<void>} Resolves when deletion is complete.
+ * @throws {Error} If deletion fails.
+ */
+export function deleteDirRecursive(dirPath) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fsp.rm(dirPath, { recursive: true, force: true })];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Checks whether a given path is a directory.
+ *
+ * @param {string} pathStr - Path to check.
+ * @returns {Promise<boolean>} True if the path is a directory, else false.
+ */
+export function isDirectory(pathStr) {
+    return __awaiter(this, void 0, void 0, function () {
+        var stat, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    _b.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, fsp.stat(pathStr)];
+                case 1:
+                    stat = _b.sent();
+                    return [2 /*return*/, stat.isDirectory()];
+                case 2:
+                    _a = _b.sent();
+                    return [2 /*return*/, false];
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Recursively copies a directory and all its contents to a destination.
+ *
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ * @returns {Promise<void>} Resolves when copy is complete.
+ * @throws {Error} If source does not exist or copy fails.
+ */
+export function copyDir(src, dest) {
+    return __awaiter(this, void 0, void 0, function () {
+        var entries, entries_2, entries_2_1, entry, srcPath, destPath, e_2_1;
+        var e_2, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, ensureDir(dest)];
+                case 1:
+                    _b.sent();
+                    return [4 /*yield*/, fsp.readdir(src, { withFileTypes: true })];
+                case 2:
+                    entries = _b.sent();
+                    _b.label = 3;
+                case 3:
+                    _b.trys.push([3, 10, 11, 12]);
+                    entries_2 = __values(entries), entries_2_1 = entries_2.next();
+                    _b.label = 4;
+                case 4:
+                    if (!!entries_2_1.done) return [3 /*break*/, 9];
+                    entry = entries_2_1.value;
+                    srcPath = path.join(src, entry.name);
+                    destPath = path.join(dest, entry.name);
+                    if (!entry.isDirectory()) return [3 /*break*/, 6];
+                    return [4 /*yield*/, copyDir(srcPath, destPath)];
+                case 5:
+                    _b.sent();
+                    return [3 /*break*/, 8];
+                case 6: return [4 /*yield*/, fsp.copyFile(srcPath, destPath)];
+                case 7:
+                    _b.sent();
+                    _b.label = 8;
+                case 8:
+                    entries_2_1 = entries_2.next();
+                    return [3 /*break*/, 4];
+                case 9: return [3 /*break*/, 12];
+                case 10:
+                    e_2_1 = _b.sent();
+                    e_2 = { error: e_2_1 };
+                    return [3 /*break*/, 12];
+                case 11:
+                    try {
+                        if (entries_2_1 && !entries_2_1.done && (_a = entries_2.return)) _a.call(entries_2);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                    return [7 /*endfinally*/];
+                case 12: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Moves a directory to a new location by copying and deleting the original.
+ *
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ * @returns {Promise<void>} Resolves when move is complete.
+ * @throws {Error} If copy or deletion fails.
+ */
+export function moveDir(src, dest) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, copyDir(src, dest)];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, deleteDirRecursive(src)];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Empties a directory by deleting all files and subdirectories inside it.
+ *
+ * @param {string} dirPath - Path to the directory to empty.
+ * @returns {Promise<void>} Resolves when the directory has been emptied.
+ * @throws {Error} If files or subdirectories cannot be removed.
+ */
+export function emptyDir(dirPath) {
+    return __awaiter(this, void 0, void 0, function () {
+        var entries, entries_3, entries_3_1, entry, entryPath, e_3_1;
+        var e_3, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, fsp.readdir(dirPath, { withFileTypes: true })];
+                case 1:
+                    entries = _b.sent();
+                    _b.label = 2;
+                case 2:
+                    _b.trys.push([2, 9, 10, 11]);
+                    entries_3 = __values(entries), entries_3_1 = entries_3.next();
+                    _b.label = 3;
+                case 3:
+                    if (!!entries_3_1.done) return [3 /*break*/, 8];
+                    entry = entries_3_1.value;
+                    entryPath = path.join(dirPath, entry.name);
+                    if (!entry.isDirectory()) return [3 /*break*/, 5];
+                    return [4 /*yield*/, fsp.rm(entryPath, { recursive: true, force: true })];
+                case 4:
+                    _b.sent();
+                    return [3 /*break*/, 7];
+                case 5: return [4 /*yield*/, fsp.unlink(entryPath)];
+                case 6:
+                    _b.sent();
+                    _b.label = 7;
+                case 7:
+                    entries_3_1 = entries_3.next();
+                    return [3 /*break*/, 3];
+                case 8: return [3 /*break*/, 11];
+                case 9:
+                    e_3_1 = _b.sent();
+                    e_3 = { error: e_3_1 };
+                    return [3 /*break*/, 11];
+                case 10:
+                    try {
+                        if (entries_3_1 && !entries_3_1.done && (_a = entries_3.return)) _a.call(entries_3);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                    return [7 /*endfinally*/];
+                case 11: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Calculates the total size (in bytes) of all files in a directory (recursive).
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<number>} Total size in bytes.
+ * @throws {Error} If any file stats cannot be read.
+ */
+export function getDirSize(dirPath) {
+    return __awaiter(this, void 0, void 0, function () {
+        var total, entries, entries_4, entries_4_1, entry, entryPath, _a, stat, e_4_1;
+        var e_4, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    total = 0;
+                    return [4 /*yield*/, fsp.readdir(dirPath, { withFileTypes: true })];
+                case 1:
+                    entries = _c.sent();
+                    _c.label = 2;
+                case 2:
+                    _c.trys.push([2, 9, 10, 11]);
+                    entries_4 = __values(entries), entries_4_1 = entries_4.next();
+                    _c.label = 3;
+                case 3:
+                    if (!!entries_4_1.done) return [3 /*break*/, 8];
+                    entry = entries_4_1.value;
+                    entryPath = path.join(dirPath, entry.name);
+                    if (!entry.isDirectory()) return [3 /*break*/, 5];
+                    _a = total;
+                    return [4 /*yield*/, getDirSize(entryPath)];
+                case 4:
+                    total = _a + _c.sent();
+                    return [3 /*break*/, 7];
+                case 5: return [4 /*yield*/, fsp.stat(entryPath)];
+                case 6:
+                    stat = _c.sent();
+                    total += stat.size;
+                    _c.label = 7;
+                case 7:
+                    entries_4_1 = entries_4.next();
+                    return [3 /*break*/, 3];
+                case 8: return [3 /*break*/, 11];
+                case 9:
+                    e_4_1 = _c.sent();
+                    e_4 = { error: e_4_1 };
+                    return [3 /*break*/, 11];
+                case 10:
+                    try {
+                        if (entries_4_1 && !entries_4_1.done && (_b = entries_4.return)) _b.call(entries_4);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                    return [7 /*endfinally*/];
+                case 11: return [2 /*return*/, total];
+            }
+        });
+    });
+}
+/**
+ * Watches a directory for file changes and calls a callback on each event.
+ *
+ * @param {string} dirPath - Directory path to watch.
+ * @param {(eventType: "rename" | "change", filename: string | null) => void} callback - Callback for each change event.
+ * @returns {() => void} A function to stop watching the directory.
+ */
+export function watchDir(dirPath, callback) {
+    var watcher = fs.watch(dirPath, function (eventType, filename) {
+        callback(eventType, filename);
+    });
+    return function () { return watcher.close(); };
+}
+//# sourceMappingURL=dir.utils.js.map

package/build/esm/utils/dir.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dir.utils.js","sourceRoot":"","sources":["../../../src/utils/dir.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"fs\";\nimport fsp from \"fs/promises\";\nimport path from \"path\";\n\n/**\n * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).\n *\n * @param {string} dirPath - The directory path to ensure.\n * @returns {Promise<void>} Resolves when the directory exists.\n * @throws {Error} If directory cannot be created.\n */\nexport async function ensureDir(dirPath: string): Promise<void> {\n  await fsp.mkdir(dirPath, { recursive: true });\n}\n\n/**\n * Recursively lists all files in a directory.\n *\n * @param {string} dirPath - The base directory.\n * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.\n * @returns {Promise<string[]>} Array of absolute file paths.\n * @throws {Error} If the directory cannot be read.\n */\nexport async function listFiles(\n  dirPath: string,\n  recursive = false,\n): Promise<string[]> {\n  const entries = await fsp.readdir(dirPath, { withFileTypes: true });\n  const files: string[] = [];\n\n  for (const entry of entries) {\n    const fullPath = path.join(dirPath, entry.name);\n\n    if (entry.isFile()) {\n      files.push(fullPath);\n    } else if (recursive && entry.isDirectory()) {\n      const nestedFiles = await listFiles(fullPath, true);\n      files.push(...nestedFiles);\n    }\n  }\n\n  return files;\n}\n\n/**\n * Deletes a directory and all its contents recursively (like `rm -rf`).\n *\n * @param {string} dirPath - Directory to delete.\n * @returns {Promise<void>} Resolves when deletion is complete.\n * @throws {Error} If deletion fails.\n */\nexport async function deleteDirRecursive(dirPath: string): Promise<void> {\n  await fsp.rm(dirPath, { recursive: true, force: true });\n}\n\n/**\n * Checks whether a given path is a directory.\n *\n * @param {string} pathStr - Path to check.\n * @returns {Promise<boolean>} True if the path is a directory, else false.\n */\nexport async function isDirectory(pathStr: string): Promise<boolean> {\n  try {\n    const stat = await fsp.stat(pathStr);\n    return stat.isDirectory();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Recursively copies a directory and all its contents to a destination.\n *\n * @param {string} src - Source directory path.\n * @param {string} dest - Destination directory path.\n * @returns {Promise<void>} Resolves when copy is complete.\n * @throws {Error} If source does not exist or copy fails.\n */\nexport async function copyDir(src: string, dest: string): Promise<void> {\n  await ensureDir(dest);\n  const entries = await fsp.readdir(src, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const srcPath = path.join(src, entry.name);\n    const destPath = path.join(dest, entry.name);\n\n    if (entry.isDirectory()) {\n      await copyDir(srcPath, destPath);\n    } else {\n      await fsp.copyFile(srcPath, destPath);\n    }\n  }\n}\n\n/**\n * Moves a directory to a new location by copying and deleting the original.\n *\n * @param {string} src - Source directory path.\n * @param {string} dest - Destination directory path.\n * @returns {Promise<void>} Resolves when move is complete.\n * @throws {Error} If copy or deletion fails.\n */\nexport async function moveDir(src: string, dest: string): Promise<void> {\n  await copyDir(src, dest);\n  await deleteDirRecursive(src);\n}\n\n/**\n * Empties a directory by deleting all files and subdirectories inside it.\n *\n * @param {string} dirPath - Path to the directory to empty.\n * @returns {Promise<void>} Resolves when the directory has been emptied.\n * @throws {Error} If files or subdirectories cannot be removed.\n */\nexport async function emptyDir(dirPath: string): Promise<void> {\n  const entries = await fsp.readdir(dirPath, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const entryPath = path.join(dirPath, entry.name);\n\n    if (entry.isDirectory()) {\n      await fsp.rm(entryPath, { recursive: true, force: true });\n    } else {\n      await fsp.unlink(entryPath);\n    }\n  }\n}\n\n/**\n * Calculates the total size (in bytes) of all files in a directory (recursive).\n *\n * @param {string} dirPath - Path to the directory.\n * @returns {Promise<number>} Total size in bytes.\n * @throws {Error} If any file stats cannot be read.\n */\nexport async function getDirSize(dirPath: string): Promise<number> {\n  let total = 0;\n  const entries = await fsp.readdir(dirPath, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const entryPath = path.join(dirPath, entry.name);\n    if (entry.isDirectory()) {\n      total += await getDirSize(entryPath);\n    } else {\n      const stat = await fsp.stat(entryPath);\n      total += stat.size;\n    }\n  }\n\n  return total;\n}\n\n/**\n * Watches a directory for file changes and calls a callback on each event.\n *\n * @param {string} dirPath - Directory path to watch.\n * @param {(eventType: \"rename\" | \"change\", filename: string | null) => void} callback - Callback for each change event.\n * @returns {() => void} A function to stop watching the directory.\n */\nexport function watchDir(\n  dirPath: string,\n  callback: (eventType: \"rename\" | \"change\", filename: string | null) => void,\n): () => void {\n  const watcher = fs.watch(dirPath, (eventType, filename) => {\n    callback(eventType, filename);\n  });\n\n  return () => watcher.close();\n}\n"]}

package/build/esm/utils/env.utils.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Enum representing valid application environments.
+ */
+export declare enum Environment {
+    PRODUCTION = "production",
+    DEVELOPMENT = "development",
+    STAGING = "staging",
+    TESTING = "testing"
+}
+/**
+ * Utility class for accessing and managing environment variables.
+ * Provides typed getters with fallback defaults and validation.
+ */
+export declare class Env {
+    /**
+     * Checks if the current NODE_ENV is 'development'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
+     */
+    static isDev(): boolean;
+    /**
+     * Sets an environment variable (only affects runtime memory).
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} value - The value to set.
+     */
+    static set(key: string, value: string): void;
+    /**
+     * Returns all environment variables as an object.
+     *
+     * @returns {object} The current `process.env` object.
+     */
+    static getAll(): object;
+    /**
+     * Retrieves a string environment variable with a fallback default.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Value to return if the key is missing.
+     * @returns {string | undefined} The env value or the fallback.
+     */
+    static get(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Retrieves a string environment variable and throws if it's missing.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {string} The environment variable's value.
+     * @throws {Error} If the variable is not defined.
+     */
+    static getRequired(key: string): string;
+    /**
+     * Retrieves an environment variable as a number, or returns a default.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} defaultValue - Fallback number if key is not present.
+     * @returns {number} Parsed numeric value or default.
+     * @throws {Error} If the value is not a valid number.
+     */
+    static getNumber(key: string, defaultValue: number): number;
+    /**
+     * Retrieves a required environment variable as a number.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {number} Parsed number.
+     * @throws {Error} If the value is missing or not a number.
+     */
+    static getNumberRequired(key: string): number;
+    /**
+     * Retrieves an environment variable as a boolean.
+     * Accepts `true`, `1`, `yes`, `on` as true; `false`, `0`, `no`, `off` as false.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {boolean} [defaultValue=false] - Optional fallback value if key is missing.
+     * @returns {boolean} Parsed boolean.
+     * @throws {Error} If the value is not a recognized boolean string.
+     */
+    static getBoolean(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Retrieves a required environment variable as a boolean.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {boolean} Parsed boolean value.
+     * @throws {Error} If missing or invalid.
+     */
+    static getBooleanRequired(key: string): boolean;
+    /**
+     * Parses a stringified JSON object from an environment variable.
+     *
+     * @typeParam T - The type to parse as (defaults to `object`).
+     * @param {string} key - The environment variable key.
+     * @param {T} defaultValue - Value to return if key is missing.
+     * @returns {T} Parsed object or default.
+     * @throws {Error} If the value is not valid JSON.
+     */
+    static getJSON<T extends object = object>(key: string, defaultValue: T): T;
+    /**
+     * Parses a comma-separated string as an array.
+     *
+     * @typeParam T - The item type (optional, defaults to string).
+     * @param {string} key - The environment variable key.
+     * @param {T[]} [defaultValue=[]] - Array to return if value is empty or missing.
+     * @param {string} [splitter=','] - Delimiter to split on.
+     * @returns {string[] | T[]} An array of strings.
+     */
+    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string): string[] | T[];
+    /**
+     * Retrieves an enum-like environment variable value, validating against allowed values.
+     *
+     * @typeParam T - The allowed value type (string literal types).
+     * @param {string} key - The environment variable key.
+     * @param {T[]} allowedValues - Array of accepted string values.
+     * @param {T} [defaultValue] - Optional fallback value.
+     * @returns {T} The validated environment value.
+     * @throws {Error} If missing or invalid.
+     */
+    static getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T;
+    /**
+     * Checks whether the specified environment variable exists.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {boolean} `true` if the variable is defined, otherwise `false`.
+     */
+    static has(key: string): boolean;
+    /**
+     * Deletes the given environment variable (useful in tests).
+     *
+     * @param {string} key - The environment variable key to delete.
+     * @returns {void}
+     */
+    static delete(key: string): void;
+}
+//# sourceMappingURL=env.utils.d.ts.map