@salesforce/core
Version:
Core libraries to interact with SFDX projects, orgs, and APIs.
202 lines (201 loc) • 7.88 kB
TypeScript
import { Stats as fsStats } from 'node:fs';
import { Logger } from '../logger/logger';
import { BaseConfigStore } from './configStore';
import { ConfigContents } from './configStackTypes';
/**
* Represents a json config file used to manage settings and state. Global config
* files are stored in the home directory hidden state folder (.sfdx) and local config
* files are stored in the project path, either in the hidden state folder or wherever
* specified.
*
* ```
* class MyConfig extends ConfigFile {
* public static getFileName(): string {
* return 'myConfigFilename.json';
* }
* }
* const myConfig = await MyConfig.create({
* isGlobal: true
* });
* myConfig.set('mykey', 'myvalue');
* await myConfig.write();
* ```
*/
export declare class ConfigFile<T extends ConfigFile.Options = ConfigFile.Options, P extends ConfigContents = ConfigContents> extends BaseConfigStore<T, P> {
protected hasRead: boolean;
protected logger: Logger;
private path;
/**
* Create an instance of a config file without reading the file. Call `read` or `readSync`
* after creating the ConfigFile OR instantiate with {@link ConfigFile.create} instead.
*
* @param options The options for the class instance
* @ignore
*/
constructor(options?: T);
/**
* Returns the config's filename.
*/
static getFileName(): string;
/**
* Returns the default options for the config file.
*
* @param isGlobal If the file should be stored globally or locally.
* @param filename The name of the config file.
*/
static getDefaultOptions(isGlobal?: boolean, filename?: string): ConfigFile.Options;
/**
* Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
*
* @param isGlobal True if the config should be global. False for local.
*/
static resolveRootFolder(isGlobal: boolean): Promise<string>;
/**
* Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
*
* @param isGlobal True if the config should be global. False for local.
*/
static resolveRootFolderSync(isGlobal: boolean): string;
/**
* Determines if the config file is read/write accessible. Returns `true` if the user has capabilities specified
* by perm.
*
* @param {number} perm The permission.
*
* **See** {@link https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback}
*/
access(perm?: number): Promise<boolean>;
/**
* Determines if the config file is read/write accessible. Returns `true` if the user has capabilities specified
* by perm.
*
* @param {number} perm The permission.
*
* **See** {@link https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback}
*/
accessSync(perm?: number): boolean;
/**
* Read the config file and set the config contents. Returns the config contents of the config file. As an
* optimization, files are only read once per process and updated in memory and via `write()`. To force
* a read from the filesystem pass `force=true`.
* **Throws** *{@link SfError}{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
*
* @param [throwOnNotFound = false] Optionally indicate if a throw should occur on file read.
* @param [force = false] Optionally force the file to be read from disk even when already read within the process.
*/
read(throwOnNotFound?: boolean, force?: boolean): Promise<P>;
/**
* Read the config file and set the config contents. Returns the config contents of the config file. As an
* optimization, files are only read once per process and updated in memory and via `write()`. To force
* a read from the filesystem pass `force=true`.
* **Throws** *{@link SfError}{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
*
* @param [throwOnNotFound = false] Optionally indicate if a throw should occur on file read.
* @param [force = false] Optionally force the file to be read from disk even when already read within the process.
*/
readSync(throwOnNotFound?: boolean, force?: boolean): P;
/**
* Write the config file with new contents. If no new contents are provided it will write the existing config
* contents that were set from {@link ConfigFile.read}, or an empty file if {@link ConfigFile.read} was not called.
*
* @param newContents The new contents of the file.
*/
write(): Promise<P>;
/**
* Write the config file with new contents. If no new contents are provided it will write the existing config
* contents that were set from {@link ConfigFile.read}, or an empty file if {@link ConfigFile.read} was not called.
*
* @param newContents The new contents of the file.
*/
writeSync(): P;
/**
* Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
*/
exists(): Promise<boolean>;
/**
* Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
*/
existsSync(): boolean;
/**
* Get the stats of the file. Returns the stats of the file.
*
* {@link fs.stat}
*/
stat(): Promise<fsStats>;
/**
* Get the stats of the file. Returns the stats of the file.
*
* {@link fs.stat}
*/
statSync(): fsStats;
/**
* Delete the config file if it exists.
*
* **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
* {@link fs.unlink}
*/
unlink(): Promise<void>;
/**
* Delete the config file if it exists.
*
* **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
* {@link fs.unlink}
*/
unlinkSync(): void;
/**
* Returns the absolute path to the config file.
*
* The first time getPath is called, the path is resolved and becomes immutable. This allows implementers to
* override options properties, like filePath, on the init method for async creation. If that is required for
* creation, the config files can not be synchronously created.
*/
getPath(): string;
/**
* Returns `true` if this config is using the global path, `false` otherwise.
*/
isGlobal(): boolean;
/**
* Used to initialize asynchronous components.
*
* **Throws** *`Error`{ code: 'ENOENT' }* If the {@link ConfigFile.getFilename} file is not found when
* options.throwOnNotFound is true.
*/
protected init(): Promise<void>;
private logAndMergeContents;
private handleWriteError;
}
export declare namespace ConfigFile {
/**
* The interface for Config options.
*/
type Options = {
/**
* The root folder where the config file is stored.
*/
rootFolder?: string;
/**
* The state folder where the config file is stored.
*/
stateFolder?: string;
/**
* The file name.
*/
filename?: string;
/**
* If the file is in the global or project directory.
*/
isGlobal?: boolean;
/**
* If the file is in the state folder or no (.sfdx).
*/
isState?: boolean;
/**
* The full file path where the config file is stored.
*/
filePath?: string;
/**
* Indicates if init should throw if the corresponding config file is not found.
*/
throwOnNotFound?: boolean;
} & BaseConfigStore.Options;
}