@catbee/utils 0.0.1 → 0.0.2

package/build/src/utils/decorators.utils.js

@@ -0,0 +1,165 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-unused-vars */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Res = exports.Req = exports.Body = exports.Param = exports.Query = exports.Connect = exports.Trace = exports.Head = exports.Options = exports.Delete = exports.Patch = exports.Put = exports.Post = exports.Get = void 0;
+exports.Controller = Controller;
+exports.Use = Use;
+exports.HttpCode = HttpCode;
+exports.Header = Header;
+exports.Before = Before;
+exports.After = After;
+exports.registerControllers = registerControllers;
+require("reflect-metadata");
+// --- End sample Express interfaces ---
+const ROUTES_KEY = Symbol("routes");
+const MIDDLEWARE_KEY = Symbol("middlewares");
+const PARAMS_KEY = Symbol("params");
+// ---- Route Decorators ----
+function createRouteDecorator(method) {
+    return (path) => {
+        return (target, propertyKey, descriptor) => {
+            const routes = Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];
+            routes.push({
+                path,
+                method,
+                handlerName: propertyKey,
+            });
+            Reflect.defineMetadata(ROUTES_KEY, routes, target.constructor);
+        };
+    };
+}
+exports.Get = createRouteDecorator("get");
+exports.Post = createRouteDecorator("post");
+exports.Put = createRouteDecorator("put");
+exports.Patch = createRouteDecorator("patch");
+exports.Delete = createRouteDecorator("delete");
+exports.Options = createRouteDecorator("options");
+exports.Head = createRouteDecorator("head");
+exports.Trace = createRouteDecorator("trace");
+exports.Connect = createRouteDecorator("connect");
+// ---- Controller Decorator ----
+function Controller(basePath) {
+    return (target) => {
+        Reflect.defineMetadata("basePath", basePath, target);
+    };
+}
+// ---- Middleware Decorator ----
+function Use(...middlewares) {
+    return (target, propertyKey, descriptor) => {
+        const existing = Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey) || [];
+        Reflect.defineMetadata(MIDDLEWARE_KEY, [...existing, ...middlewares], target, propertyKey);
+    };
+}
+// ---- Parameter Decorators ----
+function createParamDecorator(type, key) {
+    return (paramKey) => {
+        return (target, propertyKey, parameterIndex) => {
+            const params = Reflect.getMetadata(PARAMS_KEY, target, propertyKey) || [];
+            // Ensure parameters are ordered by index
+            params.push({ index: parameterIndex, type, key: paramKey || key });
+            params.sort((a, b) => a.index - b.index);
+            Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey);
+        };
+    };
+}
+exports.Query = createParamDecorator("query");
+exports.Param = createParamDecorator("param");
+exports.Body = createParamDecorator("body");
+exports.Req = createParamDecorator("req");
+exports.Res = createParamDecorator("res");
+// Custom HTTP status code decorator
+const HTTP_CODE_KEY = Symbol("httpCode");
+function HttpCode(status) {
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(HTTP_CODE_KEY, status, target, propertyKey);
+    };
+}
+// Custom header decorator
+const HEADER_KEY = Symbol("headers");
+function Header(name, value) {
+    return (target, propertyKey, descriptor) => {
+        const headers = Reflect.getMetadata(HEADER_KEY, target, propertyKey) || {};
+        headers[name] = value;
+        Reflect.defineMetadata(HEADER_KEY, headers, target, propertyKey);
+    };
+}
+// Before/After hooks (not Express middleware, but can be used for logging, etc.)
+const BEFORE_KEY = Symbol("before");
+const AFTER_KEY = Symbol("after");
+function Before(fn) {
+    return (target, propertyKey, descriptor) => {
+        const hooks = Reflect.getMetadata(BEFORE_KEY, target, propertyKey) || [];
+        hooks.push(fn);
+        Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey);
+    };
+}
+function After(fn) {
+    return (target, propertyKey, descriptor) => {
+        const hooks = Reflect.getMetadata(AFTER_KEY, target, propertyKey) || [];
+        hooks.push(fn);
+        Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey);
+    };
+}
+// ---- Register Controllers ----
+function registerControllers(router, controllers) {
+    controllers.forEach((ControllerClass) => {
+        const instance = new ControllerClass();
+        const basePath = Reflect.getMetadata("basePath", ControllerClass) || "";
+        const routes = Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];
+        routes.forEach(({ path, method, handlerName }) => {
+            const middlewares = Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];
+            const params = Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];
+            const httpCode = Reflect.getMetadata(HTTP_CODE_KEY, instance, handlerName);
+            const headers = Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};
+            const beforeHooks = Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];
+            const afterHooks = Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];
+            const handler = async (req, res, next) => {
+                var _a, _b;
+                try {
+                    for (const fn of beforeHooks)
+                        await fn(req, res);
+                    const args = [];
+                    if (params.length) {
+                        params.forEach(({ index, type, key }) => {
+                            var _a;
+                            switch (type) {
+                                case "query":
+                                    args[index] = key ? req.query[key] : req.query;
+                                    break;
+                                case "param":
+                                    args[index] = key ? req.params[key] : req.params;
+                                    break;
+                                case "body":
+                                    args[index] = key ? (_a = req.body) === null || _a === void 0 ? void 0 : _a[key] : req.body;
+                                    break;
+                                case "req":
+                                    args[index] = req;
+                                    break;
+                                case "res":
+                                    args[index] = res;
+                                    break;
+                            }
+                        });
+                    }
+                    const result = instance[handlerName](...args);
+                    // Support both sync and async handlers
+                    const awaited = result instanceof Promise ? await result : result;
+                    if (!res.headersSent && typeof awaited !== "undefined") {
+                        if (httpCode)
+                            (_a = res.status) === null || _a === void 0 ? void 0 : _a.call(res, httpCode);
+                        for (const [k, v] of Object.entries(headers))
+                            (_b = res.set) === null || _b === void 0 ? void 0 : _b.call(res, k, v);
+                        res.json(awaited);
+                    }
+                    for (const fn of afterHooks)
+                        await fn(req, res, awaited);
+                }
+                catch (err) {
+                    next(err);
+                }
+            };
+            router[method](basePath + path, ...middlewares, handler);
+        });
+    });
+}
+//# sourceMappingURL=decorators.utils.js.map

package/build/src/utils/decorators.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.utils.js","sourceRoot":"","sources":["../../../src/utils/decorators.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n\nimport \"reflect-metadata\";\n\n// --- Sample Express interfaces for type safety ---\nexport interface Request {\n  query: any;\n  params: any;\n  body?: any;\n  [key: string]: any;\n}\nexport interface Response {\n  json: (body: any) => void;\n  headersSent: boolean;\n  [key: string]: any;\n}\nexport type NextFunction = (err?: any) => void;\nexport type RequestHandler = (\n  req: Request,\n  res: Response,\n  next: NextFunction,\n) => any;\nexport interface Router {\n  [method: string]: (path: string, ...handlers: RequestHandler[]) => void;\n}\n// --- End sample Express interfaces ---\n\nconst ROUTES_KEY = Symbol(\"routes\");\nconst MIDDLEWARE_KEY = Symbol(\"middlewares\");\nconst PARAMS_KEY = Symbol(\"params\");\n\nexport type HttpMethod =\n  | \"get\"\n  | \"post\"\n  | \"put\"\n  | \"patch\"\n  | \"delete\"\n  | \"options\"\n  | \"head\"\n  | \"trace\"\n  | \"connect\";\n\ninterface RouteDefinition {\n  path: string;\n  method: HttpMethod;\n  handlerName: string;\n}\n\ninterface ParamDefinition {\n  index: number;\n  type: \"query\" | \"param\" | \"body\" | \"req\" | \"res\";\n  key?: string;\n}\n\n// ---- Route Decorators ----\nfunction createRouteDecorator(method: HttpMethod) {\n  return (path: string): MethodDecorator => {\n    return (target, propertyKey, descriptor) => {\n      const routes: RouteDefinition[] =\n        Reflect.getMetadata(ROUTES_KEY, target.constructor) || [];\n      routes.push({\n        path,\n        method,\n        handlerName: propertyKey as string,\n      });\n      Reflect.defineMetadata(ROUTES_KEY, routes, target.constructor);\n    };\n  };\n}\n\nexport const Get = createRouteDecorator(\"get\");\nexport const Post = createRouteDecorator(\"post\");\nexport const Put = createRouteDecorator(\"put\");\nexport const Patch = createRouteDecorator(\"patch\");\nexport const Delete = createRouteDecorator(\"delete\");\nexport const Options = createRouteDecorator(\"options\");\nexport const Head = createRouteDecorator(\"head\");\nexport const Trace = createRouteDecorator(\"trace\");\nexport const Connect = createRouteDecorator(\"connect\");\n\n// ---- Controller Decorator ----\nexport function Controller(basePath: string): ClassDecorator {\n  return (target) => {\n    Reflect.defineMetadata(\"basePath\", basePath, target);\n  };\n}\n\n// ---- Middleware Decorator ----\nexport function Use(...middlewares: RequestHandler[]): MethodDecorator {\n  return (target, propertyKey, descriptor) => {\n    const existing: RequestHandler[] =\n      Reflect.getMetadata(MIDDLEWARE_KEY, target, propertyKey as string) || [];\n    Reflect.defineMetadata(\n      MIDDLEWARE_KEY,\n      [...existing, ...middlewares],\n      target,\n      propertyKey as string,\n    );\n  };\n}\n\n// ---- Parameter Decorators ----\nfunction createParamDecorator(type: ParamDefinition[\"type\"], key?: string) {\n  return (paramKey?: string): ParameterDecorator => {\n    return (target, propertyKey, parameterIndex) => {\n      const params: ParamDefinition[] =\n        Reflect.getMetadata(PARAMS_KEY, target, propertyKey as string) || [];\n      // Ensure parameters are ordered by index\n      params.push({ index: parameterIndex, type, key: paramKey || key });\n      params.sort((a, b) => a.index - b.index);\n      Reflect.defineMetadata(PARAMS_KEY, params, target, propertyKey as string);\n    };\n  };\n}\n\nexport const Query = createParamDecorator(\"query\");\nexport const Param = createParamDecorator(\"param\");\nexport const Body = createParamDecorator(\"body\");\nexport const Req = createParamDecorator(\"req\");\nexport const Res = createParamDecorator(\"res\");\n\n// Custom HTTP status code decorator\nconst HTTP_CODE_KEY = Symbol(\"httpCode\");\nexport function HttpCode(status: number): MethodDecorator {\n  return (target, propertyKey, descriptor) => {\n    Reflect.defineMetadata(\n      HTTP_CODE_KEY,\n      status,\n      target,\n      propertyKey as string,\n    );\n  };\n}\n\n// Custom header decorator\nconst HEADER_KEY = Symbol(\"headers\");\nexport function Header(name: string, value: string): MethodDecorator {\n  return (target, propertyKey, descriptor) => {\n    const headers: Record<string, string> =\n      Reflect.getMetadata(HEADER_KEY, target, propertyKey as string) || {};\n    headers[name] = value;\n    Reflect.defineMetadata(HEADER_KEY, headers, target, propertyKey as string);\n  };\n}\n\n// Before/After hooks (not Express middleware, but can be used for logging, etc.)\nconst BEFORE_KEY = Symbol(\"before\");\nconst AFTER_KEY = Symbol(\"after\");\nexport function Before(fn: Function): MethodDecorator {\n  return (target, propertyKey, descriptor) => {\n    const hooks: Function[] =\n      Reflect.getMetadata(BEFORE_KEY, target, propertyKey as string) || [];\n    hooks.push(fn);\n    Reflect.defineMetadata(BEFORE_KEY, hooks, target, propertyKey as string);\n  };\n}\nexport function After(fn: Function): MethodDecorator {\n  return (target, propertyKey, descriptor) => {\n    const hooks: Function[] =\n      Reflect.getMetadata(AFTER_KEY, target, propertyKey as string) || [];\n    hooks.push(fn);\n    Reflect.defineMetadata(AFTER_KEY, hooks, target, propertyKey as string);\n  };\n}\n\n// ---- Register Controllers ----\nexport function registerControllers(router: Router, controllers: any[]) {\n  controllers.forEach((ControllerClass) => {\n    const instance = new ControllerClass();\n    const basePath: string =\n      Reflect.getMetadata(\"basePath\", ControllerClass) || \"\";\n    const routes: RouteDefinition[] =\n      Reflect.getMetadata(ROUTES_KEY, ControllerClass) || [];\n\n    routes.forEach(({ path, method, handlerName }) => {\n      const middlewares: RequestHandler[] =\n        Reflect.getMetadata(MIDDLEWARE_KEY, instance, handlerName) || [];\n      const params: ParamDefinition[] =\n        Reflect.getMetadata(PARAMS_KEY, instance, handlerName) || [];\n\n      const httpCode: number | undefined = Reflect.getMetadata(\n        HTTP_CODE_KEY,\n        instance,\n        handlerName,\n      );\n      const headers: Record<string, string> =\n        Reflect.getMetadata(HEADER_KEY, instance, handlerName) || {};\n      const beforeHooks: Function[] =\n        Reflect.getMetadata(BEFORE_KEY, instance, handlerName) || [];\n      const afterHooks: Function[] =\n        Reflect.getMetadata(AFTER_KEY, instance, handlerName) || [];\n\n      const handler: RequestHandler = async (req, res, next) => {\n        try {\n          for (const fn of beforeHooks) await fn(req, res);\n          const args: any[] = [];\n          if (params.length) {\n            params.forEach(({ index, type, key }) => {\n              switch (type) {\n                case \"query\":\n                  args[index] = key ? req.query[key] : req.query;\n                  break;\n                case \"param\":\n                  args[index] = key ? req.params[key] : req.params;\n                  break;\n                case \"body\":\n                  args[index] = key ? req.body?.[key] : req.body;\n                  break;\n                case \"req\":\n                  args[index] = req;\n                  break;\n                case \"res\":\n                  args[index] = res;\n                  break;\n              }\n            });\n          }\n          const result = (instance as any)[handlerName](...args);\n          // Support both sync and async handlers\n          const awaited = result instanceof Promise ? await result : result;\n          if (!res.headersSent && typeof awaited !== \"undefined\") {\n            if (httpCode) res.status?.(httpCode);\n            for (const [k, v] of Object.entries(headers)) res.set?.(k, v);\n            res.json(awaited);\n          }\n          for (const fn of afterHooks) await fn(req, res, awaited);\n        } catch (err) {\n          next(err);\n        }\n      };\n\n      (router as any)[method](basePath + path, ...middlewares, handler);\n    });\n  });\n}\n"]}

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

@@ -1,3 +1,4 @@
+import fs from "fs";
 /**
  * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
  *
@@ -72,4 +73,124 @@ export declare function getDirSize(dirPath: string): Promise<number>;
  * @returns {() => void} A function to stop watching the directory.
  */
 export declare function watchDir(dirPath: string, callback: (eventType: "rename" | "change", filename: string | null) => void): () => void;
+/**
+ * Finds files matching a glob pattern.
+ *
+ * @param {string} pattern - Glob pattern to match files.
+ * @param {object} [options] - Options for glob pattern matching.
+ * @param {string} [options.cwd] - Current working directory for relative patterns.
+ * @param {boolean} [options.dot=false] - Include dotfiles in matches.
+ * @param {boolean} [options.nodir=true] - Only match files, not directories.
+ * @returns {Promise<string[]>} Array of matched file paths.
+ * @throws {Error} If pattern matching fails.
+ */
+export declare function findFilesByPattern(pattern: string, options?: {
+    cwd?: string;
+    dot?: boolean;
+    nodir?: boolean;
+}): Promise<string[]>;
+/**
+ * Gets all subdirectories in a directory.
+ *
+ * @param {string} dirPath - The directory to search in.
+ * @param {boolean} [recursive=false] - Whether to include subdirectories recursively.
+ * @returns {Promise<string[]>} Array of absolute subdirectory paths.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function getSubdirectories(dirPath: string, recursive?: boolean): Promise<string[]>;
+/**
+ * Ensures a directory exists and is empty.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<void>} Resolves when the directory exists and is empty.
+ * @throws {Error} If directory cannot be created or emptied.
+ */
+export declare function ensureEmptyDir(dirPath: string): Promise<void>;
+/**
+ * Creates a temporary directory with optional auto-cleanup.
+ *
+ * @param {object} [options] - Options for the temporary directory.
+ * @param {string} [options.prefix='tmp-'] - Prefix for the directory name.
+ * @param {string} [options.parentDir=os.tmpdir()] - Parent directory.
+ * @param {boolean} [options.cleanup=false] - Whether to register cleanup on process exit.
+ * @returns {Promise<{ path: string, cleanup: () => Promise<void> }>} Object with directory path and cleanup function.
+ * @throws {Error} If directory cannot be created.
+ */
+export declare function createTempDir(options?: {
+    prefix?: string;
+    parentDir?: string;
+    cleanup?: boolean;
+}): Promise<{
+    path: string;
+    cleanup: () => Promise<void>;
+}>;
+/**
+ * Finds the newest file in a directory.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string | null>} Path to the newest file or null if no files.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function findNewestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
+/**
+ * Finds the oldest file in a directory.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string | null>} Path to the oldest file or null if no files.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function findOldestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
+/**
+ * Finds files or directories in a directory matching a predicate function.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {(path: string, stat: fs.Stats) => boolean | Promise<boolean>} predicate - Function to test each path.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string[]>} Array of matching paths.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function findInDir(dirPath: string, predicate: (path: string, stat: fs.Stats) => boolean | Promise<boolean>, recursive?: boolean): Promise<string[]>;
+/**
+ * Watches a directory recursively for file changes.
+ *
+ * @param {string} dirPath - Base directory path to watch.
+ * @param {(eventType: "rename" | "change", filename: string) => void} callback - Callback for each change event.
+ * @param {boolean} [includeSubdirs=true] - Whether to watch subdirectories.
+ * @returns {Promise<() => void>} A function to stop watching the directory.
+ * @throws {Error} If directory cannot be watched.
+ */
+export declare function watchDirRecursive(dirPath: string, callback: (eventType: "rename" | "change", filename: string) => void, includeSubdirs?: boolean): Promise<() => void>;
+/**
+ * Gets detailed directory statistics including file count, directory count, and size.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<{ fileCount: number, dirCount: number, totalSize: number }>} Directory statistics.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function getDirStats(dirPath: string): Promise<{
+    fileCount: number;
+    dirCount: number;
+    totalSize: number;
+}>;
+/**
+ * Walks through a directory hierarchy, calling a visitor function for each entry.
+ *
+ * @param {string} dirPath - Starting directory path.
+ * @param {object} options - Options for walking the directory.
+ * @param {(entry: { path: string, name: string, isDirectory: boolean, stats: fs.Stats }) => boolean | void | Promise<boolean | void>} options.visitorFn -
+ *   Function called for each file/directory. Return false to skip a directory.
+ * @param {'pre' | 'post'} [options.traversalOrder='pre'] - Whether to visit directories before or after their contents.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function walkDir(dirPath: string, options: {
+    visitorFn: (entry: {
+        path: string;
+        name: string;
+        isDirectory: boolean;
+        stats: fs.Stats;
+    }) => boolean | void | Promise<boolean | void>;
+    traversalOrder?: "pre" | "post";
+}): Promise<void>;
 //# sourceMappingURL=dir.utils.d.ts.map

package/build/src/utils/dir.utils.js

@@ -12,9 +12,22 @@ exports.moveDir = moveDir;
 exports.emptyDir = emptyDir;
 exports.getDirSize = getDirSize;
 exports.watchDir = watchDir;
+exports.findFilesByPattern = findFilesByPattern;
+exports.getSubdirectories = getSubdirectories;
+exports.ensureEmptyDir = ensureEmptyDir;
+exports.createTempDir = createTempDir;
+exports.findNewestFile = findNewestFile;
+exports.findOldestFile = findOldestFile;
+exports.findInDir = findInDir;
+exports.watchDirRecursive = watchDirRecursive;
+exports.getDirStats = getDirStats;
+exports.walkDir = walkDir;
+const os_1 = __importDefault(require("os"));
 const fs_1 = __importDefault(require("fs"));
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const glob_1 = require("glob");
+const crypto_1 = require("crypto");
 /**
  * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
  *
@@ -161,4 +174,307 @@ function watchDir(dirPath, callback) {
     });
     return () => watcher.close();
 }
+/**
+ * Finds files matching a glob pattern.
+ *
+ * @param {string} pattern - Glob pattern to match files.
+ * @param {object} [options] - Options for glob pattern matching.
+ * @param {string} [options.cwd] - Current working directory for relative patterns.
+ * @param {boolean} [options.dot=false] - Include dotfiles in matches.
+ * @param {boolean} [options.nodir=true] - Only match files, not directories.
+ * @returns {Promise<string[]>} Array of matched file paths.
+ * @throws {Error} If pattern matching fails.
+ */
+async function findFilesByPattern(pattern, options = {}) {
+    const defaultOptions = Object.assign({ nodir: true }, options);
+    return (0, glob_1.glob)(pattern, defaultOptions);
+}
+/**
+ * Gets all subdirectories in a directory.
+ *
+ * @param {string} dirPath - The directory to search in.
+ * @param {boolean} [recursive=false] - Whether to include subdirectories recursively.
+ * @returns {Promise<string[]>} Array of absolute subdirectory paths.
+ * @throws {Error} If directory cannot be read.
+ */
+async function getSubdirectories(dirPath, recursive = false) {
+    const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+    const dirs = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path_1.default.join(dirPath, entry.name));
+    if (recursive && dirs.length > 0) {
+        const nestedDirs = await Promise.all(dirs.map((dir) => getSubdirectories(dir, true)));
+        return [...dirs, ...nestedDirs.flat()];
+    }
+    return dirs;
+}
+/**
+ * Ensures a directory exists and is empty.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<void>} Resolves when the directory exists and is empty.
+ * @throws {Error} If directory cannot be created or emptied.
+ */
+async function ensureEmptyDir(dirPath) {
+    if (await isDirectory(dirPath)) {
+        await emptyDir(dirPath);
+    }
+    else {
+        try {
+            await promises_1.default.unlink(dirPath);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        await ensureDir(dirPath);
+    }
+}
+/**
+ * Creates a temporary directory with optional auto-cleanup.
+ *
+ * @param {object} [options] - Options for the temporary directory.
+ * @param {string} [options.prefix='tmp-'] - Prefix for the directory name.
+ * @param {string} [options.parentDir=os.tmpdir()] - Parent directory.
+ * @param {boolean} [options.cleanup=false] - Whether to register cleanup on process exit.
+ * @returns {Promise<{ path: string, cleanup: () => Promise<void> }>} Object with directory path and cleanup function.
+ * @throws {Error} If directory cannot be created.
+ */
+async function createTempDir(options = {}) {
+    const prefix = options.prefix || "tmp-";
+    const parentDir = options.parentDir || os_1.default.tmpdir();
+    const dirName = `${prefix}${(0, crypto_1.randomBytes)(6).toString("hex")}`;
+    const tempDirPath = path_1.default.join(parentDir, dirName);
+    await ensureDir(tempDirPath);
+    const cleanup = async () => {
+        try {
+            await deleteDirRecursive(tempDirPath);
+        }
+        catch (_a) {
+            // Ignore cleanup errors
+        }
+    };
+    if (options.cleanup) {
+        process.once("exit", () => {
+            try {
+                fs_1.default.rmSync(tempDirPath, { recursive: true, force: true });
+            }
+            catch (_a) {
+                // Ignore cleanup errors on exit
+            }
+        });
+        // Handle signals for better cleanup
+        ["SIGINT", "SIGTERM", "SIGUSR1", "SIGUSR2"].forEach((signal) => {
+            process.once(signal, () => {
+                cleanup().then(() => process.exit());
+            });
+        });
+    }
+    return { path: tempDirPath, cleanup };
+}
+/**
+ * Finds the newest file in a directory.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string | null>} Path to the newest file or null if no files.
+ * @throws {Error} If directory cannot be read.
+ */
+async function findNewestFile(dirPath, recursive = false) {
+    const files = await listFiles(dirPath, recursive);
+    if (files.length === 0)
+        return null;
+    const stats = await Promise.all(files.map(async (file) => ({
+        path: file,
+        mtime: (await promises_1.default.stat(file)).mtime,
+    })));
+    return stats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime())[0].path;
+}
+/**
+ * Finds the oldest file in a directory.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string | null>} Path to the oldest file or null if no files.
+ * @throws {Error} If directory cannot be read.
+ */
+async function findOldestFile(dirPath, recursive = false) {
+    const files = await listFiles(dirPath, recursive);
+    if (files.length === 0)
+        return null;
+    const stats = await Promise.all(files.map(async (file) => ({
+        path: file,
+        mtime: (await promises_1.default.stat(file)).mtime,
+    })));
+    return stats.sort((a, b) => a.mtime.getTime() - b.mtime.getTime())[0].path;
+}
+/**
+ * Finds files or directories in a directory matching a predicate function.
+ *
+ * @param {string} dirPath - Directory to search.
+ * @param {(path: string, stat: fs.Stats) => boolean | Promise<boolean>} predicate - Function to test each path.
+ * @param {boolean} [recursive=false] - Whether to search subdirectories.
+ * @returns {Promise<string[]>} Array of matching paths.
+ * @throws {Error} If directory cannot be read.
+ */
+async function findInDir(dirPath, predicate, recursive = false) {
+    const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        const entryPath = path_1.default.join(dirPath, entry.name);
+        const stat = await promises_1.default.stat(entryPath);
+        if (await predicate(entryPath, stat)) {
+            results.push(entryPath);
+        }
+        if (recursive && entry.isDirectory()) {
+            const nestedResults = await findInDir(entryPath, predicate, true);
+            results.push(...nestedResults);
+        }
+    }
+    return results;
+}
+/**
+ * Watches a directory recursively for file changes.
+ *
+ * @param {string} dirPath - Base directory path to watch.
+ * @param {(eventType: "rename" | "change", filename: string) => void} callback - Callback for each change event.
+ * @param {boolean} [includeSubdirs=true] - Whether to watch subdirectories.
+ * @returns {Promise<() => void>} A function to stop watching the directory.
+ * @throws {Error} If directory cannot be watched.
+ */
+async function watchDirRecursive(dirPath, callback, includeSubdirs = true) {
+    // Normalize the path to ensure consistent path separators
+    const normalizedBasePath = path_1.default.normalize(dirPath);
+    // Create watchers for the base dir and all subdirectories
+    const watchers = [];
+    // Helper function to add a watcher for a directory
+    const addWatcher = (dir) => {
+        try {
+            const watcher = fs_1.default.watch(dir, (eventType, filename) => {
+                if (!filename)
+                    return;
+                const fullPath = path_1.default.join(dir, filename);
+                // Make the path relative to the base directory
+                const relativePath = path_1.default.relative(normalizedBasePath, fullPath);
+                callback(eventType, relativePath);
+                // If a new directory is created, we should watch it
+                if (eventType === "rename" && includeSubdirs) {
+                    setTimeout(async () => {
+                        try {
+                            if (await isDirectory(fullPath)) {
+                                addWatcher(fullPath);
+                            }
+                        }
+                        catch (_a) {
+                            // Ignore errors checking newly created items
+                        }
+                    }, 100);
+                }
+            });
+            watchers.push(watcher);
+        }
+        catch (_a) {
+            // Silently ignore directories we can't watch
+        }
+    };
+    // Add watcher for the base directory
+    addWatcher(normalizedBasePath);
+    // If watching subdirectories, add watchers for all existing subdirectories
+    if (includeSubdirs) {
+        const subdirs = await getSubdirectories(normalizedBasePath, true);
+        for (const subdir of subdirs) {
+            addWatcher(subdir);
+        }
+    }
+    // Return a function to close all watchers
+    return () => {
+        watchers.forEach((watcher) => watcher.close());
+    };
+}
+/**
+ * Gets detailed directory statistics including file count, directory count, and size.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @returns {Promise<{ fileCount: number, dirCount: number, totalSize: number }>} Directory statistics.
+ * @throws {Error} If directory cannot be read.
+ */
+async function getDirStats(dirPath) {
+    let fileCount = 0;
+    let dirCount = 0;
+    let totalSize = 0;
+    async function processDir(currentPath) {
+        const entries = await promises_1.default.readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path_1.default.join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                dirCount++;
+                await processDir(entryPath);
+            }
+            else if (entry.isFile()) {
+                fileCount++;
+                const stat = await promises_1.default.stat(entryPath);
+                totalSize += stat.size;
+            }
+        }
+    }
+    await processDir(dirPath);
+    return { fileCount, dirCount, totalSize };
+}
+/**
+ * Walks through a directory hierarchy, calling a visitor function for each entry.
+ *
+ * @param {string} dirPath - Starting directory path.
+ * @param {object} options - Options for walking the directory.
+ * @param {(entry: { path: string, name: string, isDirectory: boolean, stats: fs.Stats }) => boolean | void | Promise<boolean | void>} options.visitorFn -
+ *   Function called for each file/directory. Return false to skip a directory.
+ * @param {'pre' | 'post'} [options.traversalOrder='pre'] - Whether to visit directories before or after their contents.
+ * @throws {Error} If directory cannot be read.
+ */
+async function walkDir(dirPath, options) {
+    const traversalOrder = options.traversalOrder || "pre";
+    const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path_1.default.join(dirPath, entry.name);
+        const stats = await promises_1.default.stat(entryPath);
+        const entryInfo = {
+            path: entryPath,
+            name: entry.name,
+            isDirectory: entry.isDirectory(),
+            stats,
+        };
+        if (entry.isDirectory()) {
+            // Pre-order: visit directory before its contents
+            if (traversalOrder === "pre") {
+                const shouldContinue = await options.visitorFn(entryInfo);
+                // If the visitor returns false, don't recurse into this directory
+                if (shouldContinue !== false) {
+                    await walkDir(entryPath, options);
+                }
+            }
+            else {
+                // Post-order: visit directory after its contents
+                await walkDir(entryPath, options);
+                await options.visitorFn(entryInfo);
+            }
+        }
+        else {
+            // Files are always visited when encountered
+            await options.visitorFn(entryInfo);
+        }
+    }
+    if (traversalOrder === "post") {
+        // Only visit the root if this is the top-level call (not for subdirectories)
+        // But since this function is always called recursively, always visit after children
+        const stats = await promises_1.default.stat(dirPath);
+        const entryInfo = {
+            path: dirPath,
+            name: path_1.default.basename(dirPath),
+            isDirectory: true,
+            stats,
+        };
+        await options.visitorFn(entryInfo);
+    }
+}
 //# sourceMappingURL=dir.utils.js.map