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

package/exception/index.d.ts

@@ -22,4 +22,235 @@
  * SOFTWARE.
  */
 
-export * from './exception.utils';
+import { ErrorResponse } from '@catbee/utils/response';
+
+/**
+ * Generic HTTP error class used for custom exceptions with any status code.
+ * Inherit this when you need to throw errors dynamically at runtime.
+ */
+declare class HttpError extends ErrorResponse {
+    /**
+     * Creates a new HTTP error instance.
+     * @param status - A valid HTTP status code (e.g., 400, 500).
+     * @param message - The error message to return to the client.
+     */
+    constructor(status: number, message: string);
+}
+/**
+ * Represents a 500 Internal Server Error.
+ * Use this for unexpected backend errors that are not caused by the client.
+ */
+declare class InternalServerErrorException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Internal server error".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 401 Unauthorized Error.
+ * Indicates that authentication is required and has failed or not been provided.
+ */
+declare class UnauthorizedException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Unauthorized".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 400 Bad Request Error.
+ * Indicates that the client has sent invalid data (e.g., malformed request body).
+ */
+declare class BadRequestException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad request".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 404 Not Found Error.
+ * Used when a requested resource (e.g., user, file) could not be located.
+ */
+declare class NotFoundException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Resource not found".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 403 Forbidden Error.
+ * Indicates that the client is authenticated but not allowed to access the resource.
+ */
+declare class ForbiddenException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Forbidden".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 409 Conflict Error.
+ * Commonly used when a resource already exists or a versioning conflict occurs.
+ */
+declare class ConflictException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Conflict".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 502 Bad Gateway Error.
+ * Used when the server receives an invalid response from an upstream server.
+ */
+declare class BadGatewayException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad Gateway".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 429 Too Many Requests Error.
+ * Returned when the client has hit a rate limit.
+ */
+declare class TooManyRequestsException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Too many requests".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 503 Service Unavailable Error.
+ * Indicates that the server is temporarily unavailable (e.g., for maintenance).
+ */
+declare class ServiceUnavailableException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Service Unavailable".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 504 Gateway Timeout Error.
+ * Returned when the server acting as a gateway times out waiting for a response.
+ */
+declare class GatewayTimeoutException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Gateway Timeout".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 422 Unprocessable Entity Error.
+ * Used when the server understands the content type but cannot process the contained instructions.
+ */
+declare class UnprocessableEntityException extends ErrorResponse {
+    details?: Record<string, any> | undefined;
+    /**
+     * @param message - Optional custom message. Defaults to "Unprocessable Entity".
+     * @param details - Optional validation details or additional error context.
+     */
+    constructor(message?: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Represents a 405 Method Not Allowed Error.
+ * Used when the request method is not supported for the requested resource.
+ */
+declare class MethodNotAllowedException extends ErrorResponse {
+    allowedMethods?: string[] | undefined;
+    /**
+     * @param message - Optional custom message. Defaults to "Method Not Allowed".
+     * @param allowedMethods - Optional array of allowed HTTP methods.
+     */
+    constructor(message?: string, allowedMethods?: string[] | undefined);
+}
+/**
+ * Represents a 406 Not Acceptable Error.
+ * Used when the server cannot produce a response matching the client's accepted content types.
+ */
+declare class NotAcceptableException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Not Acceptable".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 408 Request Timeout Error.
+ * Used when the server times out waiting for the client to send a request.
+ */
+declare class RequestTimeoutException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Request Timeout".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 415 Unsupported Media Type Error.
+ * Used when the request's Content-Type is not supported.
+ */
+declare class UnsupportedMediaTypeException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Unsupported Media Type".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 413 Payload Too Large Error.
+ * Used when the request body exceeds server limits.
+ */
+declare class PayloadTooLargeException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Payload Too Large".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 507 Insufficient Storage Error.
+ * Used when the server has insufficient storage to complete the request.
+ */
+declare class InsufficientStorageException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Insufficient Storage".
+     */
+    constructor(message?: string);
+}
+/**
+ * Checks if an error is an instance of HttpError or its subclasses.
+ *
+ * @param error - The error to check.
+ * @returns True if the error is an HttpError, false otherwise.
+ */
+declare function isHttpError(error: unknown): error is ErrorResponse;
+/**
+ * Creates an HTTP error with the specified status code and message.
+ * Factory function for creating appropriate HTTP error instances.
+ *
+ * @param status - HTTP status code.
+ * @param message - Optional custom error message.
+ * @returns An instance of the appropriate HTTP error class.
+ */
+declare function createHttpError(status: number, message?: string): ErrorResponse;
+/**
+ * Type guard to check if an object has specific error properties.
+ *
+ * @param error - The object to check.
+ * @returns True if object has error-like structure.
+ */
+declare function hasErrorShape(error: unknown): error is {
+    message: string;
+    status?: number;
+    code?: string;
+};
+/**
+ * Safely extracts message from any error type.
+ *
+ * @param error - Any error object or value.
+ * @returns A string error message.
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Wraps a function and transforms any errors into HTTP errors.
+ * Useful for API handlers to ensure consistent error responses.
+ *
+ * @param handler - The async function to wrap.
+ * @returns A function that always returns or throws an HTTP error.
+ */
+declare function withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+
+export { BadGatewayException, BadRequestException, ConflictException, ForbiddenException, GatewayTimeoutException, HttpError, InsufficientStorageException, InternalServerErrorException, MethodNotAllowedException, NotAcceptableException, NotFoundException, PayloadTooLargeException, RequestTimeoutException, ServiceUnavailableException, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, createHttpError, getErrorMessage, hasErrorShape, isHttpError, withErrorHandling };

package/fs/index.cjs

@@ -24,8 +24,8 @@
 
 'use strict';
 
-var fs$1 = require('fs');
-var fs = require('fs/promises');
+var fs = require('fs');
+var fsp = require('fs/promises');
 var os = require('os');
 var path = require('path');
 var promises = require('stream/promises');
@@ -34,13 +34,14 @@ var crypto = require('crypto');
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var fs__default = /*#__PURE__*/_interopDefault(fs);
+var fsp__default = /*#__PURE__*/_interopDefault(fsp);
 var path__default = /*#__PURE__*/_interopDefault(path);
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 async function fileExists(path2) {
   try {
-    await fs__default.default.access(path2);
+    await fsp__default.default.access(path2);
     return true;
   } catch {
     return false;
@@ -49,7 +50,7 @@ async function fileExists(path2) {
 __name(fileExists, "fileExists");
 async function readJsonFile(path2) {
   try {
-    const data = await fs__default.default.readFile(path2, "utf-8");
+    const data = await fsp__default.default.readFile(path2, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -63,12 +64,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__default.default.writeFile(path2, json, "utf-8");
+  await fsp__default.default.writeFile(path2, json, "utf-8");
 }
 __name(writeJsonFile, "writeJsonFile");
 async function deleteFileIfExists(path2) {
   try {
-    await fs__default.default.unlink(path2);
+    await fsp__default.default.unlink(path2);
     return true;
   } catch (err) {
     if (err.code === "ENOENT") return true;
@@ -76,36 +77,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__default.default.readFile(path2, encoding);
+}
+__name(readFile, "readFile");
+function readFileSync(path2, encoding = "utf-8") {
+  return fs__default.default.readFileSync(path2, encoding);
+}
+__name(readFileSync, "readFileSync");
+async function safeReadFile(path2, encoding = "utf-8") {
   try {
-    return await fs__default.default.readFile(path2, encoding);
-  } catch {
-    return null;
+    const data = await fsp__default.default.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__default.default.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__default.default.writeFile(path2, content, encoding);
+    await fsp__default.default.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__default.default.appendFile(path2, content, encoding);
+    await fsp__default.default.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__default.default.constants.COPYFILE_EXCL;
-    await fs__default.default.copyFile(source, destination, flags);
+    const flags = overwrite ? 0 : fsp__default.default.constants.COPYFILE_EXCL;
+    await fsp__default.default.copyFile(source, destination, flags);
     return true;
   } catch {
     return false;
@@ -114,12 +145,12 @@ async function copyFile(source, destination, overwrite = false) {
 __name(copyFile, "copyFile");
 async function moveFile(oldPath, newPath) {
   try {
-    await fs__default.default.rename(oldPath, newPath);
+    await fsp__default.default.rename(oldPath, newPath);
     return true;
   } catch {
     try {
-      await fs__default.default.copyFile(oldPath, newPath);
-      await fs__default.default.unlink(oldPath);
+      await fsp__default.default.copyFile(oldPath, newPath);
+      await fsp__default.default.unlink(oldPath);
       return true;
     } catch {
       return false;
@@ -129,7 +160,7 @@ async function moveFile(oldPath, newPath) {
 __name(moveFile, "moveFile");
 async function getFileStats(path2) {
   try {
-    return await fs__default.default.stat(path2);
+    return await fsp__default.default.stat(path2);
   } catch {
     return null;
   }
@@ -140,16 +171,16 @@ async function createTempFile({ prefix = "tmp-", extension = "", dir = os.tmpdir
   const filename = `${prefix}${crypto.randomUUID()}${ext}`;
   const filepath = path__default.default.join(dir, filename);
   if (content) {
-    await fs__default.default.writeFile(filepath, content);
+    await fsp__default.default.writeFile(filepath, content);
   } else {
-    await fs__default.default.writeFile(filepath, "");
+    await fsp__default.default.writeFile(filepath, "");
   }
   return filepath;
 }
 __name(createTempFile, "createTempFile");
 async function streamFile(source, destination) {
-  const readStream = fs$1.createReadStream(source);
-  const writeStream = fs$1.createWriteStream(destination);
+  const readStream = fs__default.default.createReadStream(source);
+  const writeStream = fs__default.default.createWriteStream(destination);
   try {
     await promises.pipeline(readStream, writeStream);
   } catch (error) {
@@ -160,7 +191,7 @@ async function streamFile(source, destination) {
 }
 __name(streamFile, "streamFile");
 async function readDirectory(dirPath, options = {}) {
-  const files = await fs__default.default.readdir(dirPath);
+  const files = await fsp__default.default.readdir(dirPath);
   let result = files;
   if (options.filter) {
     result = result.filter((file) => options.filter.test(file));
@@ -173,7 +204,7 @@ async function readDirectory(dirPath, options = {}) {
 __name(readDirectory, "readDirectory");
 async function createDirectory(dirPath, recursive = true) {
   try {
-    await fs__default.default.mkdir(dirPath, {
+    await fsp__default.default.mkdir(dirPath, {
       recursive
     });
     return true;
@@ -184,7 +215,7 @@ async function createDirectory(dirPath, recursive = true) {
 __name(createDirectory, "createDirectory");
 async function safeReadJsonFile(path2) {
   try {
-    const content = await fs__default.default.readFile(path2, "utf-8");
+    const content = await fsp__default.default.readFile(path2, "utf-8");
     try {
       const data = JSON.parse(content);
       return {
@@ -207,7 +238,7 @@ async function safeReadJsonFile(path2) {
 __name(safeReadJsonFile, "safeReadJsonFile");
 async function isFile(path2) {
   try {
-    const stat = await fs__default.default.stat(path2);
+    const stat = await fsp__default.default.stat(path2);
     return stat.isFile();
   } catch {
     return false;
@@ -216,7 +247,7 @@ async function isFile(path2) {
 __name(isFile, "isFile");
 async function getFileSize(path2) {
   try {
-    const stat = await fs__default.default.stat(path2);
+    const stat = await fsp__default.default.stat(path2);
     return stat.size;
   } catch {
     return -1;
@@ -225,14 +256,14 @@ async function getFileSize(path2) {
 __name(getFileSize, "getFileSize");
 async function readFileBuffer(path2) {
   try {
-    return await fs__default.default.readFile(path2);
+    return await fsp__default.default.readFile(path2);
   } catch {
     return null;
   }
 }
 __name(readFileBuffer, "readFileBuffer");
 
-exports.appendTextFile = appendTextFile;
+exports.appendFile = appendFile;
 exports.copyFile = copyFile;
 exports.createDirectory = createDirectory;
 exports.createTempFile = createTempFile;
@@ -243,11 +274,14 @@ exports.getFileStats = getFileStats;
 exports.isFile = isFile;
 exports.moveFile = moveFile;
 exports.readDirectory = readDirectory;
+exports.readFile = readFile;
 exports.readFileBuffer = readFileBuffer;
+exports.readFileSync = readFileSync;
 exports.readJsonFile = readJsonFile;
 exports.readJsonOrDefault = readJsonOrDefault;
-exports.readTextFile = readTextFile;
+exports.safeReadFile = safeReadFile;
+exports.safeReadFileSync = safeReadFileSync;
 exports.safeReadJsonFile = safeReadJsonFile;
 exports.streamFile = streamFile;
+exports.writeFile = writeFile;
 exports.writeJsonFile = writeJsonFile;
-exports.writeTextFile = writeTextFile;

package/fs/index.d.ts

@@ -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 };