fs-utils-sync/dist/index.d.ts

The fs-utils-sync package provides a collection of well-tested, synchronous file system utility functions. It promotes consistency and readability across projects by providing a unified approach to common file operations, saving you development time and i

import { Buffer } from 'node:buffer';
import { WriteFileOptions } from 'node:fs';
import { IPathElement, IDirectoryElementsKeySort, IDirectoryElementsOptions, IDirectoryPathElements, IReadFileOptions } from './shared/types.js';
/**
 * Checks if a path exists (file or directory).
 * @param path
 * @returns boolean
 */
declare const pathExists: (path: string) => boolean;
/**
 * Reads the content of a given path and returns the stats. If the path doesn't exist,
 * it returns null
 * @param path
 * @returns IPathElement | null
 */
declare const getPathElement: (path: string) => IPathElement | null;
/**
 * Verifies if a given path exists and is a directory.
 * @param path
 * @returns boolean
 */
declare const isDirectory: (path: string) => boolean;
/**
 * Deletes the directory located in the given path.
 * @param path
 */
declare const deleteDirectory: (path: string) => void;
/**
 * Creates a directory at a given path.
 * @param path
 * @param deleteIfExists?
 * @throws
 * - DIRECTORY_ALREADY_EXISTS: if the directory already exists and deleteIfExists is falsy
 */
declare const createDirectory: (path: string, deleteIfExists?: boolean) => void;
/**
 * It copies a directory (and sub directories) from srcPath to destPath. Keep in mind the destPath
 * is completely overridden.
 * @param srcPath
 * @param destPath
 * @throws
 * - NOT_A_DIRECTORY: if the srcPath is not a directory
 */
declare const copyDirectory: (srcPath: string, destPath: string) => void;
/**
 * Creates a symlink for the target directory at path.
 * @param target
 * @param path
 * @throws
 * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist
 * - NOT_A_DIRECTORY: if the target directory is not considered a directory by the OS
 */
declare const createDirectorySymLink: (target: string, path: string) => void;
/**
 * Reads the contents of a directory based on the provided options and returns them.
 * @param path
 * @param recursive?
 * @returns string[]
 * @throws
 * - NOT_A_DIRECTORY: if the directory is not considered a directory by the OS.
 */
declare const readDirectory: (path: string, recursive?: boolean) => string[];
/**
 * Retrieves all the path elements in the given directory based on the provided options.
 * IMPORTANT: if the includeExts option is provided, make sure to lowercase all
 * extensions (e.g '.json').
 * @param path
 * @param options?
 * @returns IDirectoryPathElements
 * @throws
 * - NOT_A_DIRECTORY: if the directory doesn't exist or is not considered a directory by the OS
 */
declare const getDirectoryElements: (path: string, options?: Partial<IDirectoryElementsOptions>) => IDirectoryPathElements;
/**
 * Verifies if a given path exists and is a file.
 * @param path
 * @returns boolean
 */
declare const isFile: (path: string) => boolean;
/**
 * Creates the base directory for a file in case it doesn't exist and then it writes the file.
 * @param path
 * @param data
 * @param options?
 */
declare const writeFile: (path: string, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions) => void;
/**
 * Writes a text file on a given path.
 * @param path
 * @param data
 * @throws
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if data is not a valid string.
 */
declare const writeTextFile: (path: string, data: string) => void;
/**
 * Writes a JSON file on a given path. If an object is provided, it will be stringified.
 * @param path
 * @param data
 * @param space?
 * @throws
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the JSON content cannot be stringified
 */
declare const writeJSONFile: (path: string, data: Record<string, any> | string, space?: number) => void;
/**
 * Writes a Buffer file on a given path.
 * @param path
 * @param data
 * @throws
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the provided data is not a valid Buffer
 */
declare const writeBufferFile: (path: string, data: Buffer) => void;
/**
 * Reads and returns the contents of a file.
 * @param path
 * @param options?
 * @returns string | Buffer
 * @throws
 * - NOT_A_FILE: if the path is not recognized by the OS as a file or if it doesn't exist
 */
declare const readFile: (path: string, options?: IReadFileOptions) => string | Buffer;
/**
 * Reads a text file and returns its contents.
 * @param path
 * @returns string
 * @throws
 * - NOT_A_FILE: if the path is not recognized by the OS as a file or if it doesn't exist
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the content of the file is empty or invalid
 */
declare const readTextFile: (path: string) => string;
/**
 * Reads a text file, parses and returns its contents.
 * @param path
 * @returns object
 * @throws
 * - NOT_A_FILE: if the path is not recognized by the OS as a file or if it doesn't exist
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the content of the file is empty or invalid
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the file's JSON content cannot be parsed
 */
declare const readJSONFile: (path: string) => Record<string, any>;
/**
 * Reads a Buffer file and returns its contents.
 * @param path
 * @returns Buffer
 * @throws
 * - NOT_A_FILE: if the path is not recognized by the OS as a file or if it doesn't exist
 * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the content of the file is empty or is not a Buffer
 */
declare const readBufferFile: (path: string) => Buffer;
/**
 * Copies a file from srcPath to destPath, replacing the destination if it exists.
 * @param srcPath
 * @param destPath
 * @throws
 * - NOT_A_FILE: if the srcPath doesnt exist or is not recognized as a file by the OS
 */
declare const copyFile: (srcPath: string, destPath: string) => void;
/**
 * Deletes the file located at the provided path.
 * @param path
 * @throws
 * - NOT_A_FILE: if the path doesnt exist or is not recognized as a file by the OS
 */
declare const deleteFile: (path: string) => void;
/**
 * Creates a symlink for a given file.
 * @param target
 * @param path
 * @throws
 * - NON_EXISTENT_FILE: if the target file does not exist
 * - NOT_A_FILE: if the path is not recognized as a file by the OS
 */
declare const createFileSymLink: (target: string, path: string) => void;
export { type IPathElement, type IDirectoryElementsKeySort, type IDirectoryElementsOptions, type IDirectoryPathElements, pathExists, getPathElement, isDirectory, createDirectory, copyDirectory, deleteDirectory, createDirectorySymLink, readDirectory, getDirectoryElements, isFile, writeFile, writeTextFile, writeJSONFile, writeBufferFile, readFile, readTextFile, readJSONFile, readBufferFile, copyFile, deleteFile, createFileSymLink, };