@catbee/utils 2.0.0-next.0 → 2.0.0

package/fs/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,4 +22,208 @@
  * SOFTWARE.
  */
 
-export * from './fs.utils';
+import { BufferEncoding } from '@catbee/utils/crypto';
+import fs from 'node:fs';
+
+/**
+ * Checks whether a file or directory exists at the given path.
+ *
+ * @param {string} path - The file or directory path to check.
+ * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.
+ */
+declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Reads and parses a JSON file from the specified path.
+ *
+ * @typeParam T - The expected type of the parsed JSON object.
+ * @param {string} path - The path to the JSON file.
+ * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.
+ */
+declare function readJsonFile<T = any>(path: string): Promise<T | null>;
+/**
+ * Read and parse JSON file or return a provided default value on error.
+ *
+ * @typeParam T
+ * @param {string} path - Path to JSON file
+ * @param {T} defaultValue - Default value to return when read/parse fails
+ * @returns {Promise<T>} Parsed JSON or defaultValue
+ */
+declare function readJsonOrDefault<T = any>(path: string, defaultValue: T): Promise<T>;
+/**
+ * Writes a JavaScript object to a file as formatted JSON.
+ *
+ * @param {string} path - The destination file path.
+ * @param {any} data - The object to serialize and write.
+ * @param {number} [space=2] - Number of spaces for JSON formatting.
+ * @returns {Promise<void>} Resolves when writing is complete.
+ */
+declare function writeJsonFile(path: string, data: any, space?: number): Promise<void>;
+/**
+ * Deletes a file if it exists.
+ *
+ * @param {string} path - The file path to delete.
+ * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
+ */
+declare function deleteFileIfExists(path: string): Promise<boolean>;
+/**
+ * Reads a file from the specified path.
+ *
+ * @param {string} path - The path to the file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
+ */
+declare function readFile(path: string, encoding?: BufferEncoding): Promise<string>;
+/**
+ * Reads a file from the specified path synchronously.
+ *
+ * @param {string} path - The path to the file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {string | null} The file contents, or `null` if reading fails.
+ */
+declare function readFileSync(path: string, encoding?: BufferEncoding): string;
+/**
+ * Safely reads a file and returns its content along with any error encountered.
+ *
+ * @param {string} path - The path to the file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<{ data: string | null; error: Error | null }>} Object with data and error properties.
+ */
+declare function safeReadFile(path: string, encoding?: BufferEncoding): Promise<{
+    data: string | null;
+    error: Error | null;
+}>;
+/**
+ * Safely reads a file synchronously and returns its content along with any error encountered.
+ *
+ * @param {string} path - The path to the file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {{ data: string | null; error: Error | null }} Object with data and error properties.
+ */
+declare function safeReadFileSync(path: string, encoding?: BufferEncoding): {
+    data: string | null;
+    error: Error | null;
+};
+/**
+ * Writes content to a file.
+ *
+ * @param {string} path - The destination file path.
+ * @param {string} content - The text content to write.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+declare function writeFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
+/**
+ * Appends text content to a file.
+ *
+ * @param {string} path - The file path to append to.
+ * @param {string} content - The text content to append.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+declare function appendFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
+/**
+ * Copies a file from source to destination.
+ *
+ * @param {string} source - Source file path.
+ * @param {string} destination - Destination file path.
+ * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+declare function copyFile(source: string, destination: string, overwrite?: boolean): Promise<boolean>;
+/**
+ * Renames/moves a file.
+ *
+ * @param {string} oldPath - Current file path.
+ * @param {string} newPath - New file path.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+declare function moveFile(oldPath: string, newPath: string): Promise<boolean>;
+/**
+ * Gets file stats if the file exists.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<fsp.Stats | null>} File stats object or null if file doesn't exist.
+ */
+declare function getFileStats(path: string): Promise<fs.Stats | null>;
+/**
+ * Creates a temporary file with optional content.
+ *
+ * @param {object} [options] - Options for creating the temp file.
+ * @param {string} [options.prefix="tmp-"] - Filename prefix.
+ * @param {string} [options.extension=""] - File extension.
+ * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).
+ * @param {string | Buffer} [options.content] - Optional content to write to the file.
+ * @returns {Promise<string>} Path to the created temporary file.
+ */
+declare function createTempFile({ prefix, extension, dir, content }?: {
+    prefix?: string;
+    extension?: string;
+    dir?: string;
+    content?: string | Buffer;
+}): Promise<string>;
+/**
+ * Streams a file from source to destination.
+ * Useful for large files to avoid loading the entire file into memory.
+ *
+ * @param {string} source - Source file path.
+ * @param {string} destination - Destination file path.
+ * @returns {Promise<void>} Resolves when streaming completes.
+ * @throws {Error} If streaming fails.
+ */
+declare function streamFile(source: string, destination: string): Promise<void>;
+/**
+ * Reads a directory and returns file names.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @param {object} [options] - Options for reading the directory.
+ * @param {boolean} [options.fullPaths=false] - Whether to return full paths.
+ * @param {RegExp} [options.filter] - Optional regex to filter files.
+ * @returns {Promise<string[]>} Array of file names or paths.
+ * @throws {Error} If directory cannot be read.
+ */
+declare function readDirectory(dirPath: string, options?: {
+    fullPaths?: boolean;
+    filter?: RegExp;
+}): Promise<string[]>;
+/**
+ * Creates a directory if it doesn't exist.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @param {boolean} [recursive=true] - Whether to create parent directories.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+declare function createDirectory(dirPath: string, recursive?: boolean): Promise<boolean>;
+/**
+ * Safely reads and parses a JSON file with error details.
+ *
+ * @typeParam T - The expected type of the parsed JSON object.
+ * @param {string} path - The path to the JSON file.
+ * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.
+ */
+declare function safeReadJsonFile<T = any>(path: string): Promise<{
+    data: T | null;
+    error: Error | null;
+}>;
+/**
+ * Checks if a path points to a file (not a directory).
+ *
+ * @param {string} path - Path to check.
+ * @returns {Promise<boolean>} True if the path is a file, false otherwise.
+ */
+declare function isFile(path: string): Promise<boolean>;
+/**
+ * Gets the size of a file in bytes.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.
+ */
+declare function getFileSize(path: string): Promise<number>;
+/**
+ * Reads a file as a Buffer.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.
+ */
+declare function readFileBuffer(path: string): Promise<Buffer | null>;
+
+export { appendFile, copyFile, createDirectory, createTempFile, deleteFileIfExists, fileExists, getFileSize, getFileStats, isFile, moveFile, readDirectory, readFile, readFileBuffer, readFileSync, readJsonFile, readJsonOrDefault, safeReadFile, safeReadFileSync, safeReadJsonFile, streamFile, writeFile, writeJsonFile };

package/fs/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
@@ -22,8 +22,8 @@
  * SOFTWARE.
  */
 
-import { createReadStream, createWriteStream } from 'fs';
-import fs from 'fs/promises';
+import fs from 'fs';
+import fsp from 'fs/promises';
 import { tmpdir } from 'os';
 import path from 'path';
 import { pipeline } from 'stream/promises';
@@ -33,7 +33,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 async function fileExists(path2) {
   try {
-    await fs.access(path2);
+    await fsp.access(path2);
     return true;
   } catch {
     return false;
@@ -42,7 +42,7 @@ async function fileExists(path2) {
 __name(fileExists, "fileExists");
 async function readJsonFile(path2) {
   try {
-    const data = await fs.readFile(path2, "utf-8");
+    const data = await fsp.readFile(path2, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -56,12 +56,12 @@ async function readJsonOrDefault(path2, defaultValue) {
 __name(readJsonOrDefault, "readJsonOrDefault");
 async function writeJsonFile(path2, data, space = 2) {
   const json = JSON.stringify(data, null, space);
-  await fs.writeFile(path2, json, "utf-8");
+  await fsp.writeFile(path2, json, "utf-8");
 }
 __name(writeJsonFile, "writeJsonFile");
 async function deleteFileIfExists(path2) {
   try {
-    await fs.unlink(path2);
+    await fsp.unlink(path2);
     return true;
   } catch (err) {
     if (err.code === "ENOENT") return true;
@@ -69,36 +69,66 @@ async function deleteFileIfExists(path2) {
   }
 }
 __name(deleteFileIfExists, "deleteFileIfExists");
-async function readTextFile(path2, encoding = "utf-8") {
+async function readFile(path2, encoding = "utf-8") {
+  return await fsp.readFile(path2, encoding);
+}
+__name(readFile, "readFile");
+function readFileSync(path2, encoding = "utf-8") {
+  return fs.readFileSync(path2, encoding);
+}
+__name(readFileSync, "readFileSync");
+async function safeReadFile(path2, encoding = "utf-8") {
   try {
-    return await fs.readFile(path2, encoding);
-  } catch {
-    return null;
+    const data = await fsp.readFile(path2, encoding);
+    return {
+      data,
+      error: null
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: new Error(`Failed to read file ${path2}: ${error.message}`)
+    };
+  }
+}
+__name(safeReadFile, "safeReadFile");
+function safeReadFileSync(path2, encoding = "utf-8") {
+  try {
+    const data = fs.readFileSync(path2, encoding);
+    return {
+      data,
+      error: null
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: new Error(`Failed to read file ${path2}: ${error.message}`)
+    };
   }
 }
-__name(readTextFile, "readTextFile");
-async function writeTextFile(path2, content, encoding = "utf-8") {
+__name(safeReadFileSync, "safeReadFileSync");
+async function writeFile(path2, content, encoding = "utf-8") {
   try {
-    await fs.writeFile(path2, content, encoding);
+    await fsp.writeFile(path2, content, encoding);
     return true;
   } catch {
     return false;
   }
 }
-__name(writeTextFile, "writeTextFile");
-async function appendTextFile(path2, content, encoding = "utf-8") {
+__name(writeFile, "writeFile");
+async function appendFile(path2, content, encoding = "utf-8") {
   try {
-    await fs.appendFile(path2, content, encoding);
+    await fsp.appendFile(path2, content, encoding);
     return true;
   } catch {
     return false;
   }
 }
-__name(appendTextFile, "appendTextFile");
+__name(appendFile, "appendFile");
 async function copyFile(source, destination, overwrite = false) {
   try {
-    const flags = overwrite ? 0 : fs.constants.COPYFILE_EXCL;
-    await fs.copyFile(source, destination, flags);
+    const flags = overwrite ? 0 : fsp.constants.COPYFILE_EXCL;
+    await fsp.copyFile(source, destination, flags);
     return true;
   } catch {
     return false;
@@ -107,12 +137,12 @@ async function copyFile(source, destination, overwrite = false) {
 __name(copyFile, "copyFile");
 async function moveFile(oldPath, newPath) {
   try {
-    await fs.rename(oldPath, newPath);
+    await fsp.rename(oldPath, newPath);
     return true;
   } catch {
     try {
-      await fs.copyFile(oldPath, newPath);
-      await fs.unlink(oldPath);
+      await fsp.copyFile(oldPath, newPath);
+      await fsp.unlink(oldPath);
       return true;
     } catch {
       return false;
@@ -122,7 +152,7 @@ async function moveFile(oldPath, newPath) {
 __name(moveFile, "moveFile");
 async function getFileStats(path2) {
   try {
-    return await fs.stat(path2);
+    return await fsp.stat(path2);
   } catch {
     return null;
   }
@@ -133,16 +163,16 @@ async function createTempFile({ prefix = "tmp-", extension = "", dir = tmpdir(),
   const filename = `${prefix}${randomUUID()}${ext}`;
   const filepath = path.join(dir, filename);
   if (content) {
-    await fs.writeFile(filepath, content);
+    await fsp.writeFile(filepath, content);
   } else {
-    await fs.writeFile(filepath, "");
+    await fsp.writeFile(filepath, "");
   }
   return filepath;
 }
 __name(createTempFile, "createTempFile");
 async function streamFile(source, destination) {
-  const readStream = createReadStream(source);
-  const writeStream = createWriteStream(destination);
+  const readStream = fs.createReadStream(source);
+  const writeStream = fs.createWriteStream(destination);
   try {
     await pipeline(readStream, writeStream);
   } catch (error) {
@@ -153,7 +183,7 @@ async function streamFile(source, destination) {
 }
 __name(streamFile, "streamFile");
 async function readDirectory(dirPath, options = {}) {
-  const files = await fs.readdir(dirPath);
+  const files = await fsp.readdir(dirPath);
   let result = files;
   if (options.filter) {
     result = result.filter((file) => options.filter.test(file));
@@ -166,7 +196,7 @@ async function readDirectory(dirPath, options = {}) {
 __name(readDirectory, "readDirectory");
 async function createDirectory(dirPath, recursive = true) {
   try {
-    await fs.mkdir(dirPath, {
+    await fsp.mkdir(dirPath, {
       recursive
     });
     return true;
@@ -177,7 +207,7 @@ async function createDirectory(dirPath, recursive = true) {
 __name(createDirectory, "createDirectory");
 async function safeReadJsonFile(path2) {
   try {
-    const content = await fs.readFile(path2, "utf-8");
+    const content = await fsp.readFile(path2, "utf-8");
     try {
       const data = JSON.parse(content);
       return {
@@ -200,7 +230,7 @@ async function safeReadJsonFile(path2) {
 __name(safeReadJsonFile, "safeReadJsonFile");
 async function isFile(path2) {
   try {
-    const stat = await fs.stat(path2);
+    const stat = await fsp.stat(path2);
     return stat.isFile();
   } catch {
     return false;
@@ -209,7 +239,7 @@ async function isFile(path2) {
 __name(isFile, "isFile");
 async function getFileSize(path2) {
   try {
-    const stat = await fs.stat(path2);
+    const stat = await fsp.stat(path2);
     return stat.size;
   } catch {
     return -1;
@@ -218,11 +248,11 @@ async function getFileSize(path2) {
 __name(getFileSize, "getFileSize");
 async function readFileBuffer(path2) {
   try {
-    return await fs.readFile(path2);
+    return await fsp.readFile(path2);
   } catch {
     return null;
   }
 }
 __name(readFileBuffer, "readFileBuffer");
 
-export { appendTextFile, copyFile, createDirectory, createTempFile, deleteFileIfExists, fileExists, getFileSize, getFileStats, isFile, moveFile, readDirectory, readFileBuffer, readJsonFile, readJsonOrDefault, readTextFile, safeReadJsonFile, streamFile, writeJsonFile, writeTextFile };
+export { appendFile, copyFile, createDirectory, createTempFile, deleteFileIfExists, fileExists, getFileSize, getFileStats, isFile, moveFile, readDirectory, readFile, readFileBuffer, readFileSync, readJsonFile, readJsonOrDefault, safeReadFile, safeReadFileSync, safeReadJsonFile, streamFile, writeFile, writeJsonFile };

package/http-status-codes/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