@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/dir/index.cjs

@@ -142,7 +142,7 @@ function watchDir(dirPath, callback) {
 __name(watchDir, "watchDir");
 async function findFilesByPattern(pattern, options = {}) {
   const matchPattern = /* @__PURE__ */ __name((name, pattern2) => {
-    let escaped = pattern2.replaceAll(/[.+^${}()|[\]\\]/g, "\\$&");
+    let escaped = pattern2.replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`);
     escaped = escaped.replaceAll("*", ".*").replaceAll("?", ".");
     const regex = new RegExp(`^${escaped}$`);
     return regex.test(name);
@@ -152,7 +152,7 @@ async function findFilesByPattern(pattern, options = {}) {
   async function walk(dir, segIndex) {
     if (segIndex >= segments.length) return [];
     const segment = segments[segIndex];
-    const entries = await fs__default.default.promises.readdir(dir, {
+    const entries = await fsp__default.default.readdir(dir, {
       withFileTypes: true
     });
     let matchedFiles = [];
@@ -254,7 +254,8 @@ async function findNewestFile(dirPath, recursive = false) {
     path: file,
     mtime: (await fsp__default.default.stat(file)).mtime
   })));
-  return stats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime())[0].path;
+  const sorted = stats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return sorted[0].path;
 }
 __name(findNewestFile, "findNewestFile");
 async function findOldestFile(dirPath, recursive = false) {

package/dir/index.d.ts

@@ -22,4 +22,198 @@
  * SOFTWARE.
  */
 
-export * from './dir.utils';
+import fs from 'node:fs';
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function watchDir(dirPath: string, callback: (eventType: 'rename' | 'change', filename: string | null) => void): () => void;
+/**
+ * Recursively finds files matching a simple pattern (supports '*' and '?').
+ *
+ * @param {string} pattern - Simple pattern to match files (e.g., '*.ts', 'src/*.js').
+ * @param {object} [options] - Options for matching files.
+ * @param {string} [options.cwd=process.cwd()] - Base directory to start searching from.
+ * @param {boolean} [options.dot=false] - Include dotfiles in matches.
+ * @returns {Promise<string[]>} Array of matched file paths.
+ */
+declare function findFilesByPattern(pattern: string, options?: {
+    cwd?: string;
+    dot?: 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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>;
+
+export { copyDir, createTempDir, deleteDirRecursive, emptyDir, ensureDir, ensureEmptyDir, findFilesByPattern, findInDir, findNewestFile, findOldestFile, getDirSize, getDirStats, getSubdirectories, isDirectory, listFiles, moveDir, walkDir, watchDir, watchDirRecursive };

package/dir/index.mjs

@@ -133,7 +133,7 @@ function watchDir(dirPath, callback) {
 __name(watchDir, "watchDir");
 async function findFilesByPattern(pattern, options = {}) {
   const matchPattern = /* @__PURE__ */ __name((name, pattern2) => {
-    let escaped = pattern2.replaceAll(/[.+^${}()|[\]\\]/g, "\\$&");
+    let escaped = pattern2.replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`);
     escaped = escaped.replaceAll("*", ".*").replaceAll("?", ".");
     const regex = new RegExp(`^${escaped}$`);
     return regex.test(name);
@@ -143,7 +143,7 @@ async function findFilesByPattern(pattern, options = {}) {
   async function walk(dir, segIndex) {
     if (segIndex >= segments.length) return [];
     const segment = segments[segIndex];
-    const entries = await fs.promises.readdir(dir, {
+    const entries = await fsp.readdir(dir, {
       withFileTypes: true
     });
     let matchedFiles = [];
@@ -245,7 +245,8 @@ async function findNewestFile(dirPath, recursive = false) {
     path: file,
     mtime: (await fsp.stat(file)).mtime
   })));
-  return stats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime())[0].path;
+  const sorted = stats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return sorted[0].path;
 }
 __name(findNewestFile, "findNewestFile");
 async function findOldestFile(dirPath, recursive = false) {

package/env/index.cjs

@@ -26,6 +26,8 @@
 
 var fs = require('fs');
 var path = require('path');
+var date = require('@catbee/utils/date');
+var validation = require('@catbee/utils/validation');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -114,7 +116,7 @@ var Env = class _Env {
   */
   static get(key, defaultValue) {
     let value = process.env[key] ?? defaultValue;
-    if (value && value.includes("${")) {
+    if (value?.includes("${")) {
       value = value.replace(/\${([A-Za-z0-9_]+)}/g, (_, varName) => {
         return process.env[varName] ?? "";
       });
@@ -172,7 +174,7 @@ var Env = class _Env {
       return defaultValue;
     }
     const numberValue = Number(value);
-    if (isNaN(numberValue)) {
+    if (Number.isNaN(numberValue)) {
       throw new Error(`Environment variable '${key}' is not a valid number, got: "${value}"`);
     }
     this.cache.set(`number:${key}`, numberValue);
@@ -363,7 +365,7 @@ var Env = class _Env {
   static getNumberArray(key, defaultValue = [], splitter = ",") {
     return _Env.getArray(key, defaultValue, splitter, (item) => {
       const num = Number(item);
-      if (isNaN(num)) {
+      if (Number.isNaN(num)) {
         throw new Error(`Value "${item}" in array '${key}' is not a valid number`);
       }
       return num;
@@ -490,8 +492,7 @@ var Env = class _Env {
       }
       return defaultValue;
     }
-    const emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
-    if (!emailRegex.test(value)) {
+    if (!validation.isEmail(value)) {
       throw new Error(`Environment variable '${key}' is not a valid email address: "${value}"`);
     }
     this.cache.set(`email:${key}`, value);
@@ -579,7 +580,7 @@ var Env = class _Env {
       return defaultValue instanceof Date ? defaultValue : /* @__PURE__ */ new Date();
     }
     const date = new Date(value);
-    if (isNaN(date.getTime())) {
+    if (Number.isNaN(date.getTime())) {
       throw new Error(`Environment variable '${key}' is not a valid date: "${value}"`);
     }
     return date;
@@ -603,26 +604,9 @@ var Env = class _Env {
     if (this.cache.has(cacheKey)) {
       return this.cache.get(cacheKey);
     }
-    const value = _Env.get(key, String(defaultValue));
-    if (!value) return 0;
-    if (/^\d+$/.test(value)) {
-      const ms2 = parseInt(value, 10);
-      this.cache.set(cacheKey, ms2);
-      return ms2;
-    }
-    const durationRegex = /^(?:(\d+)y)?(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?(?:(\d+)ms)?$/;
-    const matches = value.match(durationRegex);
-    if (!matches || matches[0] === "") {
-      throw new Error(`Environment variable '${key}' has invalid duration format: "${value}". Use formats like 1y, 2w, 3d, 4h, 5m, 6s, or 7ms.`);
-    }
-    let ms = 0;
-    if (matches[1]) ms += parseInt(matches[1], 10) * 31536e6;
-    if (matches[2]) ms += parseInt(matches[2], 10) * 6048e5;
-    if (matches[3]) ms += parseInt(matches[3], 10) * 864e5;
-    if (matches[4]) ms += parseInt(matches[4], 10) * 36e5;
-    if (matches[5]) ms += parseInt(matches[5], 10) * 6e4;
-    if (matches[6]) ms += parseInt(matches[6], 10) * 1e3;
-    if (matches[7]) ms += parseInt(matches[7], 10);
+    const raw = _Env.get(key, String(defaultValue));
+    if (!raw) return 0;
+    const ms = date.parseDuration(raw);
     this.cache.set(cacheKey, ms);
     return ms;
   }