@salesforce/core 3.21.5 → 3.22.1

package/lib/stateAggregator/accessors/tokenAccessor.d.ts

@@ -17,12 +17,53 @@ export declare class GlobaInfoTokenAccessor {
 }
 export declare class TokenAccessor extends AsyncOptionalCreatable {
     private config;
+    /**
+     * Return all tokens.
+     *
+     * @param decrypt
+     * @returns {SfTokens}
+     */
     getAll(decrypt?: boolean): SfTokens;
+    /**
+     * Return a token for the provided name.
+     *
+     * @param name
+     * @param decrypt
+     * @returns {Optional<SfToken & Timestamp>}
+     */
     get(name: string, decrypt?: boolean): Optional<SfToken & Timestamp>;
+    /**
+     * Return true if a given name has a token associated with it.
+     *
+     * @param name
+     * @returns {boolean}
+     */
     has(name: string): boolean;
+    /**
+     * Set the token for the provided name.
+     *
+     * @param name
+     * @param token
+     */
     set(name: string, token: SfToken): void;
+    /**
+     * Update the token for the provided name.
+     *
+     * @param name
+     * @param token
+     */
     update(name: string, token: Partial<SfToken>): void;
+    /**
+     * Unet the token for the provided name.
+     *
+     * @param name
+     */
     unset(name: string): void;
+    /**
+     * Write the contents to the token file.
+     *
+     * @returns {Promise<SfTokens>}
+     */
     write(): Promise<SfTokens>;
     protected init(): Promise<void>;
 }

package/lib/stateAggregator/accessors/tokenAccessor.js

@@ -38,24 +38,65 @@ class GlobaInfoTokenAccessor {
 }
 exports.GlobaInfoTokenAccessor = GlobaInfoTokenAccessor;
 class TokenAccessor extends kit_1.AsyncOptionalCreatable {
+    /**
+     * Return all tokens.
+     *
+     * @param decrypt
+     * @returns {SfTokens}
+     */
     getAll(decrypt = false) {
         return this.config.getContents(decrypt) || {};
     }
+    /**
+     * Return a token for the provided name.
+     *
+     * @param name
+     * @param decrypt
+     * @returns {Optional<SfToken & Timestamp>}
+     */
     get(name, decrypt = false) {
         return this.config.get(name, decrypt);
     }
+    /**
+     * Return true if a given name has a token associated with it.
+     *
+     * @param name
+     * @returns {boolean}
+     */
     has(name) {
         return !!this.getAll()[name];
     }
+    /**
+     * Set the token for the provided name.
+     *
+     * @param name
+     * @param token
+     */
     set(name, token) {
         this.config.set(name, token);
     }
+    /**
+     * Update the token for the provided name.
+     *
+     * @param name
+     * @param token
+     */
     update(name, token) {
         this.config.update(name, token);
     }
+    /**
+     * Unet the token for the provided name.
+     *
+     * @param name
+     */
     unset(name) {
         this.config.unset(name);
     }
+    /**
+     * Write the contents to the token file.
+     *
+     * @returns {Promise<SfTokens>}
+     */
     async write() {
         return this.config.write();
     }

package/lib/stateAggregator/globalInfoConfig.js

@@ -103,7 +103,7 @@ class GlobalInfo extends configFile_1.ConfigFile {
     }
 }
 exports.GlobalInfo = GlobalInfo;
-GlobalInfo.encryptedKeys = [/token/gi, /password/gi, /secret/gi];
+GlobalInfo.encryptedKeys = [/token/i, /password/i, /secret/i];
 GlobalInfo.EMPTY_DATA_MODEL = {
     [types_1.SfInfoKeys.ORGS]: {},
     [types_1.SfInfoKeys.TOKENS]: {},

package/lib/testSetup.d.ts

@@ -88,14 +88,21 @@ export interface TestContext {
         [configName: string]: Optional<ConfigStub>;
         AliasesConfig?: ConfigStub;
         AuthInfoConfig?: ConfigStub;
-        SfdxConfig?: ConfigStub;
+        Config?: ConfigStub;
         SfProjectJson?: ConfigStub;
         TokensConfig?: ConfigStub;
     };
     /**
      * An record of stubs created during instantaion.
      */
-    stubs?: Record<string, sinonType.SinonStub>;
+    stubs: {
+        configRead?: sinonType.SinonStub;
+        configReadSync?: sinonType.SinonStub;
+        configWriteSync?: sinonType.SinonStub;
+        configWrite?: sinonType.SinonStub;
+        configExists?: sinonType.SinonStub;
+        configRemove?: sinonType.SinonStub;
+    };
     /**
      * A function used when resolving the local path. Calls localPathResolverSync by default.
      *
@@ -157,12 +164,45 @@ export interface TestContext {
      * @param value The actual stub contents. The Mock data.
      */
     setConfigStubContents(name: string, value: ConfigContents): void;
+    /**
+     * Set stubs for working in the context of a SfProject
+     */
     inProject(inProject: boolean): void;
+    /**
+     * Stub salesforce org authorizations.
+     */
     stubAuths(...orgs: MockTestOrgData[]): Promise<void>;
+    /**
+     * Stub salesforce sandbox authorizations.
+     */
     stubSandboxes(...orgs: MockTestSandboxData[]): Promise<void>;
+    /**
+     * Stub the aliases in the global aliases config file.
+     */
     stubAliases(aliases: Record<string, string>, group?: AliasGroup): void;
+    /**
+     * Stub contents in the config file.
+     */
+    stubConfig(config: Record<string, string>): void;
+    /**
+     * Stub the tokens in the global token config file.
+     */
+    stubTokens(tokens: Record<string, string>): void;
 }
-export declare const uniqid: () => string;
+/**
+ * A function to generate a unique id and return it in the context of a template, if supplied.
+ *
+ * A template is a string that can contain `${%s}` to be replaced with a unique id.
+ * If the template contains the "%s" placeholder, it will be replaced with the unique id otherwise the id will be appended to the template.
+ *
+ * @param options an object with the following properties:
+ * - template: a template string.
+ * - length: the length of the unique id as presented in hexadecimal.
+ */
+export declare function uniqid(options?: {
+    template?: string;
+    length?: number;
+}): string;
 /**
  * Instantiate a @salesforce/core test context. This is automatically created by `const $$ = testSetup()`
  * but is useful if you don't want to have a global stub of @salesforce/core and you want to isolate it to
@@ -249,10 +289,10 @@ export declare const restoreContext: (testContext: TestContext) => void;
  *    $$.SANDBOX.stub(MyClass.prototype, 'myMethod').returnsFake(() => {});
  *
  *    // Set the contents that is used when aliases are read. Same for all config files.
- *    $$.configStubs.Aliases = { contents: { 'myTestAlias': 'user@company.com' } };
+ *    $$.stubAliases({ 'myTestAlias': 'user@company.com' });
  *
  *    // Will use the contents set above.
- *    const username = Aliases.fetch('myTestAlias');
+ *    const username = (await StateAggregator.getInstance()).aliases.resolveUseranme('myTestAlias');
  *    expect(username).to.equal('user@company.com');
  *  });
  * });
@@ -286,7 +326,29 @@ export declare const unexpectedResult: SfError;
  *
  * @param f The async function that is expected to throw.
  */
-export declare function shouldThrow(f: Promise<unknown>): Promise<never>;
+export declare function shouldThrow(f: Promise<unknown>, message?: string): Promise<never>;
+/**
+ * Use for this testing pattern:
+ * ```
+ *  try {
+ *      call()
+ *      assert.fail('this should never happen');
+ *  } catch (e) {
+ *  ...
+ *  }
+ *
+ *  Just do this
+ *
+ *  try {
+ *      shouldThrowSync(call); // If this succeeds unexpectedResultError is thrown.
+ *  } catch(e) {
+ *  ...
+ *  }
+ * ```
+ *
+ * @param f The function that is expected to throw.
+ */
+export declare function shouldThrowSync(f: () => unknown, message?: string): never;
 /**
  * A helper to determine if a subscription will use callback or errorback.
  * Enable errback to simulate a subscription failure.
@@ -385,7 +447,11 @@ export declare class StreamingMockCometClient extends CometClient {
     disconnect(): Promise<void>;
 }
 /**
- * Mock class for OrgData.
+ * Mock class for Salesforce Orgs.
+ *
+ * @example
+ * const testOrg = new MockTestOrgData();
+ * await $$.stubAuths(testOrg)
  */
 export declare class MockTestOrgData {
     testId: string;
@@ -410,13 +476,38 @@ export declare class MockTestOrgData {
     constructor(id?: string, options?: {
         username: string;
     });
+    /**
+     * Add devhub username to properties.
+     */
     createDevHubUsername(username: string): void;
+    /**
+     * Mark this org as a devhub.
+     */
     makeDevHub(): void;
+    /**
+     * Returns a MockTestOrgData that represents a user created in the org.
+     */
     createUser(user: string): MockTestOrgData;
+    /**
+     * Return mock user information based on this org.
+     */
     getMockUserInfo(): JsonMap;
+    /**
+     * Return the auth config file contents.
+     */
     getConfig(): Promise<AuthFields>;
+    /**
+     * Return the Connection for the org.
+     */
     getConnection(): Promise<Connection>;
 }
+/**
+ * Mock class for Salesforce Sandboxes.
+ *
+ * @example
+ * const testOrg = new MockTestSandboxData();
+ * await $$.stubSandboxes(testOrg)
+ */
 export declare class MockTestSandboxData {
     id: string;
     sandboxOrgId: string;
@@ -428,5 +519,8 @@ export declare class MockTestSandboxData {
         name: string;
         username: string;
     }>);
+    /**
+     * Return the auth config file contents.
+     */
     getConfig(): Promise<SandboxFields>;
 }

package/lib/testSetup.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockTestSandboxData = exports.MockTestOrgData = exports.StreamingMockCometClient = exports.StreamingMockCometSubscription = exports.StreamingMockSubscriptionCall = exports.shouldThrow = exports.unexpectedResult = exports.testSetup = exports.restoreContext = exports.stubContext = exports.instantiateContext = exports.uniqid = void 0;
+exports.MockTestSandboxData = exports.MockTestOrgData = exports.StreamingMockCometClient = exports.StreamingMockCometSubscription = exports.StreamingMockSubscriptionCall = exports.shouldThrowSync = exports.shouldThrow = exports.unexpectedResult = exports.testSetup = exports.restoreContext = exports.stubContext = exports.instantiateContext = exports.uniqid = void 0;
 /*
  * Copyright (c) 2020, salesforce.com, inc.
  * All rights reserved.
@@ -12,6 +12,7 @@ const crypto_1 = require("crypto");
 const events_1 = require("events");
 const os_1 = require("os");
 const path_1 = require("path");
+const util = require("util");
 const kit_1 = require("@salesforce/kit");
 const ts_sinon_1 = require("@salesforce/ts-sinon");
 const ts_types_1 = require("@salesforce/ts-types");
@@ -29,9 +30,28 @@ const org_1 = require("./org");
 const sandboxAccessor_1 = require("./stateAggregator/accessors/sandboxAccessor");
 const aliasesConfig_1 = require("./config/aliasesConfig");
 const global_1 = require("./global");
-const uniqid = () => {
-    return (0, crypto_1.randomBytes)(16).toString('hex');
-};
+/**
+ * A function to generate a unique id and return it in the context of a template, if supplied.
+ *
+ * A template is a string that can contain `${%s}` to be replaced with a unique id.
+ * If the template contains the "%s" placeholder, it will be replaced with the unique id otherwise the id will be appended to the template.
+ *
+ * @param options an object with the following properties:
+ * - template: a template string.
+ * - length: the length of the unique id as presented in hexadecimal.
+ */
+function uniqid(options) {
+    var _a, _b;
+    const uniqueString = (0, crypto_1.randomBytes)(Math.ceil(((_a = options === null || options === void 0 ? void 0 : options.length) !== null && _a !== void 0 ? _a : 32) / 2.0))
+        .toString('hex')
+        .slice(0, (_b = options === null || options === void 0 ? void 0 : options.length) !== null && _b !== void 0 ? _b : 32);
+    if (!(options === null || options === void 0 ? void 0 : options.template)) {
+        return uniqueString;
+    }
+    return options.template.includes('%s')
+        ? util.format(options.template, uniqueString)
+        : `${options.template}${uniqueString}`;
+}
 exports.uniqid = uniqid;
 function getTestLocalPath(uid) {
     return (0, path_1.join)((0, os_1.tmpdir)(), uid, 'sfdx_core', 'local');
@@ -39,11 +59,11 @@ function getTestLocalPath(uid) {
 function getTestGlobalPath(uid) {
     return (0, path_1.join)((0, os_1.tmpdir)(), uid, 'sfdx_core', 'global');
 }
-function retrieveRootPathSync(isGlobal, uid = (0, exports.uniqid)()) {
+function retrieveRootPathSync(isGlobal, uid = uniqid()) {
     return isGlobal ? getTestGlobalPath(uid) : getTestLocalPath(uid);
 }
 // eslint-disable-next-line @typescript-eslint/require-await
-async function retrieveRootPath(isGlobal, uid = (0, exports.uniqid)()) {
+async function retrieveRootPath(isGlobal, uid = uniqid()) {
     return retrieveRootPathSync(isGlobal, uid);
 }
 function defaultFakeConnectionRequest() {
@@ -99,9 +119,10 @@ const instantiateContext = (sinon) => {
         TEST_LOGGER: new logger_1.Logger({
             name: 'SFDX_Core_Test_Logger',
         }).useMemoryLogging(),
-        id: (0, exports.uniqid)(),
-        uniqid: exports.uniqid,
+        id: uniqid(),
+        uniqid,
         configStubs: {},
+        stubs: {},
         // eslint-disable-next-line @typescript-eslint/require-await
         localPathRetriever: async (uid) => getTestLocalPath(uid),
         localPathRetrieverSync: getTestLocalPath,
@@ -167,6 +188,12 @@ const instantiateContext = (sinon) => {
         stubAliases(aliases, group = aliasesConfig_1.AliasGroup.ORGS) {
             this.configStubs.AliasesConfig = { contents: { [group]: aliases } };
         },
+        stubConfig(config) {
+            this.configStubs.Config = { contents: config };
+        },
+        stubTokens(tokens) {
+            this.configStubs.TokensConfig = { contents: tokens };
+        },
     };
     return testContext;
 };
@@ -235,8 +262,8 @@ const stubContext = (testContext) => {
     };
     // Mock out all config file IO for all tests. They can restore individually if they need original functionality.
     // @ts-ignore
-    testContext.SANDBOXES.CONFIG.stub(configFile_1.ConfigFile.prototype, 'readSync').callsFake(readSync);
-    testContext.SANDBOXES.CONFIG.stub(configFile_1.ConfigFile.prototype, 'read').callsFake(read);
+    stubs.configRead = testContext.SANDBOXES.CONFIG.stub(configFile_1.ConfigFile.prototype, 'readSync').callsFake(readSync);
+    stubs.configReadSync = testContext.SANDBOXES.CONFIG.stub(configFile_1.ConfigFile.prototype, 'read').callsFake(read);
     const writeSync = function (newContents) {
         if (!testContext.configStubs[this.constructor.name]) {
             testContext.configStubs[this.constructor.name] = {};
@@ -358,10 +385,10 @@ const _testSetup = (sinon) => {
  *    $$.SANDBOX.stub(MyClass.prototype, 'myMethod').returnsFake(() => {});
  *
  *    // Set the contents that is used when aliases are read. Same for all config files.
- *    $$.configStubs.Aliases = { contents: { 'myTestAlias': 'user@company.com' } };
+ *    $$.stubAliases({ 'myTestAlias': 'user@company.com' });
  *
  *    // Will use the contents set above.
- *    const username = Aliases.fetch('myTestAlias');
+ *    const username = (await StateAggregator.getInstance()).aliases.resolveUseranme('myTestAlias');
  *    expect(username).to.equal('user@company.com');
  *  });
  * });
@@ -395,11 +422,47 @@ exports.unexpectedResult = new sfError_1.SfError('This code was expected to fail
  *
  * @param f The async function that is expected to throw.
  */
-async function shouldThrow(f) {
+async function shouldThrow(f, message) {
     await f;
-    throw exports.unexpectedResult;
+    if (message) {
+        throw new sfError_1.SfError(message, 'UnexpectedResult');
+    }
+    else {
+        throw exports.unexpectedResult;
+    }
 }
 exports.shouldThrow = shouldThrow;
+/**
+ * Use for this testing pattern:
+ * ```
+ *  try {
+ *      call()
+ *      assert.fail('this should never happen');
+ *  } catch (e) {
+ *  ...
+ *  }
+ *
+ *  Just do this
+ *
+ *  try {
+ *      shouldThrowSync(call); // If this succeeds unexpectedResultError is thrown.
+ *  } catch(e) {
+ *  ...
+ *  }
+ * ```
+ *
+ * @param f The function that is expected to throw.
+ */
+function shouldThrowSync(f, message) {
+    f();
+    if (message) {
+        throw new sfError_1.SfError(message, 'UnexpectedResult');
+    }
+    else {
+        throw exports.unexpectedResult;
+    }
+}
+exports.shouldThrowSync = shouldThrowSync;
 /**
  * A helper to determine if a subscription will use callback or errorback.
  * Enable errback to simulate a subscription failure.
@@ -521,10 +584,14 @@ class StreamingMockCometClient extends streamingClient_1.CometClient {
 }
 exports.StreamingMockCometClient = StreamingMockCometClient;
 /**
- * Mock class for OrgData.
+ * Mock class for Salesforce Orgs.
+ *
+ * @example
+ * const testOrg = new MockTestOrgData();
+ * await $$.stubAuths(testOrg)
  */
 class MockTestOrgData {
-    constructor(id = (0, exports.uniqid)(), options) {
+    constructor(id = uniqid(), options) {
         this.testId = id;
         this.userId = `user_id_${this.testId}`;
         this.orgId = `${this.testId}`;
@@ -536,14 +603,23 @@ class MockTestOrgData {
         this.authcode = `${this.testId}/authcode`;
         this.accessToken = `${this.testId}/accessToken`;
         this.refreshToken = `${this.testId}/refreshToken`;
-        this.redirectUri = `http://${this.testId}/localhost:1717/OauthRedirect`;
+        this.redirectUri = 'http://localhost:1717/OauthRedirect';
     }
+    /**
+     * Add devhub username to properties.
+     */
     createDevHubUsername(username) {
         this.devHubUsername = username;
     }
+    /**
+     * Mark this org as a devhub.
+     */
     makeDevHub() {
         this.isDevHub = true;
     }
+    /**
+     * Returns a MockTestOrgData that represents a user created in the org.
+     */
     createUser(user) {
         const userMock = new MockTestOrgData();
         userMock.username = user;
@@ -561,6 +637,9 @@ class MockTestOrgData {
         userMock.isExpired = this.isExpired;
         return userMock;
     }
+    /**
+     * Return mock user information based on this org.
+     */
     getMockUserInfo() {
         return {
             Id: this.userId,
@@ -576,6 +655,9 @@ class MockTestOrgData {
             Email: `user_email@${this.testId}.com`,
         };
     }
+    /**
+     * Return the auth config file contents.
+     */
     async getConfig() {
         const crypto = await crypto_2.Crypto.create();
         const config = {};
@@ -601,19 +683,32 @@ class MockTestOrgData {
         config.isDevHub = this.isDevHub;
         return config;
     }
+    /**
+     * Return the Connection for the org.
+     */
     async getConnection() {
         return (await org_1.Org.create({ aliasOrUsername: this.username })).getConnection();
     }
 }
 exports.MockTestOrgData = MockTestOrgData;
+/**
+ * Mock class for Salesforce Sandboxes.
+ *
+ * @example
+ * const testOrg = new MockTestSandboxData();
+ * await $$.stubSandboxes(testOrg)
+ */
 class MockTestSandboxData {
-    constructor(id = (0, exports.uniqid)(), options) {
+    constructor(id = uniqid(), options) {
         this.id = id;
         this.sandboxOrgId = id;
         this.prodOrgUsername = (options === null || options === void 0 ? void 0 : options.prodOrgUsername) || `admin_${id}@gb.org`;
         this.sandboxName = (options === null || options === void 0 ? void 0 : options.name) || `sandbox_${id}`;
         this.username = (options === null || options === void 0 ? void 0 : options.username) || `${this.prodOrgUsername}.sandbox`;
     }
+    /**
+     * Return the auth config file contents.
+     */
     async getConfig() {
         return {
             sandboxOrgId: this.sandboxOrgId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "3.21.5",
+  "version": "3.22.1",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -56,13 +56,14 @@
   },
   "devDependencies": {
     "@salesforce/dev-config": "^3.0.1",
-    "@salesforce/dev-scripts": "^2.0.1",
+    "@salesforce/dev-scripts": "^2.0.3",
     "@salesforce/prettier-config": "^0.0.2",
     "@salesforce/ts-sinon": "^1.3.21",
     "@types/archiver": "^5.3.1",
     "@types/debug": "0.0.31",
     "@types/jsen": "0.0.21",
     "@types/jsonwebtoken": "8.5.7",
+    "@types/lodash": "^4.14.182",
     "@types/shelljs": "0.8.11",
     "@typescript-eslint/eslint-plugin": "^4.33.0",
     "@typescript-eslint/parser": "4.33.0",
@@ -78,6 +79,7 @@
     "eslint-plugin-jsdoc": "^35.1.2",
     "eslint-plugin-prettier": "^3.1.3",
     "husky": "^7.0.4",
+    "lodash": "^4.17.21",
     "mocha": "^9.1.3",
     "nyc": "^15.1.0",
     "prettier": "^2.5.1",

package/lib/config/keychainConfig.d.ts

@@ -1,19 +0,0 @@
-import { ConfigFile } from './configFile';
-import { ConfigContents } from './configStore';
-/**
- * Represent a key chain config backed by a json file.
- */
-export declare class KeychainConfig extends ConfigFile<ConfigFile.Options> {
-    static getFileName(): string;
-    /**
-     * Gets default options for the KeychainConfig
-     */
-    static getDefaultOptions(): ConfigFile.Options;
-    /**
-     * Write the config file with new contents. If no new contents are passed in
-     * it will write this.contents that was set from read(). Returns the written contents.
-     *
-     * @param newContents the new contents of the file
-     */
-    write(newContents?: ConfigContents): Promise<ConfigContents>;
-}

package/lib/config/keychainConfig.js

@@ -1,44 +0,0 @@
-"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.KeychainConfig = void 0;
-const path_1 = require("path");
-const fs = require("fs");
-const mkdirp = require("mkdirp");
-const configFile_1 = require("./configFile");
-/**
- * Represent a key chain config backed by a json file.
- */
-// istanbul ignore next - getPassword/setPassword is always mocked out
-class KeychainConfig extends configFile_1.ConfigFile {
-    static getFileName() {
-        return 'key.json';
-    }
-    /**
-     * Gets default options for the KeychainConfig
-     */
-    static getDefaultOptions() {
-        return configFile_1.ConfigFile.getDefaultOptions(true, KeychainConfig.getFileName());
-    }
-    /**
-     * Write the config file with new contents. If no new contents are passed in
-     * it will write this.contents that was set from read(). Returns the written contents.
-     *
-     * @param newContents the new contents of the file
-     */
-    async write(newContents) {
-        if (newContents != null) {
-            this.setContents(newContents);
-        }
-        await mkdirp((0, path_1.dirname)(this.getPath()));
-        await fs.promises.writeFile(this.getPath(), JSON.stringify(this.getContents(), null, 4), { mode: '600' });
-        return this.getContents();
-    }
-}
-exports.KeychainConfig = KeychainConfig;
-//# sourceMappingURL=keychainConfig.js.map