@salesforce/core/lib/config/configFile.d.ts

/// <reference types="node" />
import { Stats as fsStats } from 'fs';
import { Logger } from '../logger';
import { BaseConfigStore, ConfigContents } from './configStore';
/**
 * 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(newContents?: P): 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(newContents?: P): 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>;
}
export declare namespace ConfigFile {
    /**
     * The interface for Config options.
     */
    interface Options extends BaseConfigStore.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;
    }
}