@catbee/utils 2.0.0-next.0 → 2.0.0

package/{dir → directory}/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -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/dir.utils.d.ts → directory/index.d.ts}

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,7 +22,8 @@
  * SOFTWARE.
  */
 
-import fs from 'fs';
+import fs from 'node:fs';
+
 /**
  * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
  *
@@ -30,7 +31,7 @@ import fs from 'fs';
  * @returns {Promise<void>} Resolves when the directory exists.
  * @throws {Error} If directory cannot be created.
  */
-export declare function ensureDir(dirPath: string): Promise<void>;
+declare function ensureDir(dirPath: string): Promise<void>;
 /**
  * Recursively lists all files in a directory.
  *
@@ -39,7 +40,7 @@ export declare function ensureDir(dirPath: string): Promise<void>;
  * @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[]>;
+declare function listFiles(dirPath: string, recursive?: boolean): Promise<string[]>;
 /**
  * Deletes a directory and all its contents recursively (like `rm -rf`).
  *
@@ -47,14 +48,14 @@ export declare function listFiles(dirPath: string, recursive?: boolean): Promise
  * @returns {Promise<void>} Resolves when deletion is complete.
  * @throws {Error} If deletion fails.
  */
-export declare function deleteDirRecursive(dirPath: string): Promise<void>;
+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>;
+declare function isDirectory(pathStr: string): Promise<boolean>;
 /**
  * Recursively copies a directory and all its contents to a destination.
  *
@@ -63,7 +64,7 @@ export declare function isDirectory(pathStr: string): Promise<boolean>;
  * @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>;
+declare function copyDir(src: string, dest: string): Promise<void>;
 /**
  * Moves a directory to a new location by copying and deleting the original.
  *
@@ -72,7 +73,7 @@ export declare function copyDir(src: string, dest: string): Promise<void>;
  * @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>;
+declare function moveDir(src: string, dest: string): Promise<void>;
 /**
  * Empties a directory by deleting all files and subdirectories inside it.
  *
@@ -80,7 +81,7 @@ export declare function moveDir(src: string, dest: string): Promise<void>;
  * @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>;
+declare function emptyDir(dirPath: string): Promise<void>;
 /**
  * Calculates the total size (in bytes) of all files in a directory (recursive).
  *
@@ -88,7 +89,7 @@ export declare function emptyDir(dirPath: string): Promise<void>;
  * @returns {Promise<number>} Total size in bytes.
  * @throws {Error} If any file stats cannot be read.
  */
-export declare function getDirSize(dirPath: string): Promise<number>;
+declare function getDirSize(dirPath: string): Promise<number>;
 /**
  * Watches a directory for file changes and calls a callback on each event.
  *
@@ -96,7 +97,7 @@ export declare function getDirSize(dirPath: string): Promise<number>;
  * @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;
+declare function watchDir(dirPath: string, callback: (eventType: 'rename' | 'change', filename: string | null) => void): () => void;
 /**
  * Recursively finds files matching a simple pattern (supports '*' and '?').
  *
@@ -106,7 +107,7 @@ export declare function watchDir(dirPath: string, callback: (eventType: 'rename'
  * @param {boolean} [options.dot=false] - Include dotfiles in matches.
  * @returns {Promise<string[]>} Array of matched file paths.
  */
-export declare function findFilesByPattern(pattern: string, options?: {
+declare function findFilesByPattern(pattern: string, options?: {
     cwd?: string;
     dot?: boolean;
 }): Promise<string[]>;
@@ -118,7 +119,7 @@ export declare function findFilesByPattern(pattern: string, options?: {
  * @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[]>;
+declare function getSubdirectories(dirPath: string, recursive?: boolean): Promise<string[]>;
 /**
  * Ensures a directory exists and is empty.
  *
@@ -126,7 +127,7 @@ export declare function getSubdirectories(dirPath: string, recursive?: boolean):
  * @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>;
+declare function ensureEmptyDir(dirPath: string): Promise<void>;
 /**
  * Creates a temporary directory with optional auto-cleanup.
  *
@@ -137,7 +138,7 @@ export declare function ensureEmptyDir(dirPath: string): Promise<void>;
  * @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?: {
+declare function createTempDir(options?: {
     prefix?: string;
     parentDir?: string;
     cleanup?: boolean;
@@ -153,7 +154,7 @@ export declare function createTempDir(options?: {
  * @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>;
+declare function findNewestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
 /**
  * Finds the oldest file in a directory.
  *
@@ -162,7 +163,7 @@ export declare function findNewestFile(dirPath: string, recursive?: boolean): Pr
  * @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>;
+declare function findOldestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
 /**
  * Finds files or directories in a directory matching a predicate function.
  *
@@ -172,7 +173,7 @@ export declare function findOldestFile(dirPath: string, recursive?: boolean): Pr
  * @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[]>;
+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.
  *
@@ -182,7 +183,7 @@ export declare function findInDir(dirPath: string, predicate: (path: string, sta
  * @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>;
+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.
  *
@@ -190,7 +191,7 @@ export declare function watchDirRecursive(dirPath: string, callback: (eventType:
  * @returns {Promise<{ fileCount: number, dirCount: number, totalSize: number }>} Directory statistics.
  * @throws {Error} If directory cannot be read.
  */
-export declare function getDirStats(dirPath: string): Promise<{
+declare function getDirStats(dirPath: string): Promise<{
     fileCount: number;
     dirCount: number;
     totalSize: number;
@@ -205,7 +206,7 @@ export declare function getDirStats(dirPath: string): Promise<{
  * @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: {
+declare function walkDir(dirPath: string, options: {
     visitorFn: (entry: {
         path: string;
         name: string;
@@ -214,3 +215,5 @@ export declare function walkDir(dirPath: string, options: {
     }) => 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 → directory}/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -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

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -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 });
@@ -83,9 +85,7 @@ var Env = class _Env {
   static set(key, value) {
     process.env[key] = value;
     this.cache.delete(key);
-    for (const cacheKey of [
-      ...this.cache.keys()
-    ]) {
+    for (const cacheKey of this.cache.keys()) {
       if (cacheKey.includes(`:${key}`)) {
         this.cache.delete(cacheKey);
       }
@@ -114,7 +114,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 +172,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 +363,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;
@@ -439,20 +439,33 @@ var Env = class _Env {
     if (!value) {
       throw new Error(`URL environment variable '${key}' is missing or empty`);
     }
-    let url;
+    const url = this.parseUrl(value, key);
+    this.validateProtocol(url, key, options);
+    this.validateHostname(url, key, options);
+    this.cache.set(cacheKey, value);
+    return value;
+  }
+  static parseUrl(value, key) {
     try {
-      url = new URL(value);
+      return new URL(value);
     } catch {
       throw new Error(`Environment variable '${key}' is not a valid URL: "${value}"`);
     }
+  }
+  static validateProtocol(url, key, options) {
     if (options.protocols && options.protocols.length > 0) {
       const protocol = url.protocol.replace(":", "");
       if (!options.protocols.includes(protocol)) {
         throw new Error(`Environment variable '${key}' must use one of the protocols: ${options.protocols.join(", ")}. Got: ${protocol}`);
       }
     }
+  }
+  static isIp(hostname) {
+    return /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(hostname);
+  }
+  static validateHostname(url, key, options) {
     const { hostname } = url;
-    const isIp = /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(hostname);
+    const isIp = _Env.isIp(hostname);
     const isLocalhost = hostname === "localhost";
     if (isIp && options.allowIp === false) {
       throw new Error(`Environment variable '${key}' cannot be an IP address: "${hostname}"`);
@@ -465,8 +478,6 @@ var Env = class _Env {
         throw new Error(`Environment variable '${key}' must have a valid host with TLD: "${hostname}"`);
       }
     }
-    this.cache.set(cacheKey, value);
-    return value;
   }
   /**
   * Retrieves an email environment variable and validates it.
@@ -490,8 +501,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 +589,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 +613,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;
   }
@@ -667,63 +660,102 @@ var Env = class _Env {
       throw new Error(`Environment file not found: "${path}"`);
     }
     const content = fs.readFileSync(path, "utf8");
+    const variables = this.parseEnvContent(content);
+    for (const [k, v] of Object.entries(variables)) {
+      if (!process.env[k]) {
+        process.env[k] = v;
+      }
+    }
+    return variables;
+  }
+  static parseEnvContent(content) {
     const variables = {};
     const lines = content.split(/\r?\n/);
     let i = 0;
     while (i < lines.length) {
       let line = lines[i].trim();
-      if (!line || line.startsWith("#")) {
+      if (this.isCommentOrEmpty(line)) {
         i++;
         continue;
       }
-      const match = line.match(/^([^=]+)=(.*)$/);
+      const match = this.extractKeyValue(line);
       if (!match) {
         i++;
         continue;
       }
       const key = match[1].trim();
       let value = match[2].trim();
-      if (!/^['"]/.test(value)) {
-        const hashIndex = value.indexOf(" #");
-        if (hashIndex !== -1) {
-          value = value.slice(0, hashIndex).trim();
-        }
+      if (!this.isQuoted(value)) {
+        value = this.stripInlineComment(value);
       }
-      if ((value.startsWith('"') || value.startsWith("'")) && value.length > 1) {
-        const quote = value[0];
-        if (!value.endsWith(quote) || value.length === 1) {
-          let multilineValue = value.slice(1);
-          i++;
-          while (i < lines.length) {
-            const nextLine = lines[i];
-            if (nextLine.endsWith(quote)) {
-              multilineValue += "\n" + nextLine.slice(0, -1);
-              break;
-            } else {
-              multilineValue += "\n" + nextLine;
-            }
-            i++;
-          }
-          value = multilineValue;
-        } else {
-          value = value.slice(1, -1);
-        }
+      if (this.isQuoted(value) && value.length > 1) {
+        const result = this.parseQuotedValue(lines, i, value);
+        value = result.value;
+        i = result.nextIndex;
       } else {
-        i++;
-        while (i < lines.length && !lines[i].includes("=") && lines[i].trim() !== "") {
-          value += "\n" + lines[i];
-          i++;
-        }
-        i--;
+        const result = this.parseUnquotedMultiline(lines, i, value);
+        value = result.value;
+        i = result.nextIndex;
       }
       if (!process.env[key]) {
-        process.env[key] = value;
         variables[key] = value;
       }
       i++;
     }
     return variables;
   }
+  static isCommentOrEmpty(line) {
+    return !line || line.startsWith("#");
+  }
+  static extractKeyValue(line) {
+    return line.match(/^([^=]+)=(.*)$/);
+  }
+  static isQuoted(value) {
+    return /^['"]/.test(value);
+  }
+  static stripInlineComment(value) {
+    const hashIndex = value.indexOf(" #");
+    if (hashIndex !== -1) {
+      return value.slice(0, hashIndex).trim();
+    }
+    return value;
+  }
+  static parseQuotedValue(lines, currentIndex, value) {
+    const quote = value[0];
+    if (!value.endsWith(quote) || value.length === 1) {
+      let multilineValue = value.slice(1);
+      let i = currentIndex + 1;
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        if (nextLine.endsWith(quote)) {
+          multilineValue += "\n" + nextLine.slice(0, -1);
+          break;
+        } else {
+          multilineValue += "\n" + nextLine;
+        }
+        i++;
+      }
+      return {
+        value: multilineValue,
+        nextIndex: i
+      };
+    }
+    return {
+      value: value.slice(1, -1),
+      nextIndex: currentIndex
+    };
+  }
+  static parseUnquotedMultiline(lines, currentIndex, value) {
+    let i = currentIndex + 1;
+    while (i < lines.length && !lines[i].includes("=") && lines[i].trim() !== "") {
+      value += "\n" + lines[i];
+      i++;
+    }
+    return {
+      value,
+      nextIndex: i - 1
+    };
+  }
   /**
   * Checks whether the specified environment variable exists.
   *