@salesforce/core 3.30.14 → 3.31.7

package/lib/config/configStore.d.ts

@@ -1,241 +1,241 @@
-import { AsyncOptionalCreatable } from '@salesforce/kit';
-import { AnyJson, Dictionary, JsonMap, Optional } from '@salesforce/ts-types';
-import { Crypto } from '../crypto/crypto';
-/**
- * The allowed types stored in a config store.
- */
-export declare type ConfigValue = AnyJson;
-/**
- * The type of entries in a config store defined by the key and value type of {@link ConfigContents}.
- */
-export declare type ConfigEntry = [string, ConfigValue];
-/**
- * The type of content a config stores.
- */
-export declare type ConfigContents<T = ConfigValue> = Dictionary<T>;
-export declare type Key<P extends ConfigContents> = Extract<keyof P, string>;
-/**
- * An interface for a config object with a persistent store.
- */
-export interface ConfigStore<P extends ConfigContents = ConfigContents> {
-    entries(): ConfigEntry[];
-    get<K extends Key<P>>(key: K, decrypt: boolean): P[K];
-    get<T extends ConfigValue>(key: string, decrypt: boolean): T;
-    getKeysByValue(value: ConfigValue): Array<Key<P>>;
-    has(key: string): boolean;
-    keys(): Array<Key<P>>;
-    set<K extends Key<P>>(key: K, value: P[K]): void;
-    set<T extends ConfigValue>(key: string, value: T): void;
-    update<K extends Key<P>>(key: K, value: Partial<P[K]>): void;
-    update<T extends ConfigValue>(key: string, value: Partial<T>): void;
-    unset(key: string): boolean;
-    unsetAll(keys: string[]): boolean;
-    clear(): void;
-    values(): ConfigValue[];
-    forEach(actionFn: (key: string, value: ConfigValue) => void): void;
-    awaitEach(actionFn: (key: string, value: ConfigValue) => Promise<void>): Promise<void>;
-    getContents(): P;
-    setContents(contents?: P): void;
-}
-/**
- * An abstract class that implements all the config management functions but
- * none of the storage functions.
- *
- * **Note:** To see the interface, look in typescripts autocomplete help or the npm package's ConfigStore.d.ts file.
- */
-export declare abstract class BaseConfigStore<T extends BaseConfigStore.Options = BaseConfigStore.Options, P extends ConfigContents = ConfigContents> extends AsyncOptionalCreatable<T> implements ConfigStore<P> {
-    protected static encryptedKeys: Array<string | RegExp>;
-    protected options: T;
-    protected crypto?: Crypto;
-    private contents;
-    private statics;
-    /**
-     * Constructor.
-     *
-     * @param options The options for the class instance.
-     * @ignore
-     */
-    constructor(options?: T);
-    /**
-     * Returns an array of {@link ConfigEntry} for each element in the config.
-     */
-    entries(): ConfigEntry[];
-    /**
-     * Returns the value associated to the key, or undefined if there is none.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     * @param decrypt If it is an encrypted key, decrypt the value.
-     * If the value is an object, a clone will be returned.
-     */
-    get<K extends Key<P>>(key: K, decrypt?: boolean): P[K];
-    get<V = ConfigValue>(key: string, decrypt?: boolean): V;
-    /**
-     * Returns the list of keys that contain a value.
-     *
-     * @param value The value to filter keys on.
-     */
-    getKeysByValue(value: ConfigValue): Array<Key<P>>;
-    /**
-     * Returns a boolean asserting whether a value has been associated to the key in the config object or not.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     */
-    has(key: string): boolean;
-    /**
-     * Returns an array that contains the keys for each element in the config object.
-     */
-    keys(): Array<Key<P>>;
-    /**
-     * Sets the value for the key in the config object. This will override the existing value.
-     * To do a partial update, use {@link BaseConfigStore.update}.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     * @param value The value.
-     */
-    set<K extends Key<P>>(key: K, value: P[K]): void;
-    set<V = ConfigValue>(key: string, value: V): void;
-    /**
-     * Updates the value for the key in the config object. If the value is an object, it
-     * will be merged with the existing object.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     * @param value The value.
-     */
-    update<K extends Key<P>>(key: K, value: Partial<P[K]>): void;
-    update<V = ConfigValue>(key: string, value: Partial<V>): void;
-    /**
-     * Returns `true` if an element in the config object existed and has been removed, or `false` if the element does not
-     * exist. {@link BaseConfigStore.has} will return false afterwards.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     */
-    unset(key: string): boolean;
-    /**
-     * Returns `true` if all elements in the config object existed and have been removed, or `false` if all the elements
-     * do not exist (some may have been removed). {@link BaseConfigStore.has(key)} will return false afterwards.
-     *
-     * @param keys The keys. Supports query keys like `a.b[0]`.
-     */
-    unsetAll(keys: string[]): boolean;
-    /**
-     * Removes all key/value pairs from the config object.
-     */
-    clear(): void;
-    /**
-     * Returns an array that contains the values for each element in the config object.
-     */
-    values(): ConfigValue[];
-    /**
-     * Returns the entire config contents.
-     *
-     * *NOTE:* Data will still be encrypted unless decrypt is passed in. A clone of
-     * the data will be returned to prevent storing un-encrypted data in memory and
-     * potentially saving to the file system.
-     *
-     * @param decrypt: decrypt all data in the config. A clone of the data will be returned.
-     *
-     */
-    getContents(decrypt?: boolean): P;
-    /**
-     * Sets the entire config contents.
-     *
-     * @param contents The contents.
-     */
-    setContents(contents?: P): void;
-    /**
-     * Invokes `actionFn` once for each key-value pair present in the config object.
-     *
-     * @param {function} actionFn The function `(key: string, value: ConfigValue) => void` to be called for each element.
-     */
-    forEach(actionFn: (key: string, value: ConfigValue) => void): void;
-    /**
-     * Asynchronously invokes `actionFn` once for each key-value pair present in the config object.
-     *
-     * @param {function} actionFn The function `(key: string, value: ConfigValue) => Promise<void>` to be called for
-     * each element.
-     * @returns {Promise<void>}
-     */
-    awaitEach(actionFn: (key: string, value: ConfigValue) => Promise<void>): Promise<void>;
-    /**
-     * Convert the config object to a JSON object. Returns the config contents.
-     * Same as calling {@link ConfigStore.getContents}
-     */
-    toObject(): JsonMap;
-    /**
-     * Convert an object to a {@link ConfigContents} and set it as the config contents.
-     *
-     * @param obj The object.
-     */
-    setContentsFromObject<U extends JsonMap>(obj: U): void;
-    protected getEncryptedKeys(): Array<string | RegExp>;
-    /**
-     * This config file has encrypted keys and it should attempt to encrypt them.
-     *
-     * @returns Has encrypted keys
-     */
-    protected hasEncryption(): boolean;
-    protected setMethod(contents: ConfigContents, key: string, value?: ConfigValue): void;
-    protected getMethod(contents: ConfigContents, key: string): Optional<ConfigValue>;
-    protected initialContents(): P;
-    /**
-     * Used to initialize asynchronous components.
-     */
-    protected init(): Promise<void>;
-    /**
-     * Initialize the crypto dependency.
-     */
-    protected initCrypto(): Promise<void>;
-    /**
-     * Closes the crypto dependency. Crypto should be close after it's used and no longer needed.
-     */
-    protected clearCrypto(): Promise<void>;
-    /**
-     * Should the given key be encrypted on set methods and decrypted on get methods.
-     *
-     * @param key The key. Supports query key like `a.b[0]`.
-     * @returns Should encrypt/decrypt
-     */
-    protected isCryptoKey(key: string): string | RegExp | undefined;
-    protected encrypt(value: unknown): Optional<string>;
-    protected decrypt(value: unknown): Optional<string>;
-    /**
-     * Encrypt all values in a nested JsonMap.
-     *
-     * @param keyPaths: The complete path of the (nested) data
-     * @param data: The current (nested) data being worked on.
-     */
-    protected recursiveEncrypt<J extends JsonMap>(data: J, parentKey?: string): J;
-    /**
-     * Decrypt all values in a nested JsonMap.
-     *
-     * @param keyPaths: The complete path of the (nested) data
-     * @param data: The current (nested) data being worked on.
-     */
-    protected recursiveDecrypt(data: JsonMap, parentKey?: string): JsonMap;
-    /**
-     * Encrypt/Decrypt all values in a nested JsonMap.
-     *
-     * @param keyPaths: The complete path of the (nested) data
-     * @param data: The current (nested) data being worked on.
-     */
-    private recursiveCrypto;
-}
-/**
- * @ignore
- */
-export declare namespace BaseConfigStore {
-    /**
-     * Options for the config store.
-     */
-    interface Options {
-        /**
-         * Keys to encrypt.
-         *
-         * The preferred way to set encrypted keys is to use {@link BaseConfigStore.encryptedKeys}
-         * so they are constant for all instances of a Config class. However, this is useful for
-         * instantiating subclasses of ConfigStore on the fly (like {@link ConfigFile}) without
-         * defining a new class.
-         */
-        encryptedKeys?: Array<string | RegExp>;
-    }
-}
+import { AsyncOptionalCreatable } from '@salesforce/kit';
+import { AnyJson, Dictionary, JsonMap, Optional } from '@salesforce/ts-types';
+import { Crypto } from '../crypto/crypto';
+/**
+ * The allowed types stored in a config store.
+ */
+export declare type ConfigValue = AnyJson;
+/**
+ * The type of entries in a config store defined by the key and value type of {@link ConfigContents}.
+ */
+export declare type ConfigEntry = [string, ConfigValue];
+/**
+ * The type of content a config stores.
+ */
+export declare type ConfigContents<T = ConfigValue> = Dictionary<T>;
+export declare type Key<P extends ConfigContents> = Extract<keyof P, string>;
+/**
+ * An interface for a config object with a persistent store.
+ */
+export interface ConfigStore<P extends ConfigContents = ConfigContents> {
+    entries(): ConfigEntry[];
+    get<K extends Key<P>>(key: K, decrypt: boolean): P[K];
+    get<T extends ConfigValue>(key: string, decrypt: boolean): T;
+    getKeysByValue(value: ConfigValue): Array<Key<P>>;
+    has(key: string): boolean;
+    keys(): Array<Key<P>>;
+    set<K extends Key<P>>(key: K, value: P[K]): void;
+    set<T extends ConfigValue>(key: string, value: T): void;
+    update<K extends Key<P>>(key: K, value: Partial<P[K]>): void;
+    update<T extends ConfigValue>(key: string, value: Partial<T>): void;
+    unset(key: string): boolean;
+    unsetAll(keys: string[]): boolean;
+    clear(): void;
+    values(): ConfigValue[];
+    forEach(actionFn: (key: string, value: ConfigValue) => void): void;
+    awaitEach(actionFn: (key: string, value: ConfigValue) => Promise<void>): Promise<void>;
+    getContents(): P;
+    setContents(contents?: P): void;
+}
+/**
+ * An abstract class that implements all the config management functions but
+ * none of the storage functions.
+ *
+ * **Note:** To see the interface, look in typescripts autocomplete help or the npm package's ConfigStore.d.ts file.
+ */
+export declare abstract class BaseConfigStore<T extends BaseConfigStore.Options = BaseConfigStore.Options, P extends ConfigContents = ConfigContents> extends AsyncOptionalCreatable<T> implements ConfigStore<P> {
+    protected static encryptedKeys: Array<string | RegExp>;
+    protected options: T;
+    protected crypto?: Crypto;
+    private contents;
+    private statics;
+    /**
+     * Constructor.
+     *
+     * @param options The options for the class instance.
+     * @ignore
+     */
+    constructor(options?: T);
+    /**
+     * Returns an array of {@link ConfigEntry} for each element in the config.
+     */
+    entries(): ConfigEntry[];
+    /**
+     * Returns the value associated to the key, or undefined if there is none.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     * @param decrypt If it is an encrypted key, decrypt the value.
+     * If the value is an object, a clone will be returned.
+     */
+    get<K extends Key<P>>(key: K, decrypt?: boolean): P[K];
+    get<V = ConfigValue>(key: string, decrypt?: boolean): V;
+    /**
+     * Returns the list of keys that contain a value.
+     *
+     * @param value The value to filter keys on.
+     */
+    getKeysByValue(value: ConfigValue): Array<Key<P>>;
+    /**
+     * Returns a boolean asserting whether a value has been associated to the key in the config object or not.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     */
+    has(key: string): boolean;
+    /**
+     * Returns an array that contains the keys for each element in the config object.
+     */
+    keys(): Array<Key<P>>;
+    /**
+     * Sets the value for the key in the config object. This will override the existing value.
+     * To do a partial update, use {@link BaseConfigStore.update}.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     * @param value The value.
+     */
+    set<K extends Key<P>>(key: K, value: P[K]): void;
+    set<V = ConfigValue>(key: string, value: V): void;
+    /**
+     * Updates the value for the key in the config object. If the value is an object, it
+     * will be merged with the existing object.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     * @param value The value.
+     */
+    update<K extends Key<P>>(key: K, value: Partial<P[K]>): void;
+    update<V = ConfigValue>(key: string, value: Partial<V>): void;
+    /**
+     * Returns `true` if an element in the config object existed and has been removed, or `false` if the element does not
+     * exist. {@link BaseConfigStore.has} will return false afterwards.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     */
+    unset(key: string): boolean;
+    /**
+     * Returns `true` if all elements in the config object existed and have been removed, or `false` if all the elements
+     * do not exist (some may have been removed). {@link BaseConfigStore.has(key)} will return false afterwards.
+     *
+     * @param keys The keys. Supports query keys like `a.b[0]`.
+     */
+    unsetAll(keys: string[]): boolean;
+    /**
+     * Removes all key/value pairs from the config object.
+     */
+    clear(): void;
+    /**
+     * Returns an array that contains the values for each element in the config object.
+     */
+    values(): ConfigValue[];
+    /**
+     * Returns the entire config contents.
+     *
+     * *NOTE:* Data will still be encrypted unless decrypt is passed in. A clone of
+     * the data will be returned to prevent storing un-encrypted data in memory and
+     * potentially saving to the file system.
+     *
+     * @param decrypt: decrypt all data in the config. A clone of the data will be returned.
+     *
+     */
+    getContents(decrypt?: boolean): P;
+    /**
+     * Sets the entire config contents.
+     *
+     * @param contents The contents.
+     */
+    setContents(contents?: P): void;
+    /**
+     * Invokes `actionFn` once for each key-value pair present in the config object.
+     *
+     * @param {function} actionFn The function `(key: string, value: ConfigValue) => void` to be called for each element.
+     */
+    forEach(actionFn: (key: string, value: ConfigValue) => void): void;
+    /**
+     * Asynchronously invokes `actionFn` once for each key-value pair present in the config object.
+     *
+     * @param {function} actionFn The function `(key: string, value: ConfigValue) => Promise<void>` to be called for
+     * each element.
+     * @returns {Promise<void>}
+     */
+    awaitEach(actionFn: (key: string, value: ConfigValue) => Promise<void>): Promise<void>;
+    /**
+     * Convert the config object to a JSON object. Returns the config contents.
+     * Same as calling {@link ConfigStore.getContents}
+     */
+    toObject(): JsonMap;
+    /**
+     * Convert an object to a {@link ConfigContents} and set it as the config contents.
+     *
+     * @param obj The object.
+     */
+    setContentsFromObject<U extends JsonMap>(obj: U): void;
+    protected getEncryptedKeys(): Array<string | RegExp>;
+    /**
+     * This config file has encrypted keys and it should attempt to encrypt them.
+     *
+     * @returns Has encrypted keys
+     */
+    protected hasEncryption(): boolean;
+    protected setMethod(contents: ConfigContents, key: string, value?: ConfigValue): void;
+    protected getMethod(contents: ConfigContents, key: string): Optional<ConfigValue>;
+    protected initialContents(): P;
+    /**
+     * Used to initialize asynchronous components.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Initialize the crypto dependency.
+     */
+    protected initCrypto(): Promise<void>;
+    /**
+     * Closes the crypto dependency. Crypto should be close after it's used and no longer needed.
+     */
+    protected clearCrypto(): Promise<void>;
+    /**
+     * Should the given key be encrypted on set methods and decrypted on get methods.
+     *
+     * @param key The key. Supports query key like `a.b[0]`.
+     * @returns Should encrypt/decrypt
+     */
+    protected isCryptoKey(key: string): string | RegExp | undefined;
+    protected encrypt(value: unknown): Optional<string>;
+    protected decrypt(value: unknown): Optional<string>;
+    /**
+     * Encrypt all values in a nested JsonMap.
+     *
+     * @param keyPaths: The complete path of the (nested) data
+     * @param data: The current (nested) data being worked on.
+     */
+    protected recursiveEncrypt<J extends JsonMap>(data: J, parentKey?: string): J;
+    /**
+     * Decrypt all values in a nested JsonMap.
+     *
+     * @param keyPaths: The complete path of the (nested) data
+     * @param data: The current (nested) data being worked on.
+     */
+    protected recursiveDecrypt(data: JsonMap, parentKey?: string): JsonMap;
+    /**
+     * Encrypt/Decrypt all values in a nested JsonMap.
+     *
+     * @param keyPaths: The complete path of the (nested) data
+     * @param data: The current (nested) data being worked on.
+     */
+    private recursiveCrypto;
+}
+/**
+ * @ignore
+ */
+export declare namespace BaseConfigStore {
+    /**
+     * Options for the config store.
+     */
+    interface Options {
+        /**
+         * Keys to encrypt.
+         *
+         * The preferred way to set encrypted keys is to use {@link BaseConfigStore.encryptedKeys}
+         * so they are constant for all instances of a Config class. However, this is useful for
+         * instantiating subclasses of ConfigStore on the fly (like {@link ConfigFile}) without
+         * defining a new class.
+         */
+        encryptedKeys?: Array<string | RegExp>;
+    }
+}