@catbee/utils 0.0.1 → 0.0.2

package/build/esnext/utils/exception.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"exception.utils.js","sourceRoot":"","sources":["../../../src/utils/exception.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C;;;;OAIG;IACH,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,4BAA6B,SAAQ,aAAa;IAC7D;;OAEG;IACH,YAAY,UAAkB,uBAAuB;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,qBAAqB,CAAC;IACtD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACtD;;OAEG;IACH,YAAY,UAAkB,cAAc;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,YAAY,CAAC;IAC7C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD;;OAEG;IACH,YAAY,UAAkB,aAAa;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD;;OAEG;IACH,YAAY,UAAkB,oBAAoB;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC;IAC1C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD;;OAEG;IACH,YAAY,UAAkB,WAAW;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC;IAC1C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD;;OAEG;IACH,YAAY,UAAkB,UAAU;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC;IACzC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD;;OAEG;IACH,YAAY,UAAkB,aAAa;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACzD;;OAEG;IACH,YAAY,UAAkB,mBAAmB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,iBAAiB,CAAC;IAClD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,aAAa;IAC5D;;OAEG;IACH,YAAY,UAAkB,qBAAqB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,mBAAmB,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,aAAa;IACxD;;OAEG;IACH,YAAY,UAAkB,iBAAiB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,eAAe,CAAC;IAChD,CAAC;CACF","sourcesContent":["import { HttpStatusCodes } from \"./http-status-codes\";\nimport { ErrorResponse } from \"./response.utils\";\n\n/**\n * Generic HTTP error class used for custom exceptions with any status code.\n * Inherit this when you need to throw errors dynamically at runtime.\n */\nexport class HttpError extends ErrorResponse {\n  /**\n   * Creates a new HTTP error instance.\n   * @param status - A valid HTTP status code (e.g., 400, 500).\n   * @param message - The error message to return to the client.\n   */\n  constructor(status: number, message: string) {\n    super(message);\n    this.status = status;\n  }\n}\n\n/**\n * Represents a 500 Internal Server Error.\n * Use this for unexpected backend errors that are not caused by the client.\n */\nexport class InternalServerErrorException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Internal server error\".\n   */\n  constructor(message: string = \"Internal server error\") {\n    super(message);\n    this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;\n  }\n}\n\n/**\n * Represents a 401 Unauthorized Error.\n * Indicates that authentication is required and has failed or not been provided.\n */\nexport class UnauthorizedException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unauthorized\".\n   */\n  constructor(message: string = \"Unauthorized\") {\n    super(message);\n    this.status = HttpStatusCodes.UNAUTHORIZED;\n  }\n}\n\n/**\n * Represents a 400 Bad Request Error.\n * Indicates that the client has sent invalid data (e.g., malformed request body).\n */\nexport class BadRequestException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad request\".\n   */\n  constructor(message: string = \"Bad request\") {\n    super(message);\n    this.status = HttpStatusCodes.BAD_REQUEST;\n  }\n}\n\n/**\n * Represents a 404 Not Found Error.\n * Used when a requested resource (e.g., user, file) could not be located.\n */\nexport class NotFoundException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Resource not found\".\n   */\n  constructor(message: string = \"Resource not found\") {\n    super(message);\n    this.status = HttpStatusCodes.NOT_FOUND;\n  }\n}\n\n/**\n * Represents a 403 Forbidden Error.\n * Indicates that the client is authenticated but not allowed to access the resource.\n */\nexport class ForbiddenException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Forbidden\".\n   */\n  constructor(message: string = \"Forbidden\") {\n    super(message);\n    this.status = HttpStatusCodes.FORBIDDEN;\n  }\n}\n\n/**\n * Represents a 409 Conflict Error.\n * Commonly used when a resource already exists or a versioning conflict occurs.\n */\nexport class ConflictException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Conflict\".\n   */\n  constructor(message: string = \"Conflict\") {\n    super(message);\n    this.status = HttpStatusCodes.CONFLICT;\n  }\n}\n\n/**\n * Represents a 502 Bad Gateway Error.\n * Used when the server receives an invalid response from an upstream server.\n */\nexport class BadGatewayException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad Gateway\".\n   */\n  constructor(message: string = \"Bad Gateway\") {\n    super(message);\n    this.status = HttpStatusCodes.BAD_GATEWAY;\n  }\n}\n\n/**\n * Represents a 429 Too Many Requests Error.\n * Returned when the client has hit a rate limit.\n */\nexport class TooManyRequestsException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Too many requests\".\n   */\n  constructor(message: string = \"Too many requests\") {\n    super(message);\n    this.status = HttpStatusCodes.TOO_MANY_REQUESTS;\n  }\n}\n\n/**\n * Represents a 503 Service Unavailable Error.\n * Indicates that the server is temporarily unavailable (e.g., for maintenance).\n */\nexport class ServiceUnavailableException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Service Unavailable\".\n   */\n  constructor(message: string = \"Service Unavailable\") {\n    super(message);\n    this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;\n  }\n}\n\n/**\n * Represents a 504 Gateway Timeout Error.\n * Returned when the server acting as a gateway times out waiting for a response.\n */\nexport class GatewayTimeoutException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Gateway Timeout\".\n   */\n  constructor(message: string = \"Gateway Timeout\") {\n    super(message);\n    this.status = HttpStatusCodes.GATEWAY_TIMEOUT;\n  }\n}\n"]}
+{"version":3,"file":"exception.utils.js","sourceRoot":"","sources":["../../../src/utils/exception.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { HttpStatusCodes } from \"./http-status-codes\";\nimport { getLogger } from \"./logger.utils\";\nimport { ErrorResponse } from \"./response.utils\";\n\n/**\n * Generic HTTP error class used for custom exceptions with any status code.\n * Inherit this when you need to throw errors dynamically at runtime.\n */\nexport class HttpError extends ErrorResponse {\n  /**\n   * Creates a new HTTP error instance.\n   * @param status - A valid HTTP status code (e.g., 400, 500).\n   * @param message - The error message to return to the client.\n   */\n  constructor(status: number, message: string) {\n    super(message);\n    this.status = status;\n  }\n}\n\n/**\n * Represents a 500 Internal Server Error.\n * Use this for unexpected backend errors that are not caused by the client.\n */\nexport class InternalServerErrorException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Internal server error\".\n   */\n  constructor(message: string = \"Internal server error\") {\n    super(message);\n    this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;\n  }\n}\n\n/**\n * Represents a 401 Unauthorized Error.\n * Indicates that authentication is required and has failed or not been provided.\n */\nexport class UnauthorizedException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unauthorized\".\n   */\n  constructor(message: string = \"Unauthorized\") {\n    super(message);\n    this.status = HttpStatusCodes.UNAUTHORIZED;\n  }\n}\n\n/**\n * Represents a 400 Bad Request Error.\n * Indicates that the client has sent invalid data (e.g., malformed request body).\n */\nexport class BadRequestException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad request\".\n   */\n  constructor(message: string = \"Bad request\") {\n    super(message);\n    this.status = HttpStatusCodes.BAD_REQUEST;\n  }\n}\n\n/**\n * Represents a 404 Not Found Error.\n * Used when a requested resource (e.g., user, file) could not be located.\n */\nexport class NotFoundException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Resource not found\".\n   */\n  constructor(message: string = \"Resource not found\") {\n    super(message);\n    this.status = HttpStatusCodes.NOT_FOUND;\n  }\n}\n\n/**\n * Represents a 403 Forbidden Error.\n * Indicates that the client is authenticated but not allowed to access the resource.\n */\nexport class ForbiddenException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Forbidden\".\n   */\n  constructor(message: string = \"Forbidden\") {\n    super(message);\n    this.status = HttpStatusCodes.FORBIDDEN;\n  }\n}\n\n/**\n * Represents a 409 Conflict Error.\n * Commonly used when a resource already exists or a versioning conflict occurs.\n */\nexport class ConflictException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Conflict\".\n   */\n  constructor(message: string = \"Conflict\") {\n    super(message);\n    this.status = HttpStatusCodes.CONFLICT;\n  }\n}\n\n/**\n * Represents a 502 Bad Gateway Error.\n * Used when the server receives an invalid response from an upstream server.\n */\nexport class BadGatewayException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad Gateway\".\n   */\n  constructor(message: string = \"Bad Gateway\") {\n    super(message);\n    this.status = HttpStatusCodes.BAD_GATEWAY;\n  }\n}\n\n/**\n * Represents a 429 Too Many Requests Error.\n * Returned when the client has hit a rate limit.\n */\nexport class TooManyRequestsException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Too many requests\".\n   */\n  constructor(message: string = \"Too many requests\") {\n    super(message);\n    this.status = HttpStatusCodes.TOO_MANY_REQUESTS;\n  }\n}\n\n/**\n * Represents a 503 Service Unavailable Error.\n * Indicates that the server is temporarily unavailable (e.g., for maintenance).\n */\nexport class ServiceUnavailableException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Service Unavailable\".\n   */\n  constructor(message: string = \"Service Unavailable\") {\n    super(message);\n    this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;\n  }\n}\n\n/**\n * Represents a 504 Gateway Timeout Error.\n * Returned when the server acting as a gateway times out waiting for a response.\n */\nexport class GatewayTimeoutException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Gateway Timeout\".\n   */\n  constructor(message: string = \"Gateway Timeout\") {\n    super(message);\n    this.status = HttpStatusCodes.GATEWAY_TIMEOUT;\n  }\n}\n\n/**\n * Represents a 422 Unprocessable Entity Error.\n * Used when the server understands the content type but cannot process the contained instructions.\n */\nexport class UnprocessableEntityException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unprocessable Entity\".\n   * @param details - Optional validation details or additional error context.\n   */\n  constructor(\n    message: string = \"Unprocessable Entity\",\n    public details?: Record<string, any>,\n  ) {\n    super(message);\n    this.status = HttpStatusCodes.UNPROCESSABLE_ENTITY;\n  }\n}\n\n/**\n * Represents a 405 Method Not Allowed Error.\n * Used when the request method is not supported for the requested resource.\n */\nexport class MethodNotAllowedException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Method Not Allowed\".\n   * @param allowedMethods - Optional array of allowed HTTP methods.\n   */\n  constructor(\n    message: string = \"Method Not Allowed\",\n    public allowedMethods?: string[],\n  ) {\n    super(message);\n    this.status = HttpStatusCodes.METHOD_NOT_ALLOWED;\n  }\n}\n\n/**\n * Represents a 406 Not Acceptable Error.\n * Used when the server cannot produce a response matching the client's accepted content types.\n */\nexport class NotAcceptableException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Not Acceptable\".\n   */\n  constructor(message: string = \"Not Acceptable\") {\n    super(message);\n    this.status = HttpStatusCodes.NOT_ACCEPTABLE;\n  }\n}\n\n/**\n * Represents a 408 Request Timeout Error.\n * Used when the server times out waiting for the client to send a request.\n */\nexport class RequestTimeoutException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Request Timeout\".\n   */\n  constructor(message: string = \"Request Timeout\") {\n    super(message);\n    this.status = HttpStatusCodes.REQUEST_TIMEOUT;\n  }\n}\n\n/**\n * Represents a 415 Unsupported Media Type Error.\n * Used when the request's Content-Type is not supported.\n */\nexport class UnsupportedMediaTypeException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unsupported Media Type\".\n   */\n  constructor(message: string = \"Unsupported Media Type\") {\n    super(message);\n    this.status = HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE;\n  }\n}\n\n/**\n * Represents a 413 Payload Too Large Error.\n * Used when the request body exceeds server limits.\n */\nexport class PayloadTooLargeException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Payload Too Large\".\n   */\n  constructor(message: string = \"Payload Too Large\") {\n    super(message);\n    this.status = HttpStatusCodes.PAYLOAD_TOO_LARGE;\n  }\n}\n\n/**\n * Represents a 507 Insufficient Storage Error.\n * Used when the server has insufficient storage to complete the request.\n */\nexport class InsufficientStorageException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Insufficient Storage\".\n   */\n  constructor(message: string = \"Insufficient Storage\") {\n    super(message);\n    this.status = HttpStatusCodes.INSUFFICIENT_STORAGE;\n  }\n}\n\n/**\n * Checks if an error is an instance of HttpError or its subclasses.\n *\n * @param error - The error to check.\n * @returns True if the error is an HttpError, false otherwise.\n */\nexport function isHttpError(error: unknown): error is ErrorResponse {\n  return error instanceof ErrorResponse;\n}\n\n/**\n * Creates an HTTP error with the specified status code and message.\n * Factory function for creating appropriate HTTP error instances.\n *\n * @param status - HTTP status code.\n * @param message - Optional custom error message.\n * @returns An instance of the appropriate HTTP error class.\n */\nexport function createHttpError(\n  status: number,\n  message?: string,\n): ErrorResponse {\n  switch (status) {\n    case HttpStatusCodes.BAD_REQUEST:\n      return new BadRequestException(message);\n    case HttpStatusCodes.UNAUTHORIZED:\n      return new UnauthorizedException(message);\n    case HttpStatusCodes.FORBIDDEN:\n      return new ForbiddenException(message);\n    case HttpStatusCodes.NOT_FOUND:\n      return new NotFoundException(message);\n    case HttpStatusCodes.METHOD_NOT_ALLOWED:\n      return new MethodNotAllowedException(message);\n    case HttpStatusCodes.NOT_ACCEPTABLE:\n      return new NotAcceptableException(message);\n    case HttpStatusCodes.REQUEST_TIMEOUT:\n      return new RequestTimeoutException(message);\n    case HttpStatusCodes.CONFLICT:\n      return new ConflictException(message);\n    case HttpStatusCodes.GONE:\n      return new HttpError(HttpStatusCodes.GONE, message || \"Gone\");\n    case HttpStatusCodes.PAYLOAD_TOO_LARGE:\n      return new PayloadTooLargeException(message);\n    case HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE:\n      return new UnsupportedMediaTypeException(message);\n    case HttpStatusCodes.UNPROCESSABLE_ENTITY:\n      return new UnprocessableEntityException(message);\n    case HttpStatusCodes.TOO_MANY_REQUESTS:\n      return new TooManyRequestsException(message);\n    case HttpStatusCodes.INTERNAL_SERVER_ERROR:\n      return new InternalServerErrorException(message);\n    case HttpStatusCodes.BAD_GATEWAY:\n      return new BadGatewayException(message);\n    case HttpStatusCodes.SERVICE_UNAVAILABLE:\n      return new ServiceUnavailableException(message);\n    case HttpStatusCodes.GATEWAY_TIMEOUT:\n      return new GatewayTimeoutException(message);\n    case HttpStatusCodes.INSUFFICIENT_STORAGE:\n      return new InsufficientStorageException(message);\n    default:\n      return new HttpError(status, message || `HTTP Error ${status}`);\n  }\n}\n\n/**\n * Type guard to check if an object has specific error properties.\n *\n * @param error - The object to check.\n * @returns True if object has error-like structure.\n */\nexport function hasErrorShape(\n  error: unknown,\n): error is { message: string; status?: number; code?: string } {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as any).message === \"string\"\n  );\n}\n\n/**\n * Safely extracts message from any error type.\n *\n * @param error - Any error object or value.\n * @returns A string error message.\n */\nexport function getErrorMessage(error: unknown): string {\n  if (typeof error === \"string\") {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  if (hasErrorShape(error)) {\n    return error.message;\n  }\n\n  return \"Unknown error occurred\";\n}\n\n/**\n * Wraps a function and transforms any errors into HTTP errors.\n * Useful for API handlers to ensure consistent error responses.\n *\n * @param handler - The async function to wrap.\n * @returns A function that always returns or throws an HTTP error.\n */\nexport function withErrorHandling<T extends (...args: any[]) => Promise<any>>(\n  handler: T,\n): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>> {\n  return async (...args: Parameters<T>) => {\n    try {\n      return await handler(...args);\n    } catch (error) {\n      if (isHttpError(error)) {\n        throw error;\n      }\n\n      // Log the original error (consider using a proper logger)\n      getLogger().error(\"Caught error in handler:\", error);\n\n      // Extract status code if it exists, otherwise use 500\n      let status = HttpStatusCodes.INTERNAL_SERVER_ERROR;\n      if (hasErrorShape(error) && typeof error.status === \"number\") {\n        status = error.status;\n      }\n\n      // Create appropriate HTTP error\n      throw createHttpError(status, getErrorMessage(error));\n    }\n  };\n}\n"]}

package/build/esnext/utils/fs.utils.d.ts

@@ -1,3 +1,5 @@
+import { BufferEncoding } from "./crypto.utils";
+import { Stats } from "fs";
 /**
  * Checks whether a file or directory exists at the given path.
  *
@@ -29,4 +31,134 @@ export declare function writeJsonFile(path: string, data: any, space?: number):
  * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
  */
 export declare function deleteFileIfExists(path: string): Promise<boolean>;
+/**
+ * Reads a text file from the specified path.
+ *
+ * @param {string} path - The path to the text file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
+ */
+export declare function readTextFile(path: string, encoding?: BufferEncoding): Promise<string | null>;
+/**
+ * Writes text 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.
+ */
+export declare function writeTextFile(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.
+ */
+export declare function appendTextFile(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.
+ */
+export 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.
+ */
+export 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<fs.Stats | null>} File stats object or null if file doesn't exist.
+ */
+export declare function getFileStats(path: string): Promise<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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function readFileBuffer(path: string): Promise<Buffer | null>;
 //# sourceMappingURL=fs.utils.d.ts.map

package/build/esnext/utils/fs.utils.js

@@ -1,4 +1,9 @@
 import fs from "fs/promises";
+import { createReadStream, createWriteStream } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import { pipeline } from "stream/promises";
+import { randomUUID } from "crypto";
 /**
  * Checks whether a file or directory exists at the given path.
  *
@@ -59,4 +64,267 @@ export async function deleteFileIfExists(path) {
         return false;
     }
 }
+/**
+ * Reads a text file from the specified path.
+ *
+ * @param {string} path - The path to the text file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
+ */
+export async function readTextFile(path, encoding = "utf-8") {
+    try {
+        return await fs.readFile(path, encoding);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Writes text 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.
+ */
+export async function writeTextFile(path, content, encoding = "utf-8") {
+    try {
+        await fs.writeFile(path, content, encoding);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+export async function appendTextFile(path, content, encoding = "utf-8") {
+    try {
+        await fs.appendFile(path, content, encoding);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+export async function copyFile(source, destination, overwrite = false) {
+    try {
+        const flags = overwrite ? 0 : fs.constants.COPYFILE_EXCL;
+        await fs.copyFile(source, destination, flags);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+export async function moveFile(oldPath, newPath) {
+    try {
+        await fs.rename(oldPath, newPath);
+        return true;
+    }
+    catch (_a) {
+        // If rename fails (e.g., across devices), try copy+delete
+        try {
+            await fs.copyFile(oldPath, newPath);
+            await fs.unlink(oldPath);
+            return true;
+        }
+        catch (_b) {
+            return false;
+        }
+    }
+}
+/**
+ * Gets file stats if the file exists.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.
+ */
+export async function getFileStats(path) {
+    try {
+        return await fs.stat(path);
+    }
+    catch (_a) {
+        return 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.
+ */
+export async function createTempFile({ prefix = "tmp-", extension = "", dir = tmpdir(), content, } = {}) {
+    const ext = extension
+        ? extension.startsWith(".")
+            ? extension
+            : `.${extension}`
+        : "";
+    const filename = `${prefix}${randomUUID()}${ext}`;
+    const filepath = path.join(dir, filename);
+    if (content) {
+        await fs.writeFile(filepath, content);
+    }
+    else {
+        await fs.writeFile(filepath, "");
+    }
+    return filepath;
+}
+/**
+ * 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.
+ */
+export async function streamFile(source, destination) {
+    const readStream = createReadStream(source);
+    const writeStream = createWriteStream(destination);
+    try {
+        await pipeline(readStream, writeStream);
+    }
+    catch (error) {
+        // Ensure both streams are closed in case of error
+        readStream.destroy();
+        writeStream.destroy();
+        throw error;
+    }
+}
+/**
+ * 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.
+ */
+export async function readDirectory(dirPath, options = {}) {
+    const files = await fs.readdir(dirPath);
+    let result = files;
+    if (options.filter) {
+        result = result.filter((file) => options.filter.test(file));
+    }
+    if (options.fullPaths) {
+        result = result.map((file) => path.join(dirPath, file));
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+export async function createDirectory(dirPath, recursive = true) {
+    try {
+        await fs.mkdir(dirPath, { recursive });
+        return true;
+    }
+    catch (err) {
+        // Consider it success if directory already exists
+        return err.code === "EEXIST";
+    }
+}
+/**
+ * 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.
+ */
+export async function safeReadJsonFile(path) {
+    try {
+        const content = await fs.readFile(path, "utf-8");
+        try {
+            const data = JSON.parse(content);
+            return { data, error: null };
+        }
+        catch (error) {
+            return {
+                data: null,
+                error: new Error(`Invalid JSON in file ${path}: ${error.message}`),
+            };
+        }
+    }
+    catch (error) {
+        return {
+            data: null,
+            error: new Error(`Failed to read file ${path}: ${error.message}`),
+        };
+    }
+}
+/**
+ * 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.
+ */
+export async function isFile(path) {
+    try {
+        const stat = await fs.stat(path);
+        return stat.isFile();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+export async function getFileSize(path) {
+    try {
+        const stat = await fs.stat(path);
+        return stat.size;
+    }
+    catch (_a) {
+        return -1;
+    }
+}
+/**
+ * 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.
+ */
+export async function readFileBuffer(path) {
+    try {
+        return await fs.readFile(path);
+    }
+    catch (_a) {
+        return null;
+    }
+}
 //# sourceMappingURL=fs.utils.js.map

package/build/esnext/utils/fs.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.utils.js","sourceRoot":"","sources":["../../../src/utils/fs.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAU,IAAY;IACtD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,IAAS,EACT,KAAK,GAAG,CAAC;IAET,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import fs from \"fs/promises\";\n\n/**\n * Checks whether a file or directory exists at the given path.\n *\n * @param {string} path - The file or directory path to check.\n * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.\n */\nexport async function fileExists(path: string): Promise<boolean> {\n  try {\n    await fs.access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Reads and parses a JSON file from the specified path.\n *\n * @typeParam T - The expected type of the parsed JSON object.\n * @param {string} path - The path to the JSON file.\n * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.\n */\nexport async function readJsonFile<T = any>(path: string): Promise<T | null> {\n  try {\n    const data = await fs.readFile(path, \"utf-8\");\n    return JSON.parse(data) as T;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Writes a JavaScript object to a file as formatted JSON.\n *\n * @param {string} path - The destination file path.\n * @param {any} data - The object to serialize and write.\n * @param {number} [space=2] - Number of spaces for JSON formatting.\n * @returns {Promise<void>} Resolves when writing is complete.\n */\nexport async function writeJsonFile(\n  path: string,\n  data: any,\n  space = 2,\n): Promise<void> {\n  const json = JSON.stringify(data, null, space);\n  await fs.writeFile(path, json, \"utf-8\");\n}\n\n/**\n * Deletes a file if it exists.\n *\n * @param {string} path - The file path to delete.\n * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.\n */\nexport async function deleteFileIfExists(path: string): Promise<boolean> {\n  try {\n    await fs.unlink(path);\n    return true;\n  } catch (err: any) {\n    if (err.code === \"ENOENT\") return true;\n    return false;\n  }\n}\n"]}
+{"version":3,"file":"fs.utils.js","sourceRoot":"","sources":["../../../src/utils/fs.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { BufferEncoding } from \"./crypto.utils\";\nimport fs from \"fs/promises\";\nimport { createReadStream, createWriteStream, Stats } from \"fs\";\nimport { tmpdir } from \"os\";\nimport path from \"path\";\nimport { pipeline } from \"stream/promises\";\nimport { randomUUID } from \"crypto\";\n\n/**\n * Checks whether a file or directory exists at the given path.\n *\n * @param {string} path - The file or directory path to check.\n * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.\n */\nexport async function fileExists(path: string): Promise<boolean> {\n  try {\n    await fs.access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Reads and parses a JSON file from the specified path.\n *\n * @typeParam T - The expected type of the parsed JSON object.\n * @param {string} path - The path to the JSON file.\n * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.\n */\nexport async function readJsonFile<T = any>(path: string): Promise<T | null> {\n  try {\n    const data = await fs.readFile(path, \"utf-8\");\n    return JSON.parse(data) as T;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Writes a JavaScript object to a file as formatted JSON.\n *\n * @param {string} path - The destination file path.\n * @param {any} data - The object to serialize and write.\n * @param {number} [space=2] - Number of spaces for JSON formatting.\n * @returns {Promise<void>} Resolves when writing is complete.\n */\nexport async function writeJsonFile(\n  path: string,\n  data: any,\n  space = 2,\n): Promise<void> {\n  const json = JSON.stringify(data, null, space);\n  await fs.writeFile(path, json, \"utf-8\");\n}\n\n/**\n * Deletes a file if it exists.\n *\n * @param {string} path - The file path to delete.\n * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.\n */\nexport async function deleteFileIfExists(path: string): Promise<boolean> {\n  try {\n    await fs.unlink(path);\n    return true;\n  } catch (err: any) {\n    if (err.code === \"ENOENT\") return true;\n    return false;\n  }\n}\n\n/**\n * Reads a text file from the specified path.\n *\n * @param {string} path - The path to the text file.\n * @param {BufferEncoding} [encoding=\"utf-8\"] - The encoding to use.\n * @returns {Promise<string | null>} The file contents, or `null` if reading fails.\n */\nexport async function readTextFile(\n  path: string,\n  encoding: BufferEncoding = \"utf-8\",\n): Promise<string | null> {\n  try {\n    return await fs.readFile(path, encoding);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Writes text content to a file.\n *\n * @param {string} path - The destination file path.\n * @param {string} content - The text content to write.\n * @param {BufferEncoding} [encoding=\"utf-8\"] - The encoding to use.\n * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.\n */\nexport async function writeTextFile(\n  path: string,\n  content: string,\n  encoding: BufferEncoding = \"utf-8\",\n): Promise<boolean> {\n  try {\n    await fs.writeFile(path, content, encoding);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Appends text content to a file.\n *\n * @param {string} path - The file path to append to.\n * @param {string} content - The text content to append.\n * @param {BufferEncoding} [encoding=\"utf-8\"] - The encoding to use.\n * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.\n */\nexport async function appendTextFile(\n  path: string,\n  content: string,\n  encoding: BufferEncoding = \"utf-8\",\n): Promise<boolean> {\n  try {\n    await fs.appendFile(path, content, encoding);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Copies a file from source to destination.\n *\n * @param {string} source - Source file path.\n * @param {string} destination - Destination file path.\n * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.\n * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.\n */\nexport async function copyFile(\n  source: string,\n  destination: string,\n  overwrite = false,\n): Promise<boolean> {\n  try {\n    const flags = overwrite ? 0 : fs.constants.COPYFILE_EXCL;\n    await fs.copyFile(source, destination, flags);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Renames/moves a file.\n *\n * @param {string} oldPath - Current file path.\n * @param {string} newPath - New file path.\n * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.\n */\nexport async function moveFile(\n  oldPath: string,\n  newPath: string,\n): Promise<boolean> {\n  try {\n    await fs.rename(oldPath, newPath);\n    return true;\n  } catch {\n    // If rename fails (e.g., across devices), try copy+delete\n    try {\n      await fs.copyFile(oldPath, newPath);\n      await fs.unlink(oldPath);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n}\n\n/**\n * Gets file stats if the file exists.\n *\n * @param {string} path - Path to the file.\n * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.\n */\nexport async function getFileStats(path: string): Promise<Stats | null> {\n  try {\n    return await fs.stat(path);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Creates a temporary file with optional content.\n *\n * @param {object} [options] - Options for creating the temp file.\n * @param {string} [options.prefix=\"tmp-\"] - Filename prefix.\n * @param {string} [options.extension=\"\"] - File extension.\n * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).\n * @param {string | Buffer} [options.content] - Optional content to write to the file.\n * @returns {Promise<string>} Path to the created temporary file.\n */\nexport async function createTempFile({\n  prefix = \"tmp-\",\n  extension = \"\",\n  dir = tmpdir(),\n  content,\n}: {\n  prefix?: string;\n  extension?: string;\n  dir?: string;\n  content?: string | Buffer;\n} = {}): Promise<string> {\n  const ext = extension\n    ? extension.startsWith(\".\")\n      ? extension\n      : `.${extension}`\n    : \"\";\n  const filename = `${prefix}${randomUUID()}${ext}`;\n  const filepath = path.join(dir, filename);\n\n  if (content) {\n    await fs.writeFile(filepath, content);\n  } else {\n    await fs.writeFile(filepath, \"\");\n  }\n\n  return filepath;\n}\n\n/**\n * Streams a file from source to destination.\n * Useful for large files to avoid loading the entire file into memory.\n *\n * @param {string} source - Source file path.\n * @param {string} destination - Destination file path.\n * @returns {Promise<void>} Resolves when streaming completes.\n * @throws {Error} If streaming fails.\n */\nexport async function streamFile(\n  source: string,\n  destination: string,\n): Promise<void> {\n  const readStream = createReadStream(source);\n  const writeStream = createWriteStream(destination);\n\n  try {\n    await pipeline(readStream, writeStream);\n  } catch (error) {\n    // Ensure both streams are closed in case of error\n    readStream.destroy();\n    writeStream.destroy();\n    throw error;\n  }\n}\n\n/**\n * Reads a directory and returns file names.\n *\n * @param {string} dirPath - Path to the directory.\n * @param {object} [options] - Options for reading the directory.\n * @param {boolean} [options.fullPaths=false] - Whether to return full paths.\n * @param {RegExp} [options.filter] - Optional regex to filter files.\n * @returns {Promise<string[]>} Array of file names or paths.\n * @throws {Error} If directory cannot be read.\n */\nexport async function readDirectory(\n  dirPath: string,\n  options: { fullPaths?: boolean; filter?: RegExp } = {},\n): Promise<string[]> {\n  const files = await fs.readdir(dirPath);\n\n  let result = files;\n\n  if (options.filter) {\n    result = result.filter((file) => options.filter!.test(file));\n  }\n\n  if (options.fullPaths) {\n    result = result.map((file) => path.join(dirPath, file));\n  }\n\n  return result;\n}\n\n/**\n * Creates a directory if it doesn't exist.\n *\n * @param {string} dirPath - Path to the directory.\n * @param {boolean} [recursive=true] - Whether to create parent directories.\n * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.\n */\nexport async function createDirectory(\n  dirPath: string,\n  recursive = true,\n): Promise<boolean> {\n  try {\n    await fs.mkdir(dirPath, { recursive });\n    return true;\n  } catch (err: any) {\n    // Consider it success if directory already exists\n    return err.code === \"EEXIST\";\n  }\n}\n\n/**\n * Safely reads and parses a JSON file with error details.\n *\n * @typeParam T - The expected type of the parsed JSON object.\n * @param {string} path - The path to the JSON file.\n * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.\n */\nexport async function safeReadJsonFile<T = any>(\n  path: string,\n): Promise<{ data: T | null; error: Error | null }> {\n  try {\n    const content = await fs.readFile(path, \"utf-8\");\n    try {\n      const data = JSON.parse(content) as T;\n      return { data, error: null };\n    } catch (error: any) {\n      return {\n        data: null,\n        error: new Error(`Invalid JSON in file ${path}: ${error.message}`),\n      };\n    }\n  } catch (error: any) {\n    return {\n      data: null,\n      error: new Error(`Failed to read file ${path}: ${error.message}`),\n    };\n  }\n}\n\n/**\n * Checks if a path points to a file (not a directory).\n *\n * @param {string} path - Path to check.\n * @returns {Promise<boolean>} True if the path is a file, false otherwise.\n */\nexport async function isFile(path: string): Promise<boolean> {\n  try {\n    const stat = await fs.stat(path);\n    return stat.isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Gets the size of a file in bytes.\n *\n * @param {string} path - Path to the file.\n * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.\n */\nexport async function getFileSize(path: string): Promise<number> {\n  try {\n    const stat = await fs.stat(path);\n    return stat.size;\n  } catch {\n    return -1;\n  }\n}\n\n/**\n * Reads a file as a Buffer.\n *\n * @param {string} path - Path to the file.\n * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.\n */\nexport async function readFileBuffer(path: string): Promise<Buffer | null> {\n  try {\n    return await fs.readFile(path);\n  } catch {\n    return null;\n  }\n}\n"]}