@decaf-ts/utils/lib/utils/fs.d.ts

module management utils for decaf-ts

import { DependencyMap, SimpleDependencyMap } from "./types";
/**
 * @description Patches a file with given values.
 * @summary Reads a file, applies patches using TextUtils, and writes the result back to the file.
 *
 * @param {string} path - The path to the file to be patched.
 * @param {Record<string, number | string>} values - The values to patch into the file.
 * @return {void}
 *
 * @function patchFile
 *
 * @mermaid
 * sequenceDiagram
 *   participant Caller
 *   participant patchFile
 *   participant fs
 *   participant readFile
 *   participant TextUtils
 *   participant writeFile
 *   Caller->>patchFile: Call with path and values
 *   patchFile->>fs: Check if file exists
 *   patchFile->>readFile: Read file content
 *   readFile->>fs: Read file
 *   fs-->>readFile: Return file content
 *   readFile-->>patchFile: Return file content
 *   patchFile->>TextUtils: Patch string
 *   TextUtils-->>patchFile: Return patched content
 *   patchFile->>writeFile: Write patched content
 *   writeFile->>fs: Write to file
 *   fs-->>writeFile: File written
 *   writeFile-->>patchFile: File written
 *   patchFile-->>Caller: Patching complete
 *
 * @memberOf module:utils
 */
export declare function patchFile(path: string, values: Record<string, number | string>): void;
/**
 * @description Reads a file and returns its content.
 * @summary Reads the content of a file at the specified path and returns it as a string.
 *
 * @param {string} path - The path to the file to be read.
 * @return {string} The content of the file.
 *
 * @function readFile
 *
 * @memberOf module:utils
 */
export declare function readFile(path: string): string;
/**
 * @description Writes data to a file.
 * @summary Writes the provided data to a file at the specified path.
 *
 * @param {string} path - The path to the file to be written.
 * @param {string | Buffer} data - The data to be written to the file.
 * @return {void}
 *
 * @function writeFile
 *
 * @memberOf module:utils
 */
export declare function writeFile(path: string, data: string | Buffer): void;
/**
 * @description Retrieves all files recursively from a directory.
 * @summary Traverses through directories and subdirectories to collect all file paths.
 *
 * @param {string} p - The path to start searching from.
 * @param {function} [filter] - Optional function to filter files by name or index.
 * @return {string[]} Array of file paths.
 *
 * @function getAllFiles
 *
 * @memberOf module:utils
 */
export declare function getAllFiles(p: string, filter?: (f: string, i?: number) => boolean): string[];
/**
 * @description Renames a file or directory.
 * @summary Moves a file or directory from the source path to the destination path.
 *
 * @param {string} source - The source path of the file or directory.
 * @param {string} dest - The destination path for the file or directory.
 * @return {Promise<void>} A promise that resolves when the rename operation is complete.
 *
 * @function renameFile
 *
 * @memberOf module:utils
 */
export declare function renameFile(source: string, dest: string): Promise<void>;
/**
 * @description Copies a file or directory.
 * @summary Creates a copy of a file or directory from the source path to the destination path.
 *
 * @param {string} source - The source path of the file or directory.
 * @param {string} dest - The destination path for the file or directory.
 * @return {void}
 *
 * @function copyFile
 *
 * @memberOf module:utils
 */
export declare function copyFile(source: string, dest: string): void;
/**
 * @description Deletes a file or directory.
 * @summary Removes a file or directory at the specified path, with recursive and force options enabled.
 *
 * @param {string} p - The path to the file or directory to delete.
 * @return {void}
 *
 * @function deletePath
 *
 * @memberOf module:utils
 */
export declare function deletePath(p: string): void;
/**
 * @description Retrieves package information from package.json.
 * @summary Loads and parses the package.json file from a specified directory or the current working directory. Can return the entire package object or a specific property.
 * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
 * @param {string} [property] - Optional. The specific property to retrieve from package.json.
 * @return {object | string} The parsed contents of package.json or the value of the specified property.
 * @function getPackage
 * @mermaid
 * sequenceDiagram
 *   participant Caller
 *   participant getPackage
 *   participant readFile
 *   participant JSON
 *   Caller->>getPackage: Call with path and optional property
 *   getPackage->>readFile: Read package.json
 *   readFile-->>getPackage: Return file content
 *   getPackage->>JSON: Parse file content
 *   JSON-->>getPackage: Return parsed object
 *   alt property specified
 *     getPackage->>getPackage: Check if property exists
 *     alt property exists
 *       getPackage-->>Caller: Return property value
 *     else property doesn't exist
 *       getPackage-->>Caller: Throw Error
 *     end
 *   else no property specified
 *     getPackage-->>Caller: Return entire package object
 *   end
 * @memberOf module:utils
 */
export declare function getPackage(p?: string, property?: string): object | string;
/**
 * @description Sets an attribute in the package.json file.
 * @summary Updates a specific attribute in the package.json file with the provided value.
 *
 * @param {string} attr - The attribute name to set in package.json.
 * @param {string | number | object} value - The value to set for the attribute.
 * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
 * @return {void}
 *
 * @function setPackageAttribute
 *
 * @memberOf module:utils
 */
export declare function setPackageAttribute(attr: string, value: string, p?: string): void;
/**
 * @description Retrieves the version from package.json.
 * @summary A convenience function that calls getPackage to retrieve the "version" property from package.json.
 * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
 * @return {string} The version string from package.json.
 * @function getPackageVersion
 * @memberOf module:utils
 */
export declare function getPackageVersion(p?: string): string;
/**
 * @description Retrieves all dependencies from the project.
 * @summary Executes 'npm ls --json' command to get a detailed list of all dependencies (production, development, and peer) and their versions.
 * @param {string} [path=process.cwd()] - The directory path of the project.
 * @return {Promise<{prod: Array<{name: string, version: string}>, dev: Array<{name: string, version: string}>, peer: Array<{name: string, version: string}>}>} An object containing arrays of production, development, and peer dependencies.
 * @function getDependencies
 * @mermaid
 * sequenceDiagram
 *   participant Caller
 *   participant getDependencies
 *   participant runCommand
 *   participant JSON
 *   Caller->>getDependencies: Call with optional path
 *   getDependencies->>runCommand: Execute 'npm ls --json'
 *   runCommand-->>getDependencies: Return command output
 *   getDependencies->>JSON: Parse command output
 *   JSON-->>getDependencies: Return parsed object
 *   getDependencies->>getDependencies: Process dependencies
 *   getDependencies-->>Caller: Return processed dependencies
 * @memberOf module:utils
 */
export declare function getDependencies(path?: string): Promise<DependencyMap>;
/**
 * @description Updates project dependencies to their latest versions.
 * @summary Runs npm-check-updates to update package.json and then installs the updated dependencies.
 *
 * @return {Promise<void>} A promise that resolves when dependencies are updated.
 *
 * @function updateDependencies
 *
 * @memberOf module:utils
 */
export declare function updateDependencies(): Promise<void>;
/**
 * @description Installs dependencies if they are not already available.
 * @summary Checks if specified dependencies are installed and installs any that are missing.
 *
 * @param {string[] | string} deps - The dependencies to check and potentially install.
 * @param {SimpleDependencyMap} [dependencies] - Optional map of existing dependencies.
 * @return {Promise<SimpleDependencyMap>} Updated map of dependencies.
 *
 * @function installIfNotAvailable
 *
 * @memberOf module:utils
 */
export declare function installIfNotAvailable(deps: string[] | string, dependencies?: SimpleDependencyMap): Promise<SimpleDependencyMap>;
/**
 * @description Pushes changes to Git repository.
 * @summary Temporarily changes Git user configuration, commits all changes, pushes to remote, and restores original user configuration.
 *
 * @return {Promise<void>} A promise that resolves when changes are pushed.
 *
 * @function pushToGit
 *
 * @memberOf module:utils
 */
export declare function pushToGit(): Promise<void>;
/**
 * @description Installs project dependencies.
 * @summary Installs production, development, and peer dependencies as specified.
 *
 * @param {object} dependencies - Object containing arrays of dependencies to install.
 * @param {string[]} [dependencies.prod] - Production dependencies to install.
 * @param {string[]} [dependencies.dev] - Development dependencies to install.
 * @param {string[]} [dependencies.peer] - Peer dependencies to install.
 * @return {Promise<void>} A promise that resolves when all dependencies are installed.
 *
 * @function installDependencies
 *
 * @memberOf module:utils
 */
export declare function installDependencies(dependencies: {
    prod?: string[];
    dev?: string[];
    peer?: string[];
}): Promise<void>;
/**
 * @description Normalizes imports to handle both CommonJS and ESModule formats.
 * @summary Utility function to handle module import differences between formats.
 *
 * @template T - Type of the imported module.
 * @param {Promise<T>} importPromise - Promise returned by dynamic import.
 * @return {Promise<T>} Normalized module.
 *
 * @function normalizeImport
 *
 * @memberOf module:utils
 */
export declare function normalizeImport<T>(importPromise: Promise<T>): Promise<T>;