@salesforce/core 3.31.7 → 3.31.8

package/lib/config/configFile.js

@@ -1,341 +1,341 @@
-"use strict";
-/*
- * Copyright (c) 2020, salesforce.com, inc.
- * All rights reserved.
- * Licensed under the BSD 3-Clause license.
- * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigFile = void 0;
-const fs = require("fs");
-const fs_1 = require("fs");
-const os_1 = require("os");
-const path_1 = require("path");
-const ts_types_1 = require("@salesforce/ts-types");
-const kit_1 = require("@salesforce/kit");
-const global_1 = require("../global");
-const logger_1 = require("../logger");
-const sfError_1 = require("../sfError");
-const internal_1 = require("../util/internal");
-const configStore_1 = require("./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();
- * ```
- */
-class ConfigFile extends configStore_1.BaseConfigStore {
-    /**
-     * 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) {
-        super(options);
-        // whether file contents have been read
-        this.hasRead = false;
-        this.logger = logger_1.Logger.childFromRoot(this.constructor.name);
-        const statics = this.constructor;
-        let defaultOptions = {};
-        try {
-            defaultOptions = statics.getDefaultOptions();
-        }
-        catch (e) {
-            /* Some implementations don't let you call default options */
-        }
-        // Merge default and passed in options
-        this.options = Object.assign(defaultOptions, this.options);
-    }
-    /**
-     * Returns the config's filename.
-     */
-    static getFileName() {
-        // Can not have abstract static methods, so throw a runtime error.
-        throw new sfError_1.SfError('Unknown filename for config file.');
-    }
-    /**
-     * 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 = false, filename) {
-        return {
-            isGlobal,
-            isState: true,
-            filename: filename ?? this.getFileName(),
-            stateFolder: global_1.Global.SFDX_STATE_FOLDER,
-        };
-    }
-    /**
-     * 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 async resolveRootFolder(isGlobal) {
-        return isGlobal ? (0, os_1.homedir)() : (0, internal_1.resolveProjectPath)();
-    }
-    /**
-     * 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) {
-        return isGlobal ? (0, os_1.homedir)() : (0, internal_1.resolveProjectPathSync)();
-    }
-    /**
-     * 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}
-     */
-    async access(perm) {
-        try {
-            await fs.promises.access(this.getPath(), perm);
-            return true;
-        }
-        catch (err) {
-            return false;
-        }
-    }
-    /**
-     * 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) {
-        try {
-            fs.accessSync(this.getPath(), perm);
-            return true;
-        }
-        catch (err) {
-            return false;
-        }
-    }
-    /**
-     * 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.
-     */
-    async read(throwOnNotFound = false, force = false) {
-        try {
-            // Only need to read config files once.  They are kept up to date
-            // internally and updated persistently via write().
-            if (!this.hasRead || force) {
-                this.logger.info(`Reading config file: ${this.getPath()}`);
-                const obj = (0, kit_1.parseJsonMap)(await fs.promises.readFile(this.getPath(), 'utf8'));
-                this.setContentsFromObject(obj);
-            }
-            return this.getContents();
-        }
-        catch (err) {
-            if (err.code === 'ENOENT') {
-                if (!throwOnNotFound) {
-                    this.setContents();
-                    return this.getContents();
-                }
-            }
-            throw err;
-        }
-        finally {
-            // Necessarily set this even when an error happens to avoid infinite re-reading.
-            // To attempt another read, pass `force=true`.
-            this.hasRead = true;
-        }
-    }
-    /**
-     * 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 = false, force = false) {
-        try {
-            // Only need to read config files once.  They are kept up to date
-            // internally and updated persistently via write().
-            if (!this.hasRead || force) {
-                this.logger.info(`Reading config file: ${this.getPath()}`);
-                const obj = (0, kit_1.parseJsonMap)(fs.readFileSync(this.getPath(), 'utf8'));
-                this.setContentsFromObject(obj);
-            }
-            return this.getContents();
-        }
-        catch (err) {
-            if (err.code === 'ENOENT') {
-                if (!throwOnNotFound) {
-                    this.setContents();
-                    return this.getContents();
-                }
-            }
-            throw err;
-        }
-        finally {
-            // Necessarily set this even when an error happens to avoid infinite re-reading.
-            // To attempt another read, pass `force=true`.
-            this.hasRead = true;
-        }
-    }
-    /**
-     * 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.
-     */
-    async write(newContents) {
-        if (newContents) {
-            this.setContents(newContents);
-        }
-        try {
-            await fs.promises.mkdir((0, path_1.dirname)(this.getPath()), { recursive: true });
-        }
-        catch (err) {
-            throw sfError_1.SfError.wrap(err);
-        }
-        this.logger.info(`Writing to config file: ${this.getPath()}`);
-        await fs.promises.writeFile(this.getPath(), JSON.stringify(this.toObject(), null, 2));
-        return this.getContents();
-    }
-    /**
-     * 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) {
-        if ((0, ts_types_1.isPlainObject)(newContents)) {
-            this.setContents(newContents);
-        }
-        try {
-            fs.mkdirSync((0, path_1.dirname)(this.getPath()), { recursive: true });
-        }
-        catch (err) {
-            throw sfError_1.SfError.wrap(err);
-        }
-        this.logger.info(`Writing to config file: ${this.getPath()}`);
-        fs.writeFileSync(this.getPath(), JSON.stringify(this.toObject(), null, 2));
-        return this.getContents();
-    }
-    /**
-     * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
-     */
-    async exists() {
-        return this.access(fs_1.constants.R_OK);
-    }
-    /**
-     * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
-     */
-    existsSync() {
-        return this.accessSync(fs_1.constants.R_OK);
-    }
-    /**
-     * Get the stats of the file. Returns the stats of the file.
-     *
-     * {@link fs.stat}
-     */
-    async stat() {
-        return fs.promises.stat(this.getPath());
-    }
-    /**
-     * Get the stats of the file. Returns the stats of the file.
-     *
-     * {@link fs.stat}
-     */
-    statSync() {
-        return fs.statSync(this.getPath());
-    }
-    /**
-     * Delete the config file if it exists.
-     *
-     * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
-     * {@link fs.unlink}
-     */
-    async unlink() {
-        const exists = await this.exists();
-        if (exists) {
-            return fs.promises.unlink(this.getPath());
-        }
-        throw new sfError_1.SfError(`Target file doesn't exist. path: ${this.getPath()}`, 'TargetFileNotFound');
-    }
-    /**
-     * Delete the config file if it exists.
-     *
-     * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
-     * {@link fs.unlink}
-     */
-    unlinkSync() {
-        const exists = this.existsSync();
-        if (exists) {
-            return fs.unlinkSync(this.getPath());
-        }
-        throw new sfError_1.SfError(`Target file doesn't exist. path: ${this.getPath()}`, 'TargetFileNotFound');
-    }
-    /**
-     * 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() {
-        if (!this.path) {
-            if (!this.options.filename) {
-                throw new sfError_1.SfError('The ConfigOptions filename parameter is invalid.', 'InvalidParameter');
-            }
-            // Don't let users store config files in homedir without being in the state folder.
-            let configRootFolder = this.options.rootFolder
-                ? this.options.rootFolder
-                : ConfigFile.resolveRootFolderSync(Boolean(this.options.isGlobal));
-            if (this.options.isGlobal === true || this.options.isState === true) {
-                configRootFolder = (0, path_1.join)(configRootFolder, this.options.stateFolder ?? global_1.Global.SFDX_STATE_FOLDER);
-            }
-            this.path = (0, path_1.join)(configRootFolder, this.options.filePath ? this.options.filePath : '', this.options.filename);
-        }
-        return this.path;
-    }
-    /**
-     * Returns `true` if this config is using the global path, `false` otherwise.
-     */
-    isGlobal() {
-        return !!this.options.isGlobal;
-    }
-    /**
-     * Used to initialize asynchronous components.
-     *
-     * **Throws** *`Error`{ code: 'ENOENT' }* If the {@link ConfigFile.getFilename} file is not found when
-     * options.throwOnNotFound is true.
-     */
-    async init() {
-        await super.init();
-        // Read the file, which also sets the path and throws any errors around project paths.
-        await this.read(this.options.throwOnNotFound);
-    }
-}
-exports.ConfigFile = ConfigFile;
+"use strict";
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigFile = void 0;
+const fs = require("fs");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const ts_types_1 = require("@salesforce/ts-types");
+const kit_1 = require("@salesforce/kit");
+const global_1 = require("../global");
+const logger_1 = require("../logger");
+const sfError_1 = require("../sfError");
+const internal_1 = require("../util/internal");
+const configStore_1 = require("./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();
+ * ```
+ */
+class ConfigFile extends configStore_1.BaseConfigStore {
+    /**
+     * 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) {
+        super(options);
+        // whether file contents have been read
+        this.hasRead = false;
+        this.logger = logger_1.Logger.childFromRoot(this.constructor.name);
+        const statics = this.constructor;
+        let defaultOptions = {};
+        try {
+            defaultOptions = statics.getDefaultOptions();
+        }
+        catch (e) {
+            /* Some implementations don't let you call default options */
+        }
+        // Merge default and passed in options
+        this.options = Object.assign(defaultOptions, this.options);
+    }
+    /**
+     * Returns the config's filename.
+     */
+    static getFileName() {
+        // Can not have abstract static methods, so throw a runtime error.
+        throw new sfError_1.SfError('Unknown filename for config file.');
+    }
+    /**
+     * 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 = false, filename) {
+        return {
+            isGlobal,
+            isState: true,
+            filename: filename ?? this.getFileName(),
+            stateFolder: global_1.Global.SFDX_STATE_FOLDER,
+        };
+    }
+    /**
+     * 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 async resolveRootFolder(isGlobal) {
+        return isGlobal ? (0, os_1.homedir)() : (0, internal_1.resolveProjectPath)();
+    }
+    /**
+     * 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) {
+        return isGlobal ? (0, os_1.homedir)() : (0, internal_1.resolveProjectPathSync)();
+    }
+    /**
+     * 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}
+     */
+    async access(perm) {
+        try {
+            await fs.promises.access(this.getPath(), perm);
+            return true;
+        }
+        catch (err) {
+            return false;
+        }
+    }
+    /**
+     * 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) {
+        try {
+            fs.accessSync(this.getPath(), perm);
+            return true;
+        }
+        catch (err) {
+            return false;
+        }
+    }
+    /**
+     * 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.
+     */
+    async read(throwOnNotFound = false, force = false) {
+        try {
+            // Only need to read config files once.  They are kept up to date
+            // internally and updated persistently via write().
+            if (!this.hasRead || force) {
+                this.logger.info(`Reading config file: ${this.getPath()}`);
+                const obj = (0, kit_1.parseJsonMap)(await fs.promises.readFile(this.getPath(), 'utf8'));
+                this.setContentsFromObject(obj);
+            }
+            return this.getContents();
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                if (!throwOnNotFound) {
+                    this.setContents();
+                    return this.getContents();
+                }
+            }
+            throw err;
+        }
+        finally {
+            // Necessarily set this even when an error happens to avoid infinite re-reading.
+            // To attempt another read, pass `force=true`.
+            this.hasRead = true;
+        }
+    }
+    /**
+     * 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 = false, force = false) {
+        try {
+            // Only need to read config files once.  They are kept up to date
+            // internally and updated persistently via write().
+            if (!this.hasRead || force) {
+                this.logger.info(`Reading config file: ${this.getPath()}`);
+                const obj = (0, kit_1.parseJsonMap)(fs.readFileSync(this.getPath(), 'utf8'));
+                this.setContentsFromObject(obj);
+            }
+            return this.getContents();
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                if (!throwOnNotFound) {
+                    this.setContents();
+                    return this.getContents();
+                }
+            }
+            throw err;
+        }
+        finally {
+            // Necessarily set this even when an error happens to avoid infinite re-reading.
+            // To attempt another read, pass `force=true`.
+            this.hasRead = true;
+        }
+    }
+    /**
+     * 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.
+     */
+    async write(newContents) {
+        if (newContents) {
+            this.setContents(newContents);
+        }
+        try {
+            await fs.promises.mkdir((0, path_1.dirname)(this.getPath()), { recursive: true });
+        }
+        catch (err) {
+            throw sfError_1.SfError.wrap(err);
+        }
+        this.logger.info(`Writing to config file: ${this.getPath()}`);
+        await fs.promises.writeFile(this.getPath(), JSON.stringify(this.toObject(), null, 2));
+        return this.getContents();
+    }
+    /**
+     * 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) {
+        if ((0, ts_types_1.isPlainObject)(newContents)) {
+            this.setContents(newContents);
+        }
+        try {
+            fs.mkdirSync((0, path_1.dirname)(this.getPath()), { recursive: true });
+        }
+        catch (err) {
+            throw sfError_1.SfError.wrap(err);
+        }
+        this.logger.info(`Writing to config file: ${this.getPath()}`);
+        fs.writeFileSync(this.getPath(), JSON.stringify(this.toObject(), null, 2));
+        return this.getContents();
+    }
+    /**
+     * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
+     */
+    async exists() {
+        return this.access(fs_1.constants.R_OK);
+    }
+    /**
+     * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
+     */
+    existsSync() {
+        return this.accessSync(fs_1.constants.R_OK);
+    }
+    /**
+     * Get the stats of the file. Returns the stats of the file.
+     *
+     * {@link fs.stat}
+     */
+    async stat() {
+        return fs.promises.stat(this.getPath());
+    }
+    /**
+     * Get the stats of the file. Returns the stats of the file.
+     *
+     * {@link fs.stat}
+     */
+    statSync() {
+        return fs.statSync(this.getPath());
+    }
+    /**
+     * Delete the config file if it exists.
+     *
+     * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
+     * {@link fs.unlink}
+     */
+    async unlink() {
+        const exists = await this.exists();
+        if (exists) {
+            return fs.promises.unlink(this.getPath());
+        }
+        throw new sfError_1.SfError(`Target file doesn't exist. path: ${this.getPath()}`, 'TargetFileNotFound');
+    }
+    /**
+     * Delete the config file if it exists.
+     *
+     * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
+     * {@link fs.unlink}
+     */
+    unlinkSync() {
+        const exists = this.existsSync();
+        if (exists) {
+            return fs.unlinkSync(this.getPath());
+        }
+        throw new sfError_1.SfError(`Target file doesn't exist. path: ${this.getPath()}`, 'TargetFileNotFound');
+    }
+    /**
+     * 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() {
+        if (!this.path) {
+            if (!this.options.filename) {
+                throw new sfError_1.SfError('The ConfigOptions filename parameter is invalid.', 'InvalidParameter');
+            }
+            // Don't let users store config files in homedir without being in the state folder.
+            let configRootFolder = this.options.rootFolder
+                ? this.options.rootFolder
+                : ConfigFile.resolveRootFolderSync(Boolean(this.options.isGlobal));
+            if (this.options.isGlobal === true || this.options.isState === true) {
+                configRootFolder = (0, path_1.join)(configRootFolder, this.options.stateFolder ?? global_1.Global.SFDX_STATE_FOLDER);
+            }
+            this.path = (0, path_1.join)(configRootFolder, this.options.filePath ? this.options.filePath : '', this.options.filename);
+        }
+        return this.path;
+    }
+    /**
+     * Returns `true` if this config is using the global path, `false` otherwise.
+     */
+    isGlobal() {
+        return !!this.options.isGlobal;
+    }
+    /**
+     * Used to initialize asynchronous components.
+     *
+     * **Throws** *`Error`{ code: 'ENOENT' }* If the {@link ConfigFile.getFilename} file is not found when
+     * options.throwOnNotFound is true.
+     */
+    async init() {
+        await super.init();
+        // Read the file, which also sets the path and throws any errors around project paths.
+        await this.read(this.options.throwOnNotFound);
+    }
+}
+exports.ConfigFile = ConfigFile;
 //# sourceMappingURL=configFile.js.map