@altostra/core/lib/common/Utils/FS.d.ts

Core library for shared types and logic

/// <reference types="node" />
import { createWriteStream } from 'fs';
import type { AnyTypeValidation } from '@altostra/type-validations';
import type { Options as RimrafOptions } from 'rimraf';
import type { NonEmptyString } from "../CustomTypes/NonEmptyString";
import type { Void } from "../Types";
declare type RmEntireDir = (path: string, options?: RimrafOptions) => Promise<void>;
export declare const rmEntireDir: RmEntireDir;
/**
 * Creates a unique temporary directory in the *OS temp directory*.
 *
 * Generates six random characters to be appended behind a required `prefix` to create a unique temporary directory.
 *
 * Some platforms, notably the BSDs, can return more than six random characters.
 * @param prefix The prefix to prepend to the temp directory name.
 * If the prefix does not end with a hyphen `-` character, a hyphen would be appended.
 * @returns The created folder path.
 */
export declare function createTempDir(prefix: string): Promise<string>;
/**
 * Checks if a files exists
 *
 * **Be aware that this functionality is prone to race conditions**
 * @param path The path to check
 * @returns `true` if a file in the provided path exists; otherwise `false`.
 */
export declare function exists(path: string): Promise<boolean>;
/**
 * Deletes a file if it exists
 * @param path The file path to delete
 */
export declare function deleteIfExists(path: string): Promise<void>;
export declare function getMimeType(filename: string): string;
export declare function loadJsonFile(pathOrStream: NodeJS.ReadStream | string): Promise<unknown>;
export declare function loadJsonFile<T>(pathOrStream: NodeJS.ReadableStream | string, typeValidation: AnyTypeValidation<T>): Promise<T>;
declare type JsonParams = Parameters<JSON['stringify']>;
export interface JsonOptions {
    replacer?: (this: any, key: string, value: any) => any;
    indent?: JsonParams[2];
}
export declare type FileCreationOptions = Parameters<typeof createWriteStream>[1] & object & {
    createDir?: boolean;
};
export declare type SaveJsonFileOptions = FileCreationOptions & JsonOptions;
export declare function saveJsonFile(stream: NodeJS.WriteStream, data: unknown, options?: JsonOptions): Promise<Void>;
export declare function saveJsonFile(path: string, data: unknown, options?: SaveJsonFileOptions): Promise<Void>;
export interface YamlOptions extends JsonOptions {
    indent?: number;
}
export declare type SaveYamlFileOptions = FileCreationOptions & YamlOptions;
export declare function saveYamlFile(stream: NodeJS.WriteStream, data: unknown, options?: YamlOptions): Promise<Void>;
export declare function saveYamlFile(path: string, data: unknown, options?: SaveYamlFileOptions): Promise<Void>;
export declare function saveTextFile(stream: NodeJS.WriteStream, data: string): Promise<Void>;
export declare function saveTextFile(path: string, data: string, options?: FileCreationOptions): Promise<Void>;
export declare function saveTextFile(pathOrStream: NodeJS.WriteStream | string, data: string, options?: FileCreationOptions): Promise<Void>;
export declare function resolvePathInHomeDir(target: string): string;
/**
 * Returns a string where where the illegal characters are replaced with a replacement
 * @param fileName The file name to remove illegal characters from
 * @param replacement Optional replacement for illegal characters (default: `'_'`)
 */
export declare function replaceIllegalFileNameCharacters(fileName: string, replacement?: NonEmptyString): NonEmptyString;
declare const pathLiteralSym: unique symbol;
/**
 * A value that will not be escaped when used as value in `asPath` tagged template
 */
export interface PathLiteral {
    [pathLiteralSym]: string;
}
/**
 * Create a `PathLiteral` for a given value
 * @param literalValue A value that will not be escaped when used as value in `asPath`
 * tagged template
 */
export declare function pathLiteral(literalValue: string): PathLiteral;
/**
 * A tagged template that replace illegal file-name character in the provided values
 * with `'_'` and normalize the end result.
 *
 * @example
 * const safeSubDir = 'dir1/dir2'
 * const unsafeDirName = 'dirDoubleDot/..'
 * const unsafeFileName = '../../my-file'
 *
 * const filePath = asPath`~/dir/${unsafeDirName}/${pathLiteral(safeSubDir)}/${unsafeFileName}.json`
 *
 * assert(filePath === '~/dir/dirDoubleDot_../dir1/dir2/.._.._my-file.json')
 * @returns An escaped path
 */
export declare function asPath(strings: TemplateStringsArray, ...values: unknown[]): string;
export {};