/**
* Core libraries that every NodeJS toolchain project should use.
*
* @packageDocumentation
*/
///
import * as child_process from 'child_process';
import * as fs from 'fs';
/**
* Specifies the behavior of {@link FileSystem.copyFiles} in a situation where the target object
* already exists.
* @public
*/
export declare const enum AlreadyExistsBehavior {
/**
* If the destination object exists, overwrite it.
* This is the default behavior for {@link FileSystem.copyFiles}.
*/
Overwrite = "overwrite",
/**
* If the destination object exists, report an error.
*/
Error = "error",
/**
* If the destination object exists, skip it and continue the operation.
*/
Ignore = "ignore"
}
/**
* This exception can be thrown to indicate that an operation failed and an error message has already
* been reported appropriately. Thus, the catch handler does not have responsibility for reporting
* the error.
*
* @remarks
* For example, suppose a tool writes interactive output to `console.log()`. When an exception is thrown,
* the `catch` handler will typically provide simplistic reporting such as this:
*
* ```ts
* catch (error) {
* console.log("ERROR: " + error.message);
* }
* ```
*
* Suppose that the code performing the operation normally prints rich output to the console. It may be able to
* present an error message more nicely (for example, as part of a table, or structured log format). Throwing
* `AlreadyReportedError` provides a way to use exception handling to abort the operation, but instruct the `catch`
* handler not to print an error a second time:
*
* ```ts
* catch (error) {
* if (error instanceof AlreadyReportedError) {
* return;
* }
* console.log("ERROR: " + error.message);
* }
* ```
*
* @public
*/
export declare class AlreadyReportedError extends Error {
constructor();
static [Symbol.hasInstance](instance: object): boolean;
}
/**
* Operations for working with text strings that contain
* {@link https://en.wikipedia.org/wiki/ANSI_escape_code | ANSI escape codes}.
* The most commonly used escape codes set the foreground/background color for console output.
* @public
*/
export declare class AnsiEscape {
private static readonly _csiRegExp;
private static readonly _sgrRegExp;
private static readonly _backslashNRegExp;
private static readonly _backslashRRegExp;
/**
* Returns the input text with all ANSI escape codes removed. For example, this is useful when saving
* colorized console output to a log file.
*/
static removeCodes(text: string): string;
/**
* Replaces ANSI escape codes with human-readable tokens. This is useful for unit tests
* that compare text strings in test assertions or snapshot files.
*/
static formatForTests(text: string, options?: IAnsiEscapeConvertForTestsOptions): string;
private static _tryGetSgrFriendlyName;
}
/**
* A "branded type" is a primitive type with a compile-type key that makes it incompatible with other
* aliases for the primitive type.
*
* @remarks
*
* Example usage:
*
* ```ts
* // PhoneNumber is a branded type based on the "string" primitive.
* type PhoneNumber = Brand;
*
* function createPhoneNumber(input: string): PhoneNumber {
* if (!/\d+(\-\d+)+/.test(input)) {
* throw new Error('Invalid phone number: ' + JSON.stringify(input));
* }
* return input as PhoneNumber;
* }
*
* const p1: PhoneNumber = createPhoneNumber('123-456-7890');
*
* // PhoneNumber is a string and can be used as one:
* const p2: string = p1;
*
* // But an arbitrary string cannot be implicitly type cast as PhoneNumber.
* // ERROR: Type 'string' is not assignable to type 'PhoneNumber'
* const p3: PhoneNumber = '123-456-7890';
* ```
*
* For more information about this pattern, see {@link
* https://github.com/Microsoft/TypeScript/blob/7b48a182c05ea4dea81bab73ecbbe9e013a79e99/src/compiler/types.ts#L693-L698
* | this comment} explaining the TypeScript compiler's introduction of this pattern, and
* {@link https://spin.atomicobject.com/2018/01/15/typescript-flexible-nominal-typing/ | this article}
* explaining the technique in depth.
*
* @public
*/
export declare type Brand = T & {
__brand: BrandTag;
};
/**
* The static functions on this class are used to produce colored text
* for use with the node-core-library terminal.
*
* @example
* terminal.writeLine(Colors.green('Green Text!'), ' ', Colors.blue('Blue Text!'));
*
* @beta
*/
export declare class Colors {
static black(text: string | IColorableSequence): IColorableSequence;
static red(text: string | IColorableSequence): IColorableSequence;
static green(text: string | IColorableSequence): IColorableSequence;
static yellow(text: string | IColorableSequence): IColorableSequence;
static blue(text: string | IColorableSequence): IColorableSequence;
static magenta(text: string | IColorableSequence): IColorableSequence;
static cyan(text: string | IColorableSequence): IColorableSequence;
static white(text: string | IColorableSequence): IColorableSequence;
static gray(text: string | IColorableSequence): IColorableSequence;
static blackBackground(text: string | IColorableSequence): IColorableSequence;
static redBackground(text: string | IColorableSequence): IColorableSequence;
static greenBackground(text: string | IColorableSequence): IColorableSequence;
static yellowBackground(text: string | IColorableSequence): IColorableSequence;
static blueBackground(text: string | IColorableSequence): IColorableSequence;
static magentaBackground(text: string | IColorableSequence): IColorableSequence;
static cyanBackground(text: string | IColorableSequence): IColorableSequence;
static whiteBackground(text: string | IColorableSequence): IColorableSequence;
static grayBackground(text: string | IColorableSequence): IColorableSequence;
static bold(text: string | IColorableSequence): IColorableSequence;
static dim(text: string | IColorableSequence): IColorableSequence;
static underline(text: string | IColorableSequence): IColorableSequence;
static blink(text: string | IColorableSequence): IColorableSequence;
static invertColor(text: string | IColorableSequence): IColorableSequence;
static hidden(text: string | IColorableSequence): IColorableSequence;
/**
* If called with a string, returns the string wrapped in a {@link IColorableSequence}.
* If called with a {@link IColorableSequence}, returns the {@link IColorableSequence}.
*
* @internal
*/
static _normalizeStringOrColorableSequence(value: string | IColorableSequence): IColorableSequence;
private static _applyTextAttribute;
}
/**
* Colors used with {@link IColorableSequence}.
* @beta
*/
export declare enum ColorValue {
Black = 0,
Red = 1,
Green = 2,
Yellow = 3,
Blue = 4,
Magenta = 5,
Cyan = 6,
White = 7,
Gray = 8
}
/**
* Terminal provider that prints to STDOUT (for log- and verbose-level messages) and
* STDERR (for warning- and error-level messsages).
*
* @beta
*/
export declare class ConsoleTerminalProvider implements ITerminalProvider {
/**
* If true, verbose-level messages should be written to the console.
*/
verboseEnabled: boolean;
constructor(options?: Partial);
/**
* {@inheritDoc ITerminalProvider.write}
*/
write(data: string, severity: TerminalProviderSeverity): void;
/**
* {@inheritDoc ITerminalProvider.eolCharacter}
*/
get eolCharacter(): string;
/**
* {@inheritDoc ITerminalProvider.supportsColor}
*/
get supportsColor(): boolean;
}
/**
* The allowed types of encodings, as supported by Node.js
* @public
*/
export declare const enum Encoding {
Utf8 = "utf8"
}
/**
* A helper for looking up TypeScript `enum` keys/values.
*
* @remarks
* TypeScript enums implement a lookup table for mapping between their keys and values:
*
* ```ts
* enum Colors {
* Red = 1
* }
*
* // Prints "Red"
* console.log(Colors[1]);
*
* // Prints "1"
* console.log(Colors["Red]);
* ```
*
* However the compiler's "noImplicitAny" validation has trouble with these mappings, because
* there are so many possible types for the map elements:
*
* ```ts
* function f(s: string): Colors | undefined {
* // (TS 7015) Element implicitly has an 'any' type because
* // index expression is not of type 'number'.
* return Colors[s];
* }
* ```
*
* The `Enum` helper provides a more specific, strongly typed way to access members:
*
* ```ts
* function f(s: string): Colors | undefined {
* return Enum.tryGetValueByKey(Colors, s);
* }
* ```
*
* @public
*/
export declare class Enum {
private constructor();
/**
* Returns an enum value, given its key. Returns `undefined` if no matching key is found.
*
* @example
*
* Example usage:
* ```ts
* enum Colors {
* Red = 1
* }
*
* // Prints "1"
* console.log(Enum.tryGetValueByKey(Colors, "Red"));
*
* // Prints "undefined"
* console.log(Enum.tryGetValueByKey(Colors, "Black"));
* ```
*/
static tryGetValueByKey(enumObject: {
[key: string]: TEnumValue | string;
[key: number]: TEnumValue | string;
}, key: string): TEnumValue | undefined;
/**
* This API is similar to {@link Enum.tryGetValueByKey}, except that it throws an exception
* if the key is undefined.
*/
static getValueByKey(enumObject: {
[key: string]: TEnumValue | string;
[key: number]: TEnumValue | string;
}, key: string): TEnumValue;
/**
* Returns an enum string key, given its numeric value. Returns `undefined` if no matching value
* is found.
*
* @remarks
* The TypeScript compiler only creates a reverse mapping for enum members whose value is numeric.
* For example:
*
* ```ts
* enum E {
* A = 1,
* B = 'c'
* }
*
* // Prints "A"
* console.log(E[1]);
*
* // Prints "undefined"
* console.log(E["c"]);
* ```
*
* @example
*
* Example usage:
* ```ts
* enum Colors {
* Red = 1,
* Blue = 'blue'
* }
*
* // Prints "Red"
* console.log(Enum.tryGetKeyByNumber(Colors, 1));
*
* // Prints "undefined"
* console.log(Enum.tryGetKeyByNumber(Colors, -1));
* ```
*/
static tryGetKeyByNumber(enumObject: TEnumObject, value: number): keyof typeof enumObject | undefined;
/**
* This API is similar to {@link Enum.tryGetKeyByNumber}, except that it throws an exception
* if the key is undefined.
*/
static getKeyByNumber(enumObject: TEnumObject, value: number): keyof typeof enumObject;
}
/**
* The Executable class provides a safe, portable, recommended solution for tools that need
* to launch child processes.
*
* @remarks
* The NodeJS child_process API provides a solution for launching child processes, however
* its design encourages reliance on the operating system shell for certain features.
* Invoking the OS shell is not safe, not portable, and generally not recommended:
*
* - Different shells have different behavior and command-line syntax, and which shell you
* will get with NodeJS is unpredictable. There is no universal shell guaranteed to be
* available on all platforms.
*
* - If a command parameter contains symbol characters, a shell may interpret them, which
* can introduce a security vulnerability
*
* - Each shell has different rules for escaping these symbols. On Windows, the default
* shell is incapable of escaping certain character sequences.
*
* The Executable API provides a pure JavaScript implementation of primitive shell-like
* functionality for searching the default PATH, appending default file extensions on Windows,
* and executing a file that may contain a POSIX shebang. This primitive functionality
* is sufficient (and recommended) for most tooling scenarios.
*
* If you need additional shell features such as wildcard globbing, environment variable
* expansion, piping, or built-in commands, then we recommend to use the `@microsoft/rushell`
* library instead. Rushell is a pure JavaScript shell with a standard syntax that is
* guaranteed to work consistently across all platforms.
*
* @public
*/
export declare class Executable {
/**
* Synchronously create a child process and optionally capture its output.
*
* @remarks
* This function is similar to child_process.spawnSync(). The main differences are:
*
* - It does not invoke the OS shell unless the executable file is a shell script.
* - Command-line arguments containing special characters are more accurately passed
* through to the child process.
* - If the filename is missing a path, then the shell's default PATH will be searched.
* - If the filename is missing a file extension, then Windows default file extensions
* will be searched.
*
* @param filename - The name of the executable file. This string must not contain any
* command-line arguments. If the name contains any path delimiters, then the shell's
* default PATH will not be searched.
* @param args - The command-line arguments to be passed to the process.
* @param options - Additional options
* @returns the same data type as returned by the NodeJS child_process.spawnSync() API
*
* @privateRemarks
*
* NOTE: The NodeJS spawnSync() returns SpawnSyncReturns or SpawnSyncReturns
* polymorphically based on the options.encoding parameter value. This is a fairly confusing
* design. In most cases, developers want string with the default encoding. If/when someone
* wants binary output or a non-default text encoding, we will introduce a separate API function
* with a name like "spawnWithBufferSync".
*/
static spawnSync(filename: string, args: string[], options?: IExecutableSpawnSyncOptions): child_process.SpawnSyncReturns;
/**
* Given a filename, this determines the absolute path of the executable file that would
* be executed by a shell:
*
* - If the filename is missing a path, then the shell's default PATH will be searched.
* - If the filename is missing a file extension, then Windows default file extensions
* will be searched.
*
* @remarks
*
* @param filename - The name of the executable file. This string must not contain any
* command-line arguments. If the name contains any path delimiters, then the shell's
* default PATH will not be searched.
* @param options - optional other parameters
* @returns the absolute path of the executable, or undefined if it was not found
*/
static tryResolve(filename: string, options?: IExecutableResolveOptions): string | undefined;
private static _tryResolve;
private static _tryResolveFileExtension;
/**
* This is used when searching the shell PATH for an executable, to determine
* whether a match should be skipped or not. If it returns true, this does not
* guarantee that the file can be successfully executed.
*/
private static _canExecute;
/**
* Returns the list of folders where we will search for an executable,
* based on the PATH environment variable.
*/
private static _getSearchFolders;
private static _getExecutableContext;
/**
* Given an input string containing special symbol characters, this inserts the "^" escape
* character to ensure the symbols are interpreted literally by the Windows shell.
*/
private static _getEscapedForWindowsShell;
/**
* Checks for characters that are unsafe to pass to a Windows batch file
* due to the way that cmd.exe implements escaping.
*/
private static _validateArgsForWindowsShell;
}
/**
* Typings for IExecutableSpawnSyncOptions.stdio.
* @public
*/
export declare type ExecutableStdioMapping = 'pipe' | 'ignore' | 'inherit' | ExecutableStdioStreamMapping[];
/**
* Typings for one of the streams inside IExecutableSpawnSyncOptions.stdio.
* @public
*/
export declare type ExecutableStdioStreamMapping = 'pipe' | 'ignore' | 'inherit' | NodeJS.WritableStream | NodeJS.ReadableStream | number | undefined;
/**
* String constants for common filenames and parts of filenames.
*
* @public
*/
export declare const enum FileConstants {
/**
* "package.json" - the configuration file that defines an NPM package
*/
PackageJson = "package.json"
}
/**
* The FileSystem API provides a complete set of recommended operations for interacting with the file system.
*
* @remarks
* We recommend to use this instead of the native `fs` API, because `fs` is a minimal set of low-level
* primitives that must be mapped for each supported operating system. The FileSystem API takes a
* philosophical approach of providing "one obvious way" to do each operation. We also prefer synchronous
* operations except in cases where there would be a clear performance benefit for using async, since synchronous
* code is much easier to read and debug. Also, indiscriminate parallelism has been seen to actually worsen
* performance, versus improving it.
*
* Note that in the documentation, we refer to "filesystem objects", this can be a
* file, folder, symbolic link, hard link, directory junction, etc.
*
* @public
*/
export declare class FileSystem {
/**
* Returns true if the path exists on disk.
* Behind the scenes it uses `fs.existsSync()`.
* @remarks
* There is a debate about the fact that after `fs.existsSync()` returns true,
* the file might be deleted before fs.readSync() is called, which would imply that everybody
* should catch a `readSync()` exception, and nobody should ever use `fs.existsSync()`.
* We find this to be unpersuasive, since "unexceptional exceptions" really hinder the
* break-on-exception debugging experience. Also, throwing/catching is generally slow.
* @param path - The absolute or relative path to the filesystem object.
*/
static exists(path: string): boolean;
/**
* An async version of {@link FileSystem.exists}.
*/
static existsAsync(path: string): Promise;
/**
* Gets the statistics for a particular filesystem object.
* If the path is a link, this function follows the link and returns statistics about the link target.
* Behind the scenes it uses `fs.statSync()`.
* @param path - The absolute or relative path to the filesystem object.
*/
static getStatistics(path: string): FileSystemStats;
/**
* An async version of {@link FileSystem.getStatistics}.
*/
static getStatisticsAsync(path: string): Promise;
/**
* Updates the accessed and modified timestamps of the filesystem object referenced by path.
* Behind the scenes it uses `fs.utimesSync()`.
* The caller should specify both times in the `times` parameter.
* @param path - The path of the file that should be modified.
* @param times - The times that the object should be updated to reflect.
*/
static updateTimes(path: string, times: IFileSystemUpdateTimeParameters): void;
/**
* An async version of {@link FileSystem.updateTimes}.
*/
static updateTimesAsync(path: string, times: IFileSystemUpdateTimeParameters): Promise;
/**
* Changes the permissions (i.e. file mode bits) for a filesystem object.
* Behind the scenes it uses `fs.chmodSync()`.
* @param path - The absolute or relative path to the object that should be updated.
* @param modeBits - POSIX-style file mode bits specified using the {@link PosixModeBits} enum
*/
static changePosixModeBits(path: string, mode: PosixModeBits): void;
/**
* An async version of {@link FileSystem.changePosixModeBits}.
*/
static changePosixModeBitsAsync(path: string, mode: PosixModeBits): Promise;
/**
* Retrieves the permissions (i.e. file mode bits) for a filesystem object.
* Behind the scenes it uses `fs.chmodSync()`.
* @param path - The absolute or relative path to the object that should be updated.
*
* @remarks
* This calls {@link FileSystem.getStatistics} to get the POSIX mode bits.
* If statistics in addition to the mode bits are needed, it is more efficient
* to call {@link FileSystem.getStatistics} directly instead.
*/
static getPosixModeBits(path: string): PosixModeBits;
/**
* An async version of {@link FileSystem.getPosixModeBits}.
*/
static getPosixModeBitsAsync(path: string): Promise;
/**
* Returns a 10-character string representation of a PosixModeBits value similar to what
* would be displayed by a command such as "ls -l" on a POSIX-like operating system.
* @remarks
* For example, `PosixModeBits.AllRead | PosixModeBits.AllWrite` would be formatted as "-rw-rw-rw-".
* @param modeBits - POSIX-style file mode bits specified using the {@link PosixModeBits} enum
*/
static formatPosixModeBits(modeBits: PosixModeBits): string;
/**
* Moves a file. The folder must exist, unless the `ensureFolderExists` option is provided.
* Behind the scenes it uses `fs-extra.moveSync()`
*/
static move(options: IFileSystemMoveOptions): void;
/**
* An async version of {@link FileSystem.move}.
*/
static moveAsync(options: IFileSystemMoveOptions): Promise;
/**
* Recursively creates a folder at a given path.
* Behind the scenes is uses `fs-extra.ensureDirSync()`.
* @remarks
* Throws an exception if anything in the folderPath is not a folder.
* @param folderPath - The absolute or relative path of the folder which should be created.
*/
static ensureFolder(folderPath: string): void;
/**
* An async version of {@link FileSystem.ensureFolder}.
*/
static ensureFolderAsync(folderPath: string): Promise;
/**
* Reads the contents of the folder, not including "." or "..".
* Behind the scenes it uses `fs.readdirSync()`.
* @param folderPath - The absolute or relative path to the folder which should be read.
* @param options - Optional settings that can change the behavior. Type: `IReadFolderOptions`
*/
static readFolder(folderPath: string, options?: IFileSystemReadFolderOptions): string[];
/**
* An async version of {@link FileSystem.readFolder}.
*/
static readFolderAsync(folderPath: string, options?: IFileSystemReadFolderOptions): Promise;
/**
* Deletes a folder, including all of its contents.
* Behind the scenes is uses `fs-extra.removeSync()`.
* @remarks
* Does not throw if the folderPath does not exist.
* @param folderPath - The absolute or relative path to the folder which should be deleted.
*/
static deleteFolder(folderPath: string): void;
/**
* An async version of {@link FileSystem.deleteFolder}.
*/
static deleteFolderAsync(folderPath: string): Promise;
/**
* Deletes the content of a folder, but not the folder itself. Also ensures the folder exists.
* Behind the scenes it uses `fs-extra.emptyDirSync()`.
* @remarks
* This is a workaround for a common race condition, where the virus scanner holds a lock on the folder
* for a brief period after it was deleted, causing EBUSY errors for any code that tries to recreate the folder.
* @param folderPath - The absolute or relative path to the folder which should have its contents deleted.
*/
static ensureEmptyFolder(folderPath: string): void;
/**
* An async version of {@link FileSystem.ensureEmptyFolder}.
*/
static ensureEmptyFolderAsync(folderPath: string): Promise;
/**
* Writes a text string to a file on disk, overwriting the file if it already exists.
* Behind the scenes it uses `fs.writeFileSync()`.
* @remarks
* Throws an error if the folder doesn't exist, unless ensureFolder=true.
* @param filePath - The absolute or relative path of the file.
* @param contents - The text that should be written to the file.
* @param options - Optional settings that can change the behavior. Type: `IWriteFileOptions`
*/
static writeFile(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): void;
/**
* An async version of {@link FileSystem.writeFile}.
*/
static writeFileAsync(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): Promise;
/**
* Writes a text string to a file on disk, appending to the file if it already exists.
* Behind the scenes it uses `fs.appendFileSync()`.
* @remarks
* Throws an error if the folder doesn't exist, unless ensureFolder=true.
* @param filePath - The absolute or relative path of the file.
* @param contents - The text that should be written to the file.
* @param options - Optional settings that can change the behavior. Type: `IWriteFileOptions`
*/
static appendToFile(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): void;
/**
* An async version of {@link FileSystem.appendToFile}.
*/
static appendToFileAsync(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): Promise;
/**
* Reads the contents of a file into a string.
* Behind the scenes it uses `fs.readFileSync()`.
* @param filePath - The relative or absolute path to the file whose contents should be read.
* @param options - Optional settings that can change the behavior. Type: `IReadFileOptions`
*/
static readFile(filePath: string, options?: IFileSystemReadFileOptions): string;
/**
* An async version of {@link FileSystem.readFile}.
*/
static readFileAsync(filePath: string, options?: IFileSystemReadFileOptions): Promise;
/**
* Reads the contents of a file into a buffer.
* Behind the scenes is uses `fs.readFileSync()`.
* @param filePath - The relative or absolute path to the file whose contents should be read.
*/
static readFileToBuffer(filePath: string): Buffer;
/**
* An async version of {@link FileSystem.readFileToBuffer}.
*/
static readFileToBufferAsync(filePath: string): Promise;
/**
* Copies a single file from one location to another.
* By default, destinationPath is overwritten if it already exists.
*
* @remarks
* The `copyFile()` API cannot be used to copy folders. It copies at most one file.
* Use {@link FileSystem.copyFiles} if you need to recursively copy a tree of folders.
*
* The implementation is based on `copySync()` from the `fs-extra` package.
*/
static copyFile(options: IFileSystemCopyFileOptions): void;
/**
* An async version of {@link FileSystem.copyFile}.
*/
static copyFileAsync(options: IFileSystemCopyFileOptions): Promise;
/**
* Copies a single file from one location to one or more other locations.
* By default, the file at the destination is overwritten if it already exists.
*
* @remarks
* The `copyFileToManyAsync()` API cannot be used to copy folders. It copies at most one file.
*
* The implementation is based on `createReadStream()` and `createWriteStream()` from the
* `fs-extra` package.
*/
static copyFileToManyAsync(options: IFileSystemCopyFileToManyOptions): Promise;
/**
* Copies a file or folder from one location to another, recursively copying any folder contents.
* By default, destinationPath is overwritten if it already exists.
*
* @remarks
* If you only intend to copy a single file, it is recommended to use {@link FileSystem.copyFile}
* instead to more clearly communicate the intended operation.
*
* The implementation is based on `copySync()` from the `fs-extra` package.
*/
static copyFiles(options: IFileSystemCopyFilesOptions): void;
/**
* An async version of {@link FileSystem.copyFiles}.
*/
static copyFilesAsync(options: IFileSystemCopyFilesOptions): Promise;
/**
* Deletes a file. Can optionally throw if the file doesn't exist.
* Behind the scenes it uses `fs.unlinkSync()`.
* @param filePath - The absolute or relative path to the file that should be deleted.
* @param options - Optional settings that can change the behavior. Type: `IDeleteFileOptions`
*/
static deleteFile(filePath: string, options?: IFileSystemDeleteFileOptions): void;
/**
* An async version of {@link FileSystem.deleteFile}.
*/
static deleteFileAsync(filePath: string, options?: IFileSystemDeleteFileOptions): Promise;
/**
* Gets the statistics of a filesystem object. Does NOT follow the link to its target.
* Behind the scenes it uses `fs.lstatSync()`.
* @param path - The absolute or relative path to the filesystem object.
*/
static getLinkStatistics(path: string): FileSystemStats;
/**
* An async version of {@link FileSystem.getLinkStatistics}.
*/
static getLinkStatisticsAsync(path: string): Promise;
/**
* If `path` refers to a symbolic link, this returns the path of the link target, which may be
* an absolute or relative path.
*
* @remarks
* If `path` refers to a filesystem object that is not a symbolic link, then an `ErrnoException` is thrown
* with code 'UNKNOWN'. If `path` does not exist, then an `ErrnoException` is thrown with code `ENOENT`.
*
* @param path - The absolute or relative path to the symbolic link.
* @returns the path of the link target
*/
static readLink(path: string): string;
/**
* An async version of {@link FileSystem.readLink}.
*/
static readLinkAsync(path: string): Promise;
/**
* Creates a Windows "directory junction". Behaves like `createSymbolicLinkToFile()` on other platforms.
* Behind the scenes it uses `fs.symlinkSync()`.
*/
static createSymbolicLinkJunction(options: IFileSystemCreateLinkOptions): void;
/**
* An async version of {@link FileSystem.createSymbolicLinkJunction}.
*/
static createSymbolicLinkJunctionAsync(options: IFileSystemCreateLinkOptions): Promise;
/**
* Creates a symbolic link to a file (on Windows this requires elevated permissionsBits).
* Behind the scenes it uses `fs.symlinkSync()`.
*/
static createSymbolicLinkFile(options: IFileSystemCreateLinkOptions): void;
/**
* An async version of {@link FileSystem.createSymbolicLinkFile}.
*/
static createSymbolicLinkFileAsync(options: IFileSystemCreateLinkOptions): Promise;
/**
* Creates a symbolic link to a folder (on Windows this requires elevated permissionsBits).
* Behind the scenes it uses `fs.symlinkSync()`.
*/
static createSymbolicLinkFolder(options: IFileSystemCreateLinkOptions): void;
/**
* An async version of {@link FileSystem.createSymbolicLinkFolder}.
*/
static createSymbolicLinkFolderAsync(options: IFileSystemCreateLinkOptions): Promise;
/**
* Creates a hard link.
* Behind the scenes it uses `fs.linkSync()`.
*/
static createHardLink(options: IFileSystemCreateLinkOptions): void;
/**
* An async version of {@link FileSystem.createHardLink}.
*/
static createHardLinkAsync(options: IFileSystemCreateLinkOptions): Promise;
/**
* Follows a link to its destination and returns the absolute path to the final target of the link.
* Behind the scenes it uses `fs.realpathSync()`.
* @param linkPath - The path to the link.
*/
static getRealPath(linkPath: string): string;
/**
* An async version of {@link FileSystem.getRealPath}.
*/
static getRealPathAsync(linkPath: string): Promise;
/**
* Returns true if the error provided indicates the file or folder does not exist.
*/
static isNotExistError(error: Error): boolean;
/**
* Returns true if the error provided indicates the file does not exist.
*/
static isFileDoesNotExistError(error: Error): boolean;
/**
* Returns true if the error provided indicates the folder does not exist.
*/
static isFolderDoesNotExistError(error: Error): boolean;
/**
* Detects if the provided error object is a `NodeJS.ErrnoException`
*/
static isErrnoException(error: Error): error is NodeJS.ErrnoException;
private static _wrapException;
private static _wrapExceptionAsync;
private static _updateErrorMessage;
}
/**
* Callback function type for {@link IFileSystemCopyFilesAsyncOptions.filter}
* @public
*/
export declare type FileSystemCopyFilesAsyncFilter = (sourcePath: string, destinationPath: string) => Promise;
/**
* Callback function type for {@link IFileSystemCopyFilesOptions.filter}
* @public
*/
export declare type FileSystemCopyFilesFilter = (sourcePath: string, destinationPath: string) => boolean;
/**
* An alias for the Node.js `fs.Stats` object.
*
* @remarks
* This avoids the need to import the `fs` package when using the {@link FileSystem} API.
* @public
*/
export declare type FileSystemStats = fs.Stats;
/**
* API for interacting with file handles.
* @public
*/
export declare class FileWriter {
/**
* The `filePath` that was passed to {@link FileWriter.open}.
*/
readonly filePath: string;
private _fileDescriptor;
private constructor();
/**
* Opens a new file handle to the file at the specified path and given mode.
* Behind the scenes it uses `fs.openSync()`.
* The behaviour of this function is platform specific.
* See: https://nodejs.org/docs/latest-v8.x/api/fs.html#fs_fs_open_path_flags_mode_callback
* @param filePath - The absolute or relative path to the file handle that should be opened.
* @param flags - The flags for opening the handle
*/
static open(filePath: string, flags?: IFileWriterFlags): FileWriter;
/**
* Helper function to convert the file writer array to a Node.js style string (e.g. "wx" or "a").
* @param flags - The flags that should be converted.
*/
private static _convertFlagsForNode;
/**
* Writes some text to the given file handle. Throws if the file handle has been closed.
* Behind the scenes it uses `fs.writeSync()`.
* @param text - The text to write to the file.
*/
write(text: string): void;
/**
* Closes the file handle permanently. No operations can be made on this file handle after calling this.
* Behind the scenes it uses `fs.closeSync()` and releases the file descriptor to be re-used.
*
* @remarks
* The `close()` method can be called more than once; additional calls are ignored.
*/
close(): void;
}
/**
* String constants for common folder names.
*
* @public
*/
export declare const enum FolderConstants {
/**
* ".git" - the data storage for a Git working folder
*/
Git = ".git",
/**
* "node_modules" - the folder where package managers install their files
*/
NodeModules = "node_modules"
}
/**
* Options for {@link AnsiEscape.formatForTests}.
* @public
*/
export declare interface IAnsiEscapeConvertForTestsOptions {
/**
* If true then `\n` will be replaced by `[n]`, and `\r` will be replaced by `[r]`.
*/
encodeNewlines?: boolean;
}
/**
* @beta
*/
export declare interface IColorableSequence {
text: string;
isEol?: boolean;
foregroundColor?: ColorValue;
backgroundColor?: ColorValue;
textAttributes?: TextAttribute[];
}
/**
* Options to be provided to a {@link ConsoleTerminalProvider}
*
* @beta
*/
export declare interface IConsoleTerminalProviderOptions {
/**
* If true, print verbose logging messages
*/
verboseEnabled: boolean;
}
/**
* Options for Executable.tryResolve().
* @public
*/
export declare interface IExecutableResolveOptions {
/**
* The current working directory. If omitted, process.cwd() will be used.
*/
currentWorkingDirectory?: string;
/**
* The environment variables for the child process. If omitted, process.env will be used.
*/
environment?: NodeJS.ProcessEnv;
}
/**
* Options for Executable.execute().
* @public
*/
export declare interface IExecutableSpawnSyncOptions extends IExecutableResolveOptions {
/**
* The content to be passed to the child process's stdin.
*
* NOTE: If specified, this content replaces any IExecutableSpawnSyncOptions.stdio[0]
* mapping for stdin.
*/
input?: string;
/**
* The stdio mappings for the child process.
*
* NOTE: If IExecutableSpawnSyncOptions.input is provided, it will take precedence
* over the stdin mapping (stdio[0]).
*/
stdio?: ExecutableStdioMapping;
/**
* The maximum time the process is allowed to run before it will be terminated.
*/
timeoutMs?: number;
/**
* The largest amount of bytes allowed on stdout or stderr for this synchonous operation.
* If exceeded, the child process will be terminated. The default is 200 * 1024.
*/
maxBuffer?: number;
}
/**
* @public
*/
export declare interface IFileSystemCopyFileBaseOptions {
/**
* The path of the existing object to be copied.
* The path may be absolute or relative.
*/
sourcePath: string;
/**
* Specifies what to do if the target object already exists.
* @defaultValue {@link AlreadyExistsBehavior.Overwrite}
*/
alreadyExistsBehavior?: AlreadyExistsBehavior;
}
/**
* The options for {@link FileSystem.copyFile}
* @public
*/
export declare interface IFileSystemCopyFileOptions extends IFileSystemCopyFileBaseOptions {
/**
* The path that the object will be copied to.
* The path may be absolute or relative.
*/
destinationPath: string;
}
/**
* The options for {@link FileSystem.copyFilesAsync}
* @public
*/
export declare interface IFileSystemCopyFilesAsyncOptions {
/**
* The starting path of the file or folder to be copied.
* The path may be absolute or relative.
*/
sourcePath: string;
/**
* The path that the files will be copied to.
* The path may be absolute or relative.
*/
destinationPath: string;
/**
* If true, then when copying symlinks, copy the target object instead of copying the link.
*/
dereferenceSymlinks?: boolean;
/**
* Specifies what to do if the target object already exists.
*/
alreadyExistsBehavior?: AlreadyExistsBehavior;
/**
* If true, then the target object will be assigned "last modification" and "last access" timestamps
* that are the same as the source. Otherwise, the OS default timestamps are assigned.
*/
preserveTimestamps?: boolean;
/**
* A callback that will be invoked for each path that is copied. The callback can return `false`
* to cause the object to be excluded from the operation.
*/
filter?: FileSystemCopyFilesAsyncFilter | FileSystemCopyFilesFilter;
}
/**
* The options for {@link FileSystem.copyFiles}
* @public
*/
export declare interface IFileSystemCopyFilesOptions extends IFileSystemCopyFilesAsyncOptions {
/** {@inheritdoc IFileSystemCopyFilesAsyncOptions.filter} */
filter?: FileSystemCopyFilesFilter;
}
/**
* The options for {@link FileSystem.copyFile}
* @public
*/
export declare interface IFileSystemCopyFileToManyOptions extends IFileSystemCopyFileBaseOptions {
/**
* The path that the object will be copied to.
* The path may be absolute or relative.
*/
destinationPaths: string[];
}
/**
* The options for {@link FileSystem.createSymbolicLinkJunction}, {@link FileSystem.createSymbolicLinkFile},
* {@link FileSystem.createSymbolicLinkFolder}, and {@link FileSystem.createHardLink}.
*
* @public
*/
export declare interface IFileSystemCreateLinkOptions {
/**
* The existing path that the symbolic link will point to.
*/
linkTargetPath: string;
/**
* The new path for the new symlink link to be created.
*/
newLinkPath: string;
/**
* Specifies what to do if the target object already exists. Defaults to `AlreadyExistsBehavior.Error`.
*/
alreadyExistsBehavior?: AlreadyExistsBehavior;
}
/**
* The options for {@link FileSystem.deleteFile}
* @public
*/
export declare interface IFileSystemDeleteFileOptions {
/**
* If true, will throw an exception if the file did not exist before `deleteFile()` was called.
* @defaultValue false
*/
throwIfNotExists?: boolean;
}
/**
* The options for {@link FileSystem.move}
* @public
*/
export declare interface IFileSystemMoveOptions {
/**
* The path of the existing object to be moved.
* The path may be absolute or relative.
*/
sourcePath: string;
/**
* The new path for the object.
* The path may be absolute or relative.
*/
destinationPath: string;
/**
* If true, will overwrite the file if it already exists.
* @defaultValue true
*/
overwrite?: boolean;
/**
* If true, will ensure the folder is created before writing the file.
* @defaultValue false
*/
ensureFolderExists?: boolean;
}
/**
* The options for {@link FileSystem.readFile}
* @public
*/
export declare interface IFileSystemReadFileOptions {
/**
* If specified, will change the encoding of the file that will be written.
* @defaultValue Encoding.Utf8
*/
encoding?: Encoding;
/**
* If specified, will normalize line endings to the specified style of newline.
* @defaultValue `undefined` which means no conversion will be performed
*/
convertLineEndings?: NewlineKind;
}
/**
* The options for {@link FileSystem.readFolder}
* @public
*/
export declare interface IFileSystemReadFolderOptions {
/**
* If true, returns the absolute paths of the files in the folder.
* @defaultValue false
*/
absolutePaths?: boolean;
}
/**
* The options for {@link FileSystem.updateTimes}
* Both times must be specified.
* @public
*/
export declare interface IFileSystemUpdateTimeParameters {
/**
* The POSIX epoch time or Date when this was last accessed.
*/
accessedTime: number | Date;
/**
* The POSIX epoch time or Date when this was last modified
*/
modifiedTime: number | Date;
}
/**
* The options for {@link FileSystem.writeFile}
* @public
*/
export declare interface IFileSystemWriteFileOptions {
/**
* If true, will ensure the folder is created before writing the file.
* @defaultValue false
*/
ensureFolderExists?: boolean;
/**
* If specified, will normalize line endings to the specified style of newline.
* @defaultValue `undefined` which means no conversion will be performed
*/
convertLineEndings?: NewlineKind;
/**
* If specified, will change the encoding of the file that will be written.
* @defaultValue "utf8"
*/
encoding?: Encoding;
}
/**
* Interface which represents the flags about which mode the file should be opened in.
* @public
*/
export declare interface IFileWriterFlags {
/**
* Open file for appending.
*/
append?: boolean;
/**
* Fails if path exists. The exclusive flag ensures that path is newly created.
*
* @remarks
* On POSIX-like operating systems, path is considered to exist even if it is a symlink to a
* non-existent file. The exclusive flag may or may not work with network file systems.
*
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*/
exclusive?: boolean;
}
/**
* Options for {@link Import.resolveModule}
* @public
*/
export declare interface IImportResolveModuleOptions extends IImportResolveOptions {
/**
* The module identifier to resolve. For example "\@rushstack/node-core-library" or
* "\@rushstack/node-core-library/lib/index.js"
*/
modulePath: string;
}
/**
* Common options shared by {@link IImportResolveModuleOptions} and {@link IImportResolvePackageOptions}
* @public
*/
export declare interface IImportResolveOptions {
/**
* The path from which {@link IImportResolveModuleOptions.modulePath} or
* {@link IImportResolvePackageOptions.packageName} should be resolved.
*/
baseFolderPath: string;
/**
* If true, if the package name matches a Node.js system module, then the return
* value will be the package name without any path.
*
* @remarks
* This will take precedence over an installed NPM package of the same name.
*
* Example:
* ```ts
* // Returns the string "fs" indicating the Node.js system module
* Import.resolveModulePath({
* resolvePath: "fs",
* basePath: process.cwd()
* })
* ```
*/
includeSystemModules?: boolean;
/**
* If true, then resolvePath is allowed to refer to the package.json of the active project.
*
* @remarks
* This will take precedence over any installed dependency with the same name.
* Note that this requires an additional PackageJsonLookup calculation.
*
* Example:
* ```ts
* // Returns an absolute path to the current package
* Import.resolveModulePath({
* resolvePath: "current-project",
* basePath: process.cwd(),
* allowSelfReference: true
* })
* ```
*/
allowSelfReference?: boolean;
}
/**
* Options for {@link Import.resolvePackage}
* @public
*/
export declare interface IImportResolvePackageOptions extends IImportResolveOptions {
/**
* The package name to resolve. For example "\@rushstack/node-core-library"
*/
packageName: string;
}
/**
* Options for JsonFile.saveJsonFile()
*
* @public
*/
export declare interface IJsonFileSaveOptions extends IJsonFileStringifyOptions {
/**
* If there is an existing file, and the contents have not changed, then
* don't write anything; this preserves the old timestamp.
*/
onlyIfChanged?: boolean;
/**
* Creates the folder recursively using FileSystem.ensureFolder()
* Defaults to false.
*/
ensureFolderExists?: boolean;
/**
* If true, use the "jju" library to preserve the existing JSON formatting: The file will be loaded
* from the target filename, the new content will be merged in (preserving whitespace and comments),
* and then the file will be overwritten with the merged contents. If the target file does not exist,
* then the file is saved normally.
*/
updateExistingFile?: boolean;
}
/**
* Options for JsonFile.stringify()
*
* @public
*/
export declare interface IJsonFileStringifyOptions {
/**
* If provided, the specified newline type will be used instead of the default `\r\n`.
*/
newlineConversion?: NewlineKind;
/**
* If true, then the "jju" library will be used to improve the text formatting.
* Note that this is slightly slower than the native JSON.stringify() implementation.
*/
prettyFormatting?: boolean;
/**
* If specified, this header will be prepended to the start of the file. The header must consist
* of lines prefixed by "//" characters.
* @remarks
* When used with {@link IJsonFileSaveOptions.updateExistingFile}
* or {@link JsonFile.updateString}, the header will ONLY be added for a newly created file.
*/
headerComment?: string;
}
/**
* Callback function arguments for JsonSchema.validateObjectWithCallback();
* @public
*/
export declare interface IJsonSchemaErrorInfo {
/**
* The z-schema error tree, formatted as an indented text string.
*/
details: string;
}
/**
* Options for JsonSchema.fromFile()
* @public
*/
export declare interface IJsonSchemaFromFileOptions {
/**
* Other schemas that this schema references, e.g. via the "$ref" directive.
* @remarks
* The tree of dependent schemas may reference the same schema more than once.
* However, if the same schema "id" is used by two different JsonSchema instances,
* an error will be reported. This means you cannot load the same filename twice
* and use them both together, and you cannot have diamond dependencies on different
* versions of the same schema. Although technically this would be possible to support,
* it normally indicates an error or design problem.
*
* JsonSchema also does not allow circular references between schema dependencies.
*/
dependentSchemas?: JsonSchema[];
}
/**
* Options for JsonSchema.validateObject()
* @public
*/
export declare interface IJsonSchemaValidateOptions {
/**
* A custom header that will be used to report schema errors.
* @remarks
* If omitted, the default header is "JSON validation failed:". The error message starts with
* the header, followed by the full input filename, followed by the z-schema error tree.
* If you wish to customize all aspects of the error message, use JsonFile.loadAndValidateWithCallback()
* or JsonSchema.validateObjectWithCallback().
*/
customErrorHeader?: string;
}
/**
* Helpers for resolving and importing Node.js modules.
* @public
*/
export declare class Import {
private static __builtInModules;
private static get _builtInModules();
/**
* Provides a way to improve process startup times by lazy-loading imported modules.
*
* @remarks
* This is a more structured wrapper for the {@link https://www.npmjs.com/package/import-lazy|import-lazy}
* package. It enables you to replace an import like this:
*
* ```ts
* import * as example from 'example'; // <-- 100ms load time
*
* if (condition) {
* example.doSomething();
* }
* ```
*
* ...with a pattern like this:
*
* ```ts
* const example: typeof import('example') = Import.lazy('example', require);
*
* if (condition) {
* example.doSomething(); // <-- 100ms load time occurs here, only if needed
* }
* ```
*
* The implementation relies on JavaScript's `Proxy` feature to intercept access to object members. Thus
* it will only work correctly with certain types of module exports. If a particular export isn't well behaved,
* you may need to find (or introduce) some other module in your dependency graph to apply the optimization to.
*
* Usage guidelines:
*
* - Always specify types using `typeof` as shown above.
*
* - Never apply lazy-loading in a way that would convert the module's type to `any`. Losing type safety
* seriously impacts the maintainability of the code base.
*
* - In cases where the non-runtime types are needed, import them separately using the `Types` suffix:
*
* ```ts
* const example: typeof import('example') = Import.lazy('example', require);
* import type * as exampleTypes from 'example';
* ```
*
* - If the imported module confusingly has the same name as its export, then use the Module suffix:
*
* ```ts
* const exampleModule: typeof import('../../logic/Example') = Import.lazy(
* '../../logic/Example', require);
* import type * as exampleTypes from '../../logic/Example';
* ```
*
* - If the exports cause a lot of awkwardness (e.g. too many expressions need to have `exampleModule.` inserted
* into them), or if some exports cannot be proxied (e.g. `Import.lazy('example', require)` returns a function
* signature), then do not lazy-load that module. Instead, apply lazy-loading to some other module which is
* better behaved.
*
* - It's recommended to sort imports in a standard ordering:
*
* ```ts
* // 1. external imports
* import * as path from 'path';
* import { Import, JsonFile, JsonObject } from '@rushstack/node-core-library';
*
* // 2. local imports
* import { LocalFile } from './path/LocalFile';
*
* // 3. lazy-imports (which are technically variables, not imports)
* const semver: typeof import('semver') = Import.lazy('semver', require);
* ```
*/
static lazy(moduleName: string, require: (id: string) => unknown): any;
/**
* This resolves a module path using similar logic as the Node.js `require.resolve()` API,
* but supporting extra features such as specifying the base folder.
*
* @remarks
* A module path is a text string that might appear in a statement such as
* `import { X } from "____";` or `const x = require("___");`. The implementation is based
* on the popular `resolve` NPM package.
*
* Suppose `example` is an NPM package whose entry point is `lib/index.js`:
* ```ts
* // Returns "/path/to/project/node_modules/example/lib/index.js"
* Import.resolveModule({ modulePath: 'example' });
*
* // Returns "/path/to/project/node_modules/example/lib/other.js"
* Import.resolveModule({ modulePath: 'example/lib/other' });
* ```
* If you need to determine the containing package folder
* (`/path/to/project/node_modules/example`), use {@link Import.resolvePackage} instead.
*
* @returns the absolute path of the resolved module.
* If {@link IImportResolveOptions.includeSystemModules} is specified
* and a system module is found, then its name is returned without any file path.
*/
static resolveModule(options: IImportResolveModuleOptions): string;
/**
* Performs module resolution to determine the folder where a package is installed.
*
* @remarks
* Suppose `example` is an NPM package whose entry point is `lib/index.js`:
* ```ts
* // Returns "/path/to/project/node_modules/example"
* Import.resolvePackage({ packageName: 'example' });
* ```
*
* If you need to resolve a module path, use {@link Import.resolveModule} instead:
* ```ts
* // Returns "/path/to/project/node_modules/example/lib/index.js"
* Import.resolveModule({ modulePath: 'example' });
* ```
*
* @returns the absolute path of the package folder.
* If {@link IImportResolveOptions.includeSystemModules} is specified
* and a system module is found, then its name is returned without any file path.
*/
static resolvePackage(options: IImportResolvePackageOptions): string;
private static _getPackageName;
}
/**
* An interface for accessing common fields from a package.json file whose version field may be missing.
*
* @remarks
* This interface is the same as {@link IPackageJson}, except that the `version` field is optional.
* According to the {@link https://docs.npmjs.com/files/package.json | NPM documentation}
* and {@link http://wiki.commonjs.org/wiki/Packages/1.0 | CommonJS Packages specification}, the `version` field
* is normally a required field for package.json files.
*
* However, NodeJS relaxes this requirement for its `require()` API. The
* {@link https://nodejs.org/dist/latest-v10.x/docs/api/modules.html#modules_folders_as_modules
* | "Folders as Modules" section} from the NodeJS documentation gives an example of a package.json file
* that has only the `name` and `main` fields. NodeJS does not consider the `version` field during resolution,
* so it can be omitted. Some libraries do this.
*
* Use the `INodePackageJson` interface when loading such files. Use `IPackageJson` for package.json files
* that are installed from an NPM registry, or are otherwise known to have a `version` field.
*
* @public
*/
export declare interface INodePackageJson {
/**
* The name of the package.
*/
name: string;
/**
* A version number conforming to the Semantic Versioning (SemVer) standard.
*/
version?: string;
/**
* Indicates whether this package is allowed to be published or not.
*/
private?: boolean;
/**
* A brief description of the package.
*/
description?: string;
/**
* The URL of the project's repository.
*/
repository?: string;
/**
* The URL to the project's web page.
*/
homepage?: string;
/**
* The name of the license.
*/
license?: string;
/**
* The path to the module file that will act as the main entry point.
*/
main?: string;
/**
* The path to the TypeScript *.d.ts file describing the module file
* that will act as the main entry point.
*/
types?: string;
/**
* Alias for `types`
*/
typings?: string;
/**
* The path to the TSDoc metadata file.
* This is still being standardized: https://github.com/microsoft/tsdoc/issues/7#issuecomment-442271815
* @beta
*/
tsdocMetadata?: string;
/**
* The main entry point for the package.
*/
bin?: string;
/**
* An array of dependencies that must always be installed for this package.
*/
dependencies?: IPackageJsonDependencyTable;
/**
* An array of optional dependencies that may be installed for this package.
*/
optionalDependencies?: IPackageJsonDependencyTable;
/**
* An array of dependencies that must only be installed for developers who will
* build this package.
*/
devDependencies?: IPackageJsonDependencyTable;
/**
* An array of dependencies that must be installed by a consumer of this package,
* but which will not be automatically installed by this package.
*/
peerDependencies?: IPackageJsonDependencyTable;
/**
* A table of script hooks that a package manager or build tool may invoke.
*/
scripts?: IPackageJsonScriptTable;
}
/**
* An `Error` subclass that should be thrown to report an unexpected state that may indicate a software defect.
* An application may handle this error by instructing the end user to report an issue to the application maintainers.
*
* @remarks
* Do not use this class unless you intend to solicit bug reports from end users.
*
* @public
*/
export declare class InternalError extends Error {
/**
* If true, a JavScript `debugger;` statement will be invoked whenever the `InternalError` constructor is called.
*
* @remarks
* Generally applications should not be catching and ignoring an `InternalError`. Instead, the error should
* be reported and typically the application will terminate. Thus, if `InternalError` is constructed, it's
* almost always something we want to examine in a debugger.
*/
static breakInDebugger: boolean;
/**
* The underlying error message, without the additional boilerplate for an `InternalError`.
*/
readonly unformattedMessage: string;
/**
* Constructs a new instance of the {@link InternalError} class.
*
* @param message - A message describing the error. This will be assigned to
* {@link InternalError.unformattedMessage}. The `Error.message` field will have additional boilerplate
* explaining that the user has encountered a software defect.
*/
constructor(message: string);
private static _formatMessage;
/** @override */
toString(): string;
}
/**
* An interface for accessing common fields from a package.json file.
*
* @remarks
* This interface describes a package.json file format whose `name` and `version` field are required.
* In some situations, the `version` field is optional; in that case, use the {@link INodePackageJson}
* interface instead.
*
* More fields may be added to this interface in the future. For documentation about the package.json file format,
* see the {@link http://wiki.commonjs.org/wiki/Packages/1.0 | CommonJS Packages specification}
* and the {@link https://docs.npmjs.com/files/package.json | NPM manual page}.
*
* @public
*/
export declare interface IPackageJson extends INodePackageJson {
/** {@inheritDoc INodePackageJson.version} */
version: string;
}
/**
* This interface is part of the IPackageJson file format. It is used for the
* "dependencies", "optionalDependencies", and "devDependencies" fields.
* @public
*/
export declare interface IPackageJsonDependencyTable {
/**
* The key is the name of a dependency. The value is a Semantic Versioning (SemVer)
* range specifier.
*/
[dependencyName: string]: string;
}
/**
* Constructor parameters for {@link PackageJsonLookup}
*
* @public
*/
export declare interface IPackageJsonLookupParameters {
/**
* Certain package.json fields such as "contributors" can be very large, and may
* significantly increase the memory footprint for the PackageJsonLookup cache.
* By default, PackageJsonLookup only loads a subset of standard commonly used
* fields names. Set loadExtraFields=true to always return all fields.
*/
loadExtraFields?: boolean;
}
/**
* This interface is part of the IPackageJson file format. It is used for the
* "scripts" field.
* @public
*/
export declare interface IPackageJsonScriptTable {
/**
* The key is the name of the script hook. The value is the script body which may
* be a file path or shell script command.
*/
[scriptName: string]: string;
}
/**
* Options that configure the validation rules used by a {@link PackageNameParser} instance.
*
* @remarks
* The default validation is based on the npmjs.com registry's policy for published packages, and includes these
* restrictions:
*
* - The package name cannot be longer than 214 characters.
*
* - The package name must not be empty.
*
* - Other than the `@` and `/` delimiters used for scopes, the only allowed characters
* are letters, numbers, `-`, `_`, and `.`.
*
* - The name must not start with a `.` or `_`.
*
* @public
*/
export declare interface IPackageNameParserOptions {
/**
* If true, allows upper-case letters in package names.
* This improves compatibility with some legacy private registries that still allow that.
*/
allowUpperCase?: boolean;
}
/**
* A package name that has been separated into its scope and unscoped name.
*
* @public
*/
export declare interface IParsedPackageName {
/**
* The parsed NPM scope, or an empty string if there was no scope. The scope value will
* always include the at-sign.
* @remarks
* For example, if the parsed input was "\@scope/example", then scope would be "\@scope".
*/
scope: string;
/**
* The parsed NPM package name without the scope.
* @remarks
* For example, if the parsed input was "\@scope/example", then the name would be "example".
*/
unscopedName: string;
}
/**
* Result object returned by {@link PackageName.tryParse}
*
* @public
*/
export declare interface IParsedPackageNameOrError extends IParsedPackageName {
/**
* If the input string could not be parsed, then this string will contain a nonempty
* error message. Otherwise it will be an empty string.
*/
error: string;
}
/**
* Options for {@link Path.formatConcisely}.
* @public
*/
export declare interface IPathFormatConciselyOptions {
/**
* The path to be converted.
*/
pathToConvert: string;
/**
* The base path to use when converting `pathToConvert` to a relative path.
*/
baseFolder: string;
}
/**
* Constructor parameters for {@link ProtectableMap}
*
* @public
*/
export declare interface IProtectableMapParameters {
/**
* An optional hook that will be invoked before Map.clear() is performed.
*/
onClear?: (source: ProtectableMap) => void;
/**
* An optional hook that will be invoked before Map.delete() is performed.
*/
onDelete?: (source: ProtectableMap, key: K) => void;
/**
* An optional hook that will be invoked before Map.set() is performed.
* @remarks
* If this hook is provided, the function MUST return the `value` parameter.
* This provides the opportunity to modify the value before it is added
* to the map.
*/
onSet?: (source: ProtectableMap, key: K, value: V) => V;
}
/**
* @beta
*/
export declare interface IStringBufferOutputOptions {
/**
* If set to true, special characters like \\n, \\r, and the \\u001b character
* in color control tokens will get normalized to [-n-], [-r-], and [-x-] respectively
*
* This option defaults to `true`
*/
normalizeSpecialCharacters: boolean;
}
/**
* An interface for a builder object that allows a large text string to be constructed incrementally by appending
* small chunks.
*
* @remarks
*
* {@link StringBuilder} is the default implementation of this contract.
*
* @public
*/
export declare interface IStringBuilder {
/**
* Append the specified text to the buffer.
*/
append(text: string): void;
/**
* Returns a single string containing all the text that was appended to the buffer so far.
*
* @remarks
*
* This is a potentially expensive operation.
*/
toString(): string;
}
/**
* Implement the interface to create a terminal provider. Terminal providers
* can be registered to a {@link Terminal} instance to receive messages.
*
* @beta
*/
export declare interface ITerminalProvider {
/**
* This property should return true only if the terminal provider supports
* rendering console colors.
*/
supportsColor: boolean;
/**
* This property should return the newline character the terminal provider
* expects.
*/
eolCharacter: string;
/**
* This function gets called on every terminal provider upon every
* message function call on the terminal instance.
*
* @param data - The terminal message.
* @param severity - The message severity. Terminal providers can
* route different kinds of messages to different streams and may choose
* to ignore verbose messages.
*/
write(data: string, severity: TerminalProviderSeverity): void;
}
/**
* Utilities for reading/writing JSON files.
* @public
*/
export declare class JsonFile {
/**
* @internal
*/
static _formatPathForError: (path: string) => string;
/**
* Loads a JSON file.
*/
static load(jsonFilename: string): JsonObject;
/**
* An async version of {@link JsonFile.load}.
*/
static loadAsync(jsonFilename: string): Promise;
/**
* Parses a JSON file's contents.
*/
static parseString(jsonContents: string): JsonObject;
/**
* Loads a JSON file and validate its schema.
*/
static loadAndValidate(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonSchemaValidateOptions): JsonObject;
/**
* An async version of {@link JsonFile.loadAndValidate}.
*/
static loadAndValidateAsync(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonSchemaValidateOptions): Promise;
/**
* Loads a JSON file and validate its schema, reporting errors using a callback
* @remarks
* See JsonSchema.validateObjectWithCallback() for more info.
*/
static loadAndValidateWithCallback(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void): JsonObject;
/**
* An async version of {@link JsonFile.loadAndValidateWithCallback}.
*/
static loadAndValidateWithCallbackAsync(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void): Promise;
/**
* Serializes the specified JSON object to a string buffer.
* @param jsonObject - the object to be serialized
* @param options - other settings that control serialization
* @returns a JSON string, with newlines, and indented with two spaces
*/
static stringify(jsonObject: JsonObject, options?: IJsonFileStringifyOptions): string;
/**
* Serializes the specified JSON object to a string buffer.
* @param jsonObject - the object to be serialized
* @param options - other settings that control serialization
* @returns a JSON string, with newlines, and indented with two spaces
*/
static updateString(previousJson: string, newJsonObject: JsonObject, options?: IJsonFileStringifyOptions): string;
/**
* Saves the file to disk. Returns false if nothing was written due to options.onlyIfChanged.
* @param jsonObject - the object to be saved
* @param jsonFilename - the file path to write
* @param options - other settings that control how the file is saved
* @returns false if ISaveJsonFileOptions.onlyIfChanged didn't save anything; true otherwise
*/
static save(jsonObject: JsonObject, jsonFilename: string, options?: IJsonFileSaveOptions): boolean;
/**
* An async version of {@link JsonFile.loadAndValidateWithCallback}.
*/
static saveAsync(jsonObject: JsonObject, jsonFilename: string, options?: IJsonFileSaveOptions): Promise;
/**
* Used to validate a data structure before writing. Reports an error if there
* are any undefined members.
*/
static validateNoUndefinedMembers(jsonObject: JsonObject): void;
private static _validateNoUndefinedMembers;
private static _formatKeyPath;
private static _formatJsonHeaderComment;
}
/**
* The Rush Stack lint rules discourage usage of `null`. However, JSON parsers always return JavaScript's
* `null` to keep the two syntaxes consistent. When creating interfaces that describe JSON structures,
* use `JsonNull` to avoid triggering the lint rule. Do not use `JsonNull` for any other purpose.
*
* @remarks
* If you are designing a new JSON file format, it's a good idea to avoid `null` entirely. In most cases
* there are better representations that convey more information about an item that is unknown, omitted, or disabled.
*
* To understand why `null` is deprecated, please see the `@rushstack/eslint-plugin` documentation here:
*
* {@link https://www.npmjs.com/package/@rushstack/eslint-plugin#rushstackno-null}
*
* @public
*/
export declare type JsonNull = null;
/**
* Represents a JSON-serializable object whose type has not been determined yet.
*
* @remarks
*
* This type is similar to `any`, except that it communicates that the object is serializable JSON.
*
* @public
*/
export declare type JsonObject = any;
/**
* Represents a JSON schema that can be used to validate JSON data files loaded by the JsonFile class.
* @remarks
* The schema itself is normally loaded and compiled later, only if it is actually required to validate
* an input. To avoid schema errors at runtime, it's recommended to create a unit test that calls
* JsonSchema.ensureCompiled() for each of your schema objects.
*
* @public
*/
export declare class JsonSchema {
private _dependentSchemas;
private _filename;
private _validator;
private _schemaObject;
private constructor();
/**
* Registers a JsonSchema that will be loaded from a file on disk.
* @remarks
* NOTE: An error occurs if the file does not exist; however, the file itself is not loaded or validated
* until it the schema is actually used.
*/
static fromFile(filename: string, options?: IJsonSchemaFromFileOptions): JsonSchema;
/**
* Registers a JsonSchema that will be loaded from a file on disk.
* @remarks
* NOTE: An error occurs if the file does not exist; however, the file itself is not loaded or validated
* until it the schema is actually used.
*/
static fromLoadedObject(schemaObject: JsonObject): JsonSchema;
private static _collectDependentSchemas;
/**
* Used to nicely format the ZSchema error tree.
*/
private static _formatErrorDetails;
/**
* Used by _formatErrorDetails.
*/
private static _formatErrorDetailsHelper;
/**
* Returns a short name for this schema, for use in error messages.
* @remarks
* If the schema was loaded from a file, then the base filename is used. Otherwise, the "id"
* field is used if available.
*/
get shortName(): string;
/**
* If not already done, this loads the schema from disk and compiles it.
* @remarks
* Any dependencies will be compiled as well.
*/
ensureCompiled(): void;
/**
* Validates the specified JSON object against this JSON schema. If the validation fails,
* an exception will be thrown.
* @param jsonObject - The JSON data to be validated
* @param filenameForErrors - The filename that the JSON data was available, or an empty string
* if not applicable
* @param options - Other options that control the validation
*/
validateObject(jsonObject: JsonObject, filenameForErrors: string, options?: IJsonSchemaValidateOptions): void;
/**
* Validates the specified JSON object against this JSON schema. If the validation fails,
* a callback is called for each validation error.
*/
validateObjectWithCallback(jsonObject: JsonObject, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void): void;
private _ensureLoaded;
}
/**
* Helper functions used when interacting with APIs that do not follow modern coding practices.
* @public
*/
export declare class LegacyAdapters {
private static _useTimsort;
/**
* This function wraps a function with a callback in a promise.
*/
static convertCallbackToPromise(fn: (cb: LegacyCallback) => void): Promise;
static convertCallbackToPromise(fn: (arg1: TArg1, cb: LegacyCallback) => void, arg1: TArg1): Promise;
static convertCallbackToPromise(fn: (arg1: TArg1, arg2: TArg2, cb: LegacyCallback) => void, arg1: TArg1, arg2: TArg2): Promise;
static convertCallbackToPromise(fn: (arg1: TArg1, arg2: TArg2, arg3: TArg3, cb: LegacyCallback) => void, arg1: TArg1, arg2: TArg2, arg3: TArg3): Promise;
static convertCallbackToPromise(fn: (arg1: TArg1, arg2: TArg2, arg3: TArg3, arg4: TArg4, cb: LegacyCallback) => void, arg1: TArg1, arg2: TArg2, arg3: TArg3, arg4: TArg4): Promise;
/**
* Normalizes an object into an `Error` object.
*/
static scrubError(error: Error | string | any): Error;
/**
* Prior to Node 11.x, the `Array.sort()` algorithm is not guaranteed to be stable.
* If you need a stable sort, you can use `sortStable()` as a workaround.
*
* @remarks
* On NodeJS 11.x and later, this method simply calls the native `Array.sort()`.
* For earlier versions, it uses an implementation of Timsort, which is the same algorithm used by modern NodeJS.
*/
static sortStable(array: T[], compare?: (a: T, b: T) => number): void;
}
/**
* Callback used by {@link LegacyAdapters}.
* @public
*/
export declare type LegacyCallback = (error: TError | null | undefined, result: TResult) => void;
/**
* The `LockFile` implements a file-based mutex for synchronizing access to a shared resource
* between multiple Node.js processes. It is not recommended for synchronization solely within
* a single Node.js process.
* @remarks
* The implementation works on Windows, Mac, and Linux without requiring any native helpers.
* On non-Windows systems, the algorithm requires access to the `ps` shell command. On Linux,
* it requires access the `/proc/${pidString}/stat` filesystem.
* @public
*/
export declare class LockFile {
private static _getStartTime;
private _fileWriter;
private _filePath;
private _dirtyWhenAcquired;
private constructor();
/**
* Returns the path of the lockfile that will be created when a lock is successfully acquired.
* @param resourceFolder - The folder where the lock file will be created
* @param resourceName - An alphanumeric name that describes the resource being locked. This will become
* the filename of the temporary file created to manage the lock.
* @param pid - The PID for the current Node.js process (`process.pid`), which is used by the locking algorithm.
*/
static getLockFilePath(resourceFolder: string, resourceName: string, pid?: number): string;
/**
* Attempts to create a lockfile with the given filePath.
* @param resourceFolder - The folder where the lock file will be created
* @param resourceName - An alphanumeric name that describes the resource being locked. This will become
* the filename of the temporary file created to manage the lock.
* @returns If successful, returns a `LockFile` instance. If unable to get a lock, returns `undefined`.
*/
static tryAcquire(resourceFolder: string, resourceName: string): LockFile | undefined;
/**
* Attempts to create the lockfile. Will continue to loop at every 100ms until the lock becomes available
* or the maxWaitMs is surpassed.
*
* @remarks
* This function is subject to starvation, whereby it does not ensure that the process that has been
* waiting the longest to acquire the lock will get it first. This means that a process could theoretically
* wait for the lock forever, while other processes skipped it in line and acquired the lock first.
*
* @param resourceFolder - The folder where the lock file will be created
* @param resourceName - An alphanumeric name that describes the resource being locked. This will become
* the filename of the temporary file created to manage the lock.
* @param maxWaitMs - The maximum number of milliseconds to wait for the lock before reporting an error
*/
static acquire(resourceFolder: string, resourceName: string, maxWaitMs?: number): Promise;
private static _sleepForMs;
/**
* Attempts to acquire the lock on a Linux or OSX machine
*/
private static _tryAcquireMacOrLinux;
/**
* Attempts to acquire the lock using Windows
* This algorithm is much simpler since we can rely on the operating system
*/
private static _tryAcquireWindows;
/**
* Unlocks a file and removes it from disk.
* This can only be called once.
*/
release(): void;
/**
* Returns the initial state of the lock.
* This can be used to detect if the previous process was terminated before releasing the resource.
*/
get dirtyWhenAcquired(): boolean;
/**
* Returns the absolute path to the lockfile
*/
get filePath(): string;
/**
* Returns true if this lock is currently being held.
*/
get isReleased(): boolean;
}
/**
* Helper functions for working with the `Map` data type.
*
* @public
*/
export declare class MapExtensions {
/**
* Adds all the (key, value) pairs from the source map into the target map.
* @remarks
* This function modifies targetMap. Any existing keys will be overwritten.
* @param targetMap - The map that entries will be added to
* @param sourceMap - The map containing the entries to be added
*/
static mergeFromMap(targetMap: Map, sourceMap: ReadonlyMap): void;
/**
* Converts a string-keyed map to an object.
* @remarks
* This function has the same effect as Object.fromEntries(map.entries())
* in supported versions of Node (\>= 12.0.0).
* @param map - The map that the object properties will be sourced from
*/
static toObject(map: Map): {
[key: string]: TValue;
};
}
/**
* Enumeration controlling conversion of newline characters.
* @public
*/
export declare const enum NewlineKind {
/**
* Windows-style newlines
*/
CrLf = "\r\n",
/**
* POSIX-style newlines
*
* @remarks
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*/
Lf = "\n",
/**
* Default newline type for this operating system (`os.EOL`).
*/
OsDefault = "os"
}
/**
* This class provides methods for finding the nearest "package.json" for a folder
* and retrieving the name of the package. The results are cached.
*
* @public
*/
export declare class PackageJsonLookup {
private static _instance;
/**
* A singleton instance of `PackageJsonLookup`, which is useful for short-lived processes
* that can reasonably assume that the file system will not be modified after the cache
* is populated.
*
* @remarks
* For long-running processes that need to clear the cache at appropriate times,
* it is recommended to create your own instance of `PackageJsonLookup` instead
* of relying on this instance.
*/
static get instance(): PackageJsonLookup;
private _loadExtraFields;
private _packageFolderCache;
private _packageJsonCache;
constructor(parameters?: IPackageJsonLookupParameters);
/**
* A helper for loading the caller's own package.json file.
*
* @remarks
*
* This function provides a concise and efficient way for an NPM package to report metadata about itself.
* For example, a tool might want to report its version.
*
* The `loadOwnPackageJson()` probes upwards from the caller's folder, expecting to find a package.json file,
* which is assumed to be the caller's package. The result is cached, under the assumption that a tool's
* own package.json (and intermediary folders) will never change during the lifetime of the process.
*
* @example
* ```ts
* // Report the version of our NPM package
* const myPackageVersion: string = PackageJsonLookup.loadOwnPackageJson(__dirname).version;
* console.log(`Cool Tool - Version ${myPackageVersion}`);
* ```
*
* @param dirnameOfCaller - The NodeJS `__dirname` macro for the caller.
* @returns This function always returns a valid `IPackageJson` object. If any problems are encountered during
* loading, an exception will be thrown instead.
*/
static loadOwnPackageJson(dirnameOfCaller: string): IPackageJson;
/**
* Clears the internal file cache.
* @remarks
* Call this method if changes have been made to the package.json files on disk.
*/
clearCache(): void;
/**
* Returns the absolute path of a folder containing a package.json file, by looking
* upwards from the specified fileOrFolderPath. If no package.json can be found,
* undefined is returned.
*
* @remarks
* The fileOrFolderPath is not required to actually exist on disk.
* The fileOrFolderPath itself can be the return value, if it is a folder containing
* a package.json file.
* Both positive and negative lookup results are cached.
*
* @param fileOrFolderPath - a relative or absolute path to a source file or folder
* that may be part of a package
* @returns an absolute path to a folder containing a package.json file
*/
tryGetPackageFolderFor(fileOrFolderPath: string): string | undefined;
/**
* If the specified file or folder is part of a package, this returns the absolute path
* to the associated package.json file.
*
* @remarks
* The package folder is determined using the same algorithm
* as {@link PackageJsonLookup.tryGetPackageFolderFor}.
*
* @param fileOrFolderPath - a relative or absolute path to a source file or folder
* that may be part of a package
* @returns an absolute path to * package.json file
*/
tryGetPackageJsonFilePathFor(fileOrFolderPath: string): string | undefined;
/**
* If the specified file or folder is part of a package, this loads and returns the
* associated package.json file.
*
* @remarks
* The package folder is determined using the same algorithm
* as {@link PackageJsonLookup.tryGetPackageFolderFor}.
*
* @param fileOrFolderPath - a relative or absolute path to a source file or folder
* that may be part of a package
* @returns an IPackageJson object, or undefined if the fileOrFolderPath does not
* belong to a package
*/
tryLoadPackageJsonFor(fileOrFolderPath: string): IPackageJson | undefined;
/**
* This function is similar to {@link PackageJsonLookup.tryLoadPackageJsonFor}, except that it does not report
* an error if the `version` field is missing from the package.json file.
*/
tryLoadNodePackageJsonFor(fileOrFolderPath: string): INodePackageJson | undefined;
/**
* Loads the specified package.json file, if it is not already present in the cache.
*
* @remarks
* Unless {@link IPackageJsonLookupParameters.loadExtraFields} was specified,
* the returned IPackageJson object will contain a subset of essential fields.
* The returned object should be considered to be immutable; the caller must never
* modify it.
*
* @param jsonFilename - a relative or absolute path to a package.json file
*/
loadPackageJson(jsonFilename: string): IPackageJson;
/**
* This function is similar to {@link PackageJsonLookup.loadPackageJson}, except that it does not report an error
* if the `version` field is missing from the package.json file.
*/
loadNodePackageJson(jsonFilename: string): INodePackageJson;
private _tryGetPackageFolderFor;
}
/**
* Provides basic operations for validating and manipulating NPM package names such as `my-package`
* or `@scope/my-package`.
*
* @remarks
* This is the default implementation of {@link PackageNameParser}, exposed as a convenient static class.
* If you need to configure the parsing rules, use `PackageNameParser` instead.
*
* @public
*/
export declare class PackageName {
private static readonly _parser;
/** {@inheritDoc PackageNameParser.tryParse} */
static tryParse(packageName: string): IParsedPackageNameOrError;
/** {@inheritDoc PackageNameParser.parse} */
static parse(packageName: string): IParsedPackageName;
/** {@inheritDoc PackageNameParser.getScope} */
static getScope(packageName: string): string;
/** {@inheritDoc PackageNameParser.getUnscopedName} */
static getUnscopedName(packageName: string): string;
/** {@inheritDoc PackageNameParser.isValidName} */
static isValidName(packageName: string): boolean;
/** {@inheritDoc PackageNameParser.validate} */
static validate(packageName: string): void;
/** {@inheritDoc PackageNameParser.combineParts} */
static combineParts(scope: string, unscopedName: string): string;
}
/**
* A configurable parser for validating and manipulating NPM package names such as `my-package` or `@scope/my-package`.
*
* @remarks
* If you do not need to customize the parser configuration, it is recommended to use {@link PackageName}
* which exposes these operations as a simple static class.
*
* @public
*/
export declare class PackageNameParser {
private static readonly _invalidNameCharactersRegExp;
private readonly _options;
constructor(options?: IPackageNameParserOptions);
/**
* This attempts to parse a package name that may include a scope component.
* The packageName must not be an empty string.
* @remarks
* This function will not throw an exception.
*
* @returns an {@link IParsedPackageNameOrError} structure whose `error` property will be
* nonempty if the string could not be parsed.
*/
tryParse(packageName: string): IParsedPackageNameOrError;
/**
* Same as {@link PackageName.tryParse}, except this throws an exception if the input
* cannot be parsed.
* @remarks
* The packageName must not be an empty string.
*/
parse(packageName: string): IParsedPackageName;
/**
* {@inheritDoc IParsedPackageName.scope}
*/
getScope(packageName: string): string;
/**
* {@inheritDoc IParsedPackageName.unscopedName}
*/
getUnscopedName(packageName: string): string;
/**
* Returns true if the specified package name is valid, or false otherwise.
* @remarks
* This function will not throw an exception.
*/
isValidName(packageName: string): boolean;
/**
* Throws an exception if the specified name is not a valid package name.
* The packageName must not be an empty string.
*/
validate(packageName: string): void;
/**
* Combines an optional package scope with an unscoped root name.
* @param scope - Must be either an empty string, or a scope name such as "\@example"
* @param unscopedName - Must be a nonempty package name that does not contain a scope
* @returns A full package name such as "\@example/some-library".
*/
combineParts(scope: string, unscopedName: string): string;
}
/**
* Common operations for manipulating file and directory paths.
* @remarks
* This API is intended to eventually be a complete replacement for the NodeJS "path" API.
* @public
*/
export declare class Path {
private static _relativePathRegex;
private static _upwardPathSegmentRegex;
/**
* Returns true if "childPath" is located inside the "parentFolderPath" folder
* or one of its child folders. Note that "parentFolderPath" is not considered to be
* under itself. The "childPath" can refer to any type of file system object.
*
* @remarks
* The indicated file/folder objects are not required to actually exist on disk.
* For example, "parentFolderPath" is interpreted as a folder name even if it refers to a file.
* If the paths are relative, they will first be resolved using path.resolve().
*/
static isUnder(childPath: string, parentFolderPath: string): boolean;
/**
* Returns true if "childPath" is equal to "parentFolderPath", or if it is inside that folder
* or one of its children. The "childPath" can refer to any type of file system object.
*
* @remarks
* The indicated file/folder objects are not required to actually exist on disk.
* For example, "parentFolderPath" is interpreted as a folder name even if it refers to a file.
* If the paths are relative, they will first be resolved using path.resolve().
*/
static isUnderOrEqual(childPath: string, parentFolderPath: string): boolean;
/**
* Returns true if `path1` and `path2` refer to the same underlying path.
*
* @remarks
*
* The comparison is performed using `path.relative()`.
*/
static isEqual(path1: string, path2: string): boolean;
/**
* Formats a path to look nice for reporting purposes.
* @remarks
* If `pathToConvert` is under the `baseFolder`, then it will be converted to a relative with the `./` prefix.
* Otherwise, it will be converted to an absolute path.
*
* Backslashes will be converted to slashes, unless the path starts with an OS-specific string like `C:\`.
*/
static formatConcisely(options: IPathFormatConciselyOptions): string;
/**
* Replaces Windows-style backslashes with POSIX-style slashes.
*
* @remarks
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*/
static convertToSlashes(inputPath: string): string;
/**
* Replaces POSIX-style slashes with Windows-style backslashes
*
* @remarks
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*/
static convertToBackslashes(inputPath: string): string;
/**
* Returns true if the specified path is a relative path and does not use `..` to walk upwards.
*
* @example
* ```ts
* // These evaluate to true
* isDownwardRelative('folder');
* isDownwardRelative('file');
* isDownwardRelative('folder/');
* isDownwardRelative('./folder/');
* isDownwardRelative('./folder/file');
*
* // These evaluate to false
* isDownwardRelative('../folder');
* isDownwardRelative('folder/../file');
* isDownwardRelative('/folder/file');
* ```
*/
static isDownwardRelative(inputPath: string): boolean;
}
/**
* An integer value used to specify file permissions for POSIX-like operating systems.
*
* @remarks
*
* This bitfield corresponds to the "mode_t" structure described in this document:
* http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html
*
* It is used with NodeJS APIs such as fs.Stat.mode and fs.chmodSync(). These values
* represent a set of permissions and can be combined using bitwise arithmetic.
*
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*
* @public
*/
export declare const enum PosixModeBits {
/**
* Indicates that the item's owner can read the item.
*/
UserRead = 256,
/**
* Indicates that the item's owner can modify the item.
*/
UserWrite = 128,
/**
* Indicates that the item's owner can execute the item (if it is a file)
* or search the item (if it is a directory).
*/
UserExecute = 64,
/**
* Indicates that users belonging to the item's group can read the item.
*/
GroupRead = 32,
/**
* Indicates that users belonging to the item's group can modify the item.
*/
GroupWrite = 16,
/**
* Indicates that users belonging to the item's group can execute the item (if it is a file)
* or search the item (if it is a directory).
*/
GroupExecute = 8,
/**
* Indicates that other users (besides the item's owner user or group) can read the item.
*/
OthersRead = 4,
/**
* Indicates that other users (besides the item's owner user or group) can modify the item.
*/
OthersWrite = 2,
/**
* Indicates that other users (besides the item's owner user or group) can execute the item (if it is a file)
* or search the item (if it is a directory).
*/
OthersExecute = 1,
/**
* A zero value where no permissions bits are set.
*/
None = 0,
/**
* An alias combining OthersRead, GroupRead, and UserRead permission bits.
*/
AllRead = 292,
/**
* An alias combining OthersWrite, GroupWrite, and UserWrite permission bits.
*/
AllWrite = 146,
/**
* An alias combining OthersExecute, GroupExecute, and UserExecute permission bits.
*/
AllExecute = 73
}
/**
* The ProtectableMap provides an easy way for an API to expose a `Map` property
* while intercepting and validating any write operations that are performed by
* consumers of the API.
*
* @remarks
* The ProtectableMap itself is intended to be a private object that only its owner
* can access directly. Any operations performed directly on the ProtectableMap will
* bypass the hooks and any validation they perform. The public property that is exposed
* to API consumers should return {@link ProtectableMap.protectedView} instead.
*
* For example, suppose you want to share your `Map` data structure,
* but you want to enforce that the key must always be an upper case string:
* You could use the onSet() hook to validate the keys and throw an exception
* if the key is not uppercase.
*
* @public
*/
export declare class ProtectableMap {
private readonly _protectedView;
constructor(parameters: IProtectableMapParameters);
/**
* The owner of the protectable map should return this object via its public API.
*/
get protectedView(): Map;
/**
* Removes all entries from the map.
* This operation does NOT invoke the ProtectableMap onClear() hook.
*/
clear(): void;
/**
* Removes the specified key from the map.
* This operation does NOT invoke the ProtectableMap onDelete() hook.
*/
delete(key: K): boolean;
/**
* Sets a value for the specified key.
* This operation does NOT invoke the ProtectableMap onSet() hook.
*/
set(key: K, value: V): this;
/**
* Performs an operation for each (key, value) entries in the map.
*/
forEach(callbackfn: (value: V, key: K, map: Map) => void, thisArg?: any): void;
/**
* Retrieves the value for the specified key.
* @returns undefined if the value is undefined OR if the key is missing;
* otherwise returns the value associated with the key.
*/
get(key: K): V | undefined;
/**
* Returns true if the specified key belongs to the map.
*/
has(key: K): boolean;
/**
* Returns the number of (key, value) entries in the map.
*/
get size(): number;
}
/**
* Operations for sorting collections.
*
* @remarks
* NOTE: Prior to Node 11.x, the `Array.sort()` algorithm is not guaranteed to be stable. For maximum
* compatibility, consider using {@link LegacyAdapters.sortStable} instead of `Array.sort()`.
*
* @public
*/
export declare class Sort {
/**
* Compares `x` and `y` using the JavaScript `>` and `<` operators. This function is suitable for usage as
* the callback for `array.sort()`.
*
* @remarks
*
* The JavaScript ordering is generalized so that `undefined` \< `null` \< all other values.
*
* @returns -1 if `x` is smaller than `y`, 1 if `x` is greater than `y`, or 0 if the values are equal.
*
* @example
*
* ```ts
* let array: number[] = [3, 6, 2];
* array.sort(Sort.compareByValue); // [2, 3, 6]
* ```
*/
static compareByValue(x: any, y: any): number;
/**
* Sorts the array according to a key which is obtained from the array elements.
* The result is guaranteed to be a stable sort.
*
* @example
*
* ```ts
* let array: string[] = [ 'aaa', 'bb', 'c' ];
* Sort.sortBy(array, x => x.length); // [ 'c', 'bb', 'aaa' ]
* ```
*/
static sortBy(array: T[], keySelector: (element: T) => any, comparer?: (x: any, y: any) => number): void;
/**
* Returns true if the array is already sorted.
*/
static isSorted(array: T[], comparer?: (x: any, y: any) => number): boolean;
/**
* Returns true if the array is already sorted by the specified key.
*
* @example
*
* ```ts
* let array: string[] = [ 'a', 'bb', 'ccc' ];
* Sort.isSortedBy(array, x => x.length); // true
* ```
*/
static isSortedBy(array: T[], keySelector: (element: T) => any, comparer?: (x: any, y: any) => number): boolean;
/**
* Sorts the entries in a Map object according to the map keys.
* The result is guaranteed to be a stable sort.
*
* @example
*
* ```ts
* let map: Map = new Map();
* map.set('zebra', 1);
* map.set('goose', 2);
* map.set('aardvark', 3);
* Sort.sortMapKeys(map);
* console.log(JSON.stringify(Array.from(map.keys()))); // ["aardvark","goose","zebra"]
* ```
*/
static sortMapKeys(map: Map, keyComparer?: (x: K, y: K) => number): void;
/**
* Sorts the entries in a Set object according to the specified keys.
* The result is guaranteed to be a stable sort.
*
* @example
*
* ```ts
* let set: Set = new Set();
* set.add('aaa');
* set.add('bb');
* set.add('c');
* Sort.sortSetBy(set, x => x.length);
* console.log(Array.from(set)); // ['c', 'bb', 'aaa']
* ```
*/
static sortSetBy(set: Set, keySelector: (element: T) => any, keyComparer?: (x: T, y: T) => number): void;
/**
* Sorts the entries in a Set object. The result is guaranteed to be a stable sort.
*
* @example
*
* ```ts
* let set: Set = new Set();
* set.add('zebra');
* set.add('goose');
* set.add('aardvark');
* Sort.sortSet(set);
* console.log(Array.from(set)); // ['aardvark', 'goose', 'zebra']
* ```
*/
static sortSet(set: Set, comparer?: (x: T, y: T) => number): void;
}
/**
* Terminal provider that stores written data in buffers separated by severity.
* This terminal provider is designed to be used when code that prints to a terminal
* is being unit tested.
*
* @beta
*/
export declare class StringBufferTerminalProvider implements ITerminalProvider {
private _standardBuffer;
private _verboseBuffer;
private _warningBuffer;
private _errorBuffer;
private _supportsColor;
constructor(supportsColor?: boolean);
/**
* {@inheritDoc ITerminalProvider.write}
*/
write(data: string, severity: TerminalProviderSeverity): void;
/**
* {@inheritDoc ITerminalProvider.eolCharacter}
*/
get eolCharacter(): string;
/**
* {@inheritDoc ITerminalProvider.supportsColor}
*/
get supportsColor(): boolean;
/**
* Get everything that has been written at log-level severity.
*/
getOutput(options?: IStringBufferOutputOptions): string;
/**
* Get everything that has been written at verbose-level severity.
*/
getVerbose(options?: IStringBufferOutputOptions): string;
/**
* Get everything that has been written at error-level severity.
*/
getErrorOutput(options?: IStringBufferOutputOptions): string;
/**
* Get everything that has been written at warning-level severity.
*/
getWarningOutput(options?: IStringBufferOutputOptions): string;
private _normalizeOutput;
}
/**
* This class allows a large text string to be constructed incrementally by appending small chunks. The final
* string can be obtained by calling StringBuilder.toString().
*
* @remarks
* A naive approach might use the `+=` operator to append strings: This would have the downside of copying
* the entire string each time a chunk is appended, resulting in `O(n^2)` bytes of memory being allocated
* (and later freed by the garbage collector), and many of the allocations could be very large objects.
* StringBuilder avoids this overhead by accumulating the chunks in an array, and efficiently joining them
* when `getText()` is finally called.
*
* @public
*/
export declare class StringBuilder implements IStringBuilder {
private _chunks;
constructor();
/** {@inheritDoc IStringBuilder.append} */
append(text: string): void;
/** {@inheritDoc IStringBuilder.toString} */
toString(): string;
}
/**
* This class facilitates writing to a console.
*
* @beta
*/
export declare class Terminal {
private _providers;
constructor(provider: ITerminalProvider);
/**
* Subscribe a new terminal provider.
*/
registerProvider(provider: ITerminalProvider): void;
/**
* Unsubscribe a terminal provider. If the provider isn't subscribed, this function does nothing.
*/
unregisterProvider(provider: ITerminalProvider): void;
/**
* Write a generic message to the terminal
*/
write(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write a generic message to the terminal, followed by a newline
*/
writeLine(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write a warning message to the console with yellow text.
*
* @remarks
* The yellow color takes precedence over any other foreground colors set.
*/
writeWarning(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write a warning message to the console with yellow text, followed by a newline.
*
* @remarks
* The yellow color takes precedence over any other foreground colors set.
*/
writeWarningLine(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write an error message to the console with red text.
*
* @remarks
* The red color takes precedence over any other foreground colors set.
*/
writeError(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write an error message to the console with red text, followed by a newline.
*
* @remarks
* The red color takes precedence over any other foreground colors set.
*/
writeErrorLine(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write a verbose-level message.
*/
writeVerbose(...messageParts: (string | IColorableSequence)[]): void;
/**
* Write a verbose-level message followed by a newline.
*/
writeVerboseLine(...messageParts: (string | IColorableSequence)[]): void;
private _writeSegmentsToProviders;
private _serializeFormattableTextSegments;
}
/**
* @beta
*/
export declare enum TerminalProviderSeverity {
log = 0,
warning = 1,
error = 2,
verbose = 3
}
/**
* Operations for working with strings that contain text.
*
* @remarks
* The utilities provided by this class are intended to be simple, small, and very
* broadly applicable.
*
* @public
*/
export declare class Text {
private static readonly _newLineRegEx;
private static readonly _newLineAtEndRegEx;
/**
* Returns the same thing as targetString.replace(searchValue, replaceValue), except that
* all matches are replaced, rather than just the first match.
* @param input - The string to be modified
* @param searchValue - The value to search for
* @param replaceValue - The replacement text
*/
static replaceAll(input: string, searchValue: string, replaceValue: string): string;
/**
* Converts all newlines in the provided string to use Windows-style CRLF end of line characters.
*/
static convertToCrLf(input: string): string;
/**
* Converts all newlines in the provided string to use POSIX-style LF end of line characters.
*
* POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
*/
static convertToLf(input: string): string;
/**
* Converts all newlines in the provided string to use the specified newline type.
*/
static convertTo(input: string, newlineKind: NewlineKind): string;
/**
* Returns the newline character sequence for the specified `NewlineKind`.
*/
static getNewline(newlineKind: NewlineKind): string;
/**
* Append characters to the end of a string to ensure the result has a minimum length.
* @remarks
* If the string length already exceeds the minimum length, then the string is unchanged.
* The string is not truncated.
*/
static padEnd(s: string, minimumLength: number, paddingCharacter?: string): string;
/**
* Append characters to the start of a string to ensure the result has a minimum length.
* @remarks
* If the string length already exceeds the minimum length, then the string is unchanged.
* The string is not truncated.
*/
static padStart(s: string, minimumLength: number, paddingCharacter?: string): string;
/**
* If the string is longer than maximumLength characters, truncate it to that length
* using "..." to indicate the truncation.
*
* @remarks
* For example truncateWithEllipsis('1234578', 5) would produce '12...'.
*/
static truncateWithEllipsis(s: string, maximumLength: number): string;
/**
* Returns the input string with a trailing `\n` character appended, if not already present.
*/
static ensureTrailingNewline(s: string, newlineKind?: NewlineKind): string;
}
/**
* Text styles used with {@link IColorableSequence}.
* @beta
*/
export declare enum TextAttribute {
Bold = 0,
Dim = 1,
Underline = 2,
Blink = 3,
InvertColor = 4,
Hidden = 5
}
/**
* Provides a version-independent implementation of the JavaScript `instanceof` operator.
*
* @remarks
* The JavaScript `instanceof` operator normally only identifies objects from a particular library instance.
* For example, suppose the NPM package `example-lib` has two published versions 1.2.0 and 1.3.0, and
* it exports a class called `A`. Suppose some code consumes version `1.3.0` of the library, but it receives
* an object that was constructed using version `1.2.0`. In this situation `a instanceof A` will return `false`,
* even though `a` is an instance of `A`. The reason is that there are two prototypes for `A`; one for each
* version.
*
* The `TypeUuid` facility provides a way to make `a instanceof A` return true for both prototypes of `A`,
* by instead using a universally unique identifier (UUID) to detect object instances.
*
* You can use `Symbol.hasInstance` to enable the system `instanceof` operator to recognize type UUID equivalence:
* ```ts
* const uuidWidget: string = '9c340ef0-d29f-4e2e-a09f-42bacc59024b';
* class Widget {
* public static [Symbol.hasInstance](instance: object): boolean {
* return TypeUuid.isInstanceOf(instance, uuidWidget);
* }
* }
* ```
* // Example usage:
* ```ts
* import { Widget as Widget1 } from 'v1-of-library';
* import { Widget as Widget2 } from 'v2-of-library';
* const widget = new Widget2();
* console.log(widget instanceof Widget1); // prints true
* ```
*
* @public
*/
export declare class TypeUuid {
private static _uuidRegExp;
/**
* Registers a JavaScript class as having a type identified by the specified UUID.
* @privateRemarks
* We cannot use a construct signature for `targetClass` because it may be an abstract class.
*/
static registerClass(targetClass: any, typeUuid: string): void;
/**
* Returns true if the `targetObject` is an instance of a JavaScript class that was previously
* registered using the specified `typeUuid`. Base classes are also considered.
*/
static isInstanceOf(targetObject: unknown, typeUuid: string): boolean;
}
export { }