@salesforce/core 3.21.4 → 3.22.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [3.22.0](https://github.com/forcedotcom/sfdx-core/compare/v3.21.6...v3.22.0) (2022-06-23)
+
+### Features
+
+- modify uniqid to accept length and template ([#604](https://github.com/forcedotcom/sfdx-core/issues/604)) ([1fd1b5c](https://github.com/forcedotcom/sfdx-core/commit/1fd1b5c40ab7f9b4d66eada94f3ecfa149b263b7))
+
+### [3.21.6](https://github.com/forcedotcom/sfdx-core/compare/v3.21.5...v3.21.6) (2022-06-23)
+
+### [3.21.5](https://github.com/forcedotcom/sfdx-core/compare/v3.21.4...v3.21.5) (2022-06-23)
+
+### Bug Fixes
+
+- bump jsforce ([b1e8604](https://github.com/forcedotcom/sfdx-core/commit/b1e8604203b09df7b252fd6520fb73405e287aa4))
+
 ### [3.21.4](https://github.com/forcedotcom/sfdx-core/compare/v3.21.3...v3.21.4) (2022-06-22)
 
 ### Bug Fixes

package/README.md

@@ -1,9 +1,19 @@
 [![NPM](https://img.shields.io/npm/v/@salesforce/core.svg)](https://www.npmjs.com/package/@salesforce/core)
 [![CircleCI](https://circleci.com/gh/forcedotcom/sfdx-core.svg?style=svg&circle-token=2377ca31221869e9d13448313620486da80e595f)](https://circleci.com/gh/forcedotcom/sfdx-core)
 
+- [Description](#description)
+- [Usage](#usage)
+  - [Contributing](#contributing)
+- [Using TestSetup](#using-testsetup)
+  - [Mocking Authorizations](#mocking-authorizations)
+  - [Mocking Config Files](#mocking-config-files)
+  - [Using the Built-in Sinon Sandboxes](#using-the-built-in-sinon-sandboxes)
+  - [Testing Expected Failures](#testing-expected-failures)
+  - [Testing Log Lines](#testing-log-lines)
+
 # Description
 
-The @salesforce/core library provides client-side management of Salesforce DX projects, org authentication, connections to Salesforce APIs, and other utilities. Much of the core functionality that powers the Salesforcedx plug-ins comes from this library. You can use this functionality in your plug-ins too.
+The @salesforce/core library provides client-side management of Salesforce DX projects, org authentication, connections to Salesforce APIs, and other utilities. Much of the core functionality that powers the Salesforce CLI plugins comes from this library. You can use this functionality in your plugins too.
 
 # Usage
 
@@ -13,16 +23,11 @@ See the [API documentation](https://forcedotcom.github.io/sfdx-core/).
 
 If you are interested in contributing, please take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.
 
-# Related Docs and Repositories
-
-- [@salesforce/command](https://github.com/forcedotcom/cli-packages/tree/main/packages/command) - Contains base Salesforce CLI command, `SfdxCommand`.
-- [@salesforce/plugin-generator](https://github.com/forcedotcom/sfdx-plugin-generate) - The generator plug-in for building plug-ins for Salesforce CLI.
-
 # Using TestSetup
 
 The Salesforce DX Core Library provides a unit testing utility to help with mocking and sand-boxing core components. This feature allows unit tests to execute without needing to make API calls to salesforce.com.
 
-## Mocking AuthInfo
+## Mocking Authorizations
 
 Here you can mock authorization for a Salesforce scratch org.
 
@@ -77,6 +82,43 @@ describe('Mocking a force server call', () => {
 });
 ```
 
+## Mocking Config Files
+
+You can mock the contents of various config files
+
+```typescript
+import { strictEqual } from 'assert';
+import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
+import { StateAggregator, OrgConfigProperties } from '@salesforce/core';
+
+const $$ = testSetup();
+
+describe('Mocking Aliases', () => {
+  it('example', async () => {
+    const testData = new MockTestOrgData();
+    await $$.stubAliases({ myAlias: testData.username });
+    const alias = (await StateAggregator.getInstance()).aliases.get(testData.username);
+    strictEqual(alias, 'myAlais');
+  });
+});
+
+describe('Mocking Config', () => {
+  it('example', async () => {
+    const testData = new MockTestOrgData();
+    await $$.stubConfig({ [OrgConfigProperties.TARGET_ORG]: testData.username });
+    const {value} = (await ConfigAggregator.create()).getInfo(OrgConfigProperties.TARGET_ORG);
+    strictEqual(value, testData.username);
+  });
+});
+
+describe('Mocking Arbitrary Config Files', () => {
+  it('example', async () => {
+    // MyConfigFile must extend the ConfigFile class in order for this to work properly.
+    $$.setConfigStubContents('MyConfigFile', { contents: { foo: 'bar' } });
+  });
+});
+```
+
 ## Using the Built-in Sinon Sandboxes
 
 sfdx-core uses Sinon as its underlying mocking system. If you're unfamiliar with Sinon and it's sandboxing concept you can find more information here:
@@ -126,6 +168,30 @@ describe('Testing for expected errors', () => {
 });
 ```
 
+You can also use `shouldThrowSync` for syncrhonous functions you expect to fail
+
+```typescript
+import { SfError } from '@salesforce/core';
+import { shouldThrowSync } from '@salesforce/core/lib/testSetup';
+import { strictEqual } from 'assert';
+
+class TestObject {
+  public static method() {
+    throw new SfError('Error', 'ExpectedError');
+  }
+}
+
+describe('Testing for expected errors', () => {
+  it('example', async () => {
+    try {
+      shouldThrowSync(() => TestObject.method());
+    } catch (e) {
+      strictEqual(e.name, 'ExpectedError');
+    }
+  });
+});
+```
+
 ## Testing Log Lines
 
 It's also useful to check expected values and content from log lines. TestSetup configures the sfdx-core logger to use an in memory LogLine storage structure. These can be easily accessed from tests.
@@ -151,9 +217,9 @@ class TestObject {
 
 describe('Testing log lines', () => {
   it('example', async () => {
-    const obj: TestObject = new TestObject($$.TEST_LOGGER);
+    const obj = new TestObject($$.TEST_LOGGER);
     obj.method();
-    const records: LogLine[] = $$.TEST_LOGGER.getBufferedRecords();
+    const records = $$.TEST_LOGGER.getBufferedRecords();
     strictEqual(records.length, 1);
     strictEqual(records[0].msg, TEST_STRING);
   });

package/lib/exported.d.ts

@@ -2,8 +2,8 @@ export { OAuth2Config } from 'jsforce';
 export { ConfigFile } from './config/configFile';
 export { TTLConfig } from './config/ttlConfig';
 export { envVars, EnvironmentVariable, SUPPORTED_ENV_VARS, EnvVars } from './config/envVars';
-export { BaseConfigStore, ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
-export { GlobalInfo, SfEntry, SfInfo, SfInfoKeys, SfOrg, SfOrgs, SfToken, SfTokens, StateAggregator, } from './stateAggregator';
+export { ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
+export { GlobalInfo, SfInfo, SfInfoKeys, SfOrg, SfOrgs, SfToken, SfTokens, StateAggregator } from './stateAggregator';
 export { DeviceOauthService, DeviceCodeResponse, DeviceCodePollingResponse } from './deviceOauthService';
 export { OrgUsersConfig } from './config/orgUsersConfig';
 export { ConfigPropertyMeta, ConfigPropertyMetaInput, Config, SfdxPropertyKeys, SfConfigProperties, SFDX_ALLOWED_PROPERTIES, SF_ALLOWED_PROPERTIES, } from './config/config';

package/lib/exported.js

@@ -16,8 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxError = exports.SfError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.SfProjectJson = exports.SfProject = exports.ORG_CONFIG_ALLOWED_PROPERTIES = exports.OrgConfigProperties = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.AuthInfo = exports.SfdxConfigAggregator = exports.ConfigAggregator = exports.SandboxRequestCache = exports.SF_ALLOWED_PROPERTIES = exports.SFDX_ALLOWED_PROPERTIES = exports.SfConfigProperties = exports.SfdxPropertyKeys = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.StateAggregator = exports.SfInfoKeys = exports.GlobalInfo = exports.BaseConfigStore = exports.EnvVars = exports.SUPPORTED_ENV_VARS = exports.EnvironmentVariable = exports.envVars = exports.TTLConfig = exports.ConfigFile = void 0;
-exports.ScratchOrgCache = exports.scratchOrgLifecycleStages = exports.scratchOrgLifecycleEventName = exports.scratchOrgResume = exports.scratchOrgCreate = exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = exports.DefaultUserFields = void 0;
+exports.DefaultUserFields = exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxError = exports.SfError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.SfProjectJson = exports.SfProject = exports.ORG_CONFIG_ALLOWED_PROPERTIES = exports.OrgConfigProperties = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.AuthInfo = exports.SfdxConfigAggregator = exports.ConfigAggregator = exports.SandboxRequestCache = exports.SF_ALLOWED_PROPERTIES = exports.SFDX_ALLOWED_PROPERTIES = exports.SfConfigProperties = exports.SfdxPropertyKeys = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.StateAggregator = exports.SfInfoKeys = exports.GlobalInfo = exports.EnvVars = exports.SUPPORTED_ENV_VARS = exports.EnvironmentVariable = exports.envVars = exports.TTLConfig = exports.ConfigFile = void 0;
+exports.ScratchOrgCache = exports.scratchOrgLifecycleStages = exports.scratchOrgLifecycleEventName = exports.scratchOrgResume = exports.scratchOrgCreate = exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = void 0;
 const messages_1 = require("./messages");
 messages_1.Messages.importMessagesDirectory(__dirname);
 var configFile_1 = require("./config/configFile");
@@ -29,8 +29,6 @@ Object.defineProperty(exports, "envVars", { enumerable: true, get: function () {
 Object.defineProperty(exports, "EnvironmentVariable", { enumerable: true, get: function () { return envVars_1.EnvironmentVariable; } });
 Object.defineProperty(exports, "SUPPORTED_ENV_VARS", { enumerable: true, get: function () { return envVars_1.SUPPORTED_ENV_VARS; } });
 Object.defineProperty(exports, "EnvVars", { enumerable: true, get: function () { return envVars_1.EnvVars; } });
-var configStore_1 = require("./config/configStore");
-Object.defineProperty(exports, "BaseConfigStore", { enumerable: true, get: function () { return configStore_1.BaseConfigStore; } });
 var stateAggregator_1 = require("./stateAggregator");
 Object.defineProperty(exports, "GlobalInfo", { enumerable: true, get: function () { return stateAggregator_1.GlobalInfo; } });
 Object.defineProperty(exports, "SfInfoKeys", { enumerable: true, get: function () { return stateAggregator_1.SfInfoKeys; } });

package/lib/org/authInfo.d.ts

@@ -8,6 +8,7 @@ export declare type OAuth2Config = JsforceOAuth2Config & {
     authCode?: string;
     refreshToken?: string;
     loginUrl?: string;
+    username?: string;
 };
 /**
  * Fields for authorization, org, and local information.
@@ -289,6 +290,7 @@ export declare class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {
     private loadDecryptedAuthFromConfig;
     private isTokenOptions;
     private refreshFn;
+    private readJwtKey;
     private authJwt;
     private tryJwtAuth;
     private buildRefreshTokenConfig;

package/lib/org/authInfo.js

@@ -522,7 +522,7 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
     async init() {
         this.stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
         const username = this.options.username;
-        const authOptions = this.options.oauth2Options || this.options.accessTokenOptions;
+        const authOptions = (this.options.oauth2Options || this.options.accessTokenOptions);
         // Must specify either username and/or options
         if (!username && !authOptions) {
             throw messages.createError('authInfoCreationError');
@@ -534,7 +534,7 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                 throw messages.createError('authInfoOverwriteError');
             }
         }
-        const oauthUsername = username || (0, ts_types_1.getString)(authOptions, 'username');
+        const oauthUsername = username || (authOptions === null || authOptions === void 0 ? void 0 : authOptions.username);
         if (oauthUsername) {
             this.username = oauthUsername;
             await this.stateAggregator.orgs.read(oauthUsername, false, false);
@@ -562,9 +562,9 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
         }
     }
     getInstanceUrl(options, aggregator) {
-        const instanceUrl = (0, ts_types_1.getString)(options, 'instanceUrl') ||
-            aggregator.getPropertyValue(orgConfigProperties_1.OrgConfigProperties.ORG_INSTANCE_URL);
-        return instanceUrl || sfdcUrl_1.SfdcUrl.PRODUCTION;
+        var _a;
+        const instanceUrl = (_a = options === null || options === void 0 ? void 0 : options.instanceUrl) !== null && _a !== void 0 ? _a : aggregator.getPropertyValue(orgConfigProperties_1.OrgConfigProperties.ORG_INSTANCE_URL);
+        return instanceUrl !== null && instanceUrl !== void 0 ? instanceUrl : sfdcUrl_1.SfdcUrl.PRODUCTION;
     }
     /**
      * Initialize this AuthInfo instance with the specified options. If options are not provided, initialize it from cache
@@ -668,15 +668,19 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
             return await callback(error);
         }
     }
+    async readJwtKey(keyFile) {
+        return fs.promises.readFile(keyFile, 'utf8');
+    }
     // Build OAuth config for a JWT auth flow
     async authJwt(options) {
+        var _a;
         if (!options.clientId) {
             throw messages.createError('missingClientId');
         }
-        const privateKeyContents = await fs.promises.readFile((0, ts_types_1.ensure)(options.privateKey), 'utf8');
+        const privateKeyContents = await this.readJwtKey((0, ts_types_1.ensureString)(options.privateKey));
         const { loginUrl = sfdcUrl_1.SfdcUrl.PRODUCTION } = options;
         const url = new sfdcUrl_1.SfdcUrl(loginUrl);
-        const createdOrgInstance = (0, ts_types_1.getString)(options, 'createdOrgInstance', '').trim().toLowerCase();
+        const createdOrgInstance = ((_a = this.getFields().createdOrgInstance) !== null && _a !== void 0 ? _a : '').trim().toLowerCase();
         const audienceUrl = await url.getJwtAudienceUrl(createdOrgInstance);
         let authFieldsBuilder;
         const authErrors = [];
@@ -751,7 +755,6 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
         const { orgId } = parseIdUrl(authFieldsBuilder.id);
         let username = this.getUsername();
         if (!username) {
-            // @ts-ignore
             const userInfo = await this.retrieveUserInfo(authFieldsBuilder.instance_url, authFieldsBuilder.access_token);
             username = (0, ts_types_1.ensureString)(userInfo === null || userInfo === void 0 ? void 0 : userInfo.username);
         }
@@ -854,18 +857,16 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
      * @private
      */
     throwUserGetException(response) {
-        var _a;
+        var _a, _b, _c;
         let errorMsg = '';
-        const bodyAsString = (0, ts_types_1.getString)(response, 'body', JSON.stringify({ message: 'UNKNOWN', errorCode: 'UNKNOWN' }));
+        const bodyAsString = (_a = response.body) !== null && _a !== void 0 ? _a : JSON.stringify({ message: 'UNKNOWN', errorCode: 'UNKNOWN' });
         try {
             const body = (0, kit_1.parseJson)(bodyAsString);
             if ((0, ts_types_1.isArray)(body)) {
-                errorMsg = body
-                    .map((line) => { var _a; return (_a = (0, ts_types_1.getString)(line, 'message')) !== null && _a !== void 0 ? _a : (0, ts_types_1.getString)(line, 'errorCode', 'UNKNOWN'); })
-                    .join(os.EOL);
+                errorMsg = body.map((line) => { var _a, _b; return (_b = (_a = line.message) !== null && _a !== void 0 ? _a : line.errorCode) !== null && _b !== void 0 ? _b : 'UNKNOWN'; }).join(os.EOL);
             }
             else {
-                errorMsg = (_a = (0, ts_types_1.getString)(body, 'message')) !== null && _a !== void 0 ? _a : (0, ts_types_1.getString)(body, 'errorCode', 'UNKNOWN');
+                errorMsg = (_c = (_b = body.message) !== null && _b !== void 0 ? _b : body.errorCode) !== null && _c !== void 0 ? _c : 'UNKNOWN';
             }
         }
         catch (err) {

package/lib/org/connection.js

@@ -380,7 +380,7 @@ class Connection extends jsforce_1.Connection {
     async loadInstanceApiVersion() {
         const authFileFields = this.options.authInfo.getFields();
         const lastCheckedDateString = authFileFields.instanceApiVersionLastRetrieved;
-        let version = (0, ts_types_1.getString)(authFileFields, 'instanceApiVersion');
+        let version = authFileFields.instanceApiVersion;
         let lastChecked;
         try {
             if (lastCheckedDateString && (0, ts_types_1.isString)(lastCheckedDateString)) {

package/lib/org/org.js

@@ -292,7 +292,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
         const DEV_HUB_SOQL = `SELECT CreatedDate,Edition,ExpirationDate FROM ActiveScratchOrg WHERE ScratchOrg='${trimmedId}'`;
         try {
             const results = await devHubConnection.query(DEV_HUB_SOQL);
-            if ((0, ts_types_1.getNumber)(results, 'records.length') !== 1) {
+            if (results.records.length !== 1) {
                 throw new sfError_1.SfError('No results', 'NoResultsError');
             }
         }

package/lib/org/permissionSetAssignment.js

@@ -49,6 +49,7 @@ class PermissionSetAssignment {
      * @param permSetString An array of permission set names.
      */
     async create(id, permSetString) {
+        var _a;
         if (!id) {
             throw messages.createError('userIdRequired');
         }
@@ -61,7 +62,7 @@ class PermissionSetAssignment {
             query += ` AND NamespacePrefix='${nsPrefix}'`;
         }
         const result = await this.org.getConnection().query(query);
-        const permissionSetId = (0, ts_types_1.getString)(result, 'records[0].Id');
+        const permissionSetId = (_a = result === null || result === void 0 ? void 0 : result.records[0]) === null || _a === void 0 ? void 0 : _a.Id;
         if (!permissionSetId) {
             if (nsPrefix) {
                 throw messages.createError('assignCommandPermissionSetNotFoundForNSError', [permSetName, nsPrefix]);

package/lib/org/scratchOrgCreate.js

@@ -142,7 +142,7 @@ const scratchOrgCreate = async (options) => {
         (0, scratchOrgInfoApi_1.requestScratchOrgCreation)(hubOrg, scratchOrgInfo, settingsGenerator),
         getSignupTargetLoginUrl(),
     ]);
-    const scratchOrgInfoId = (0, ts_types_1.ensureString)((0, ts_types_1.getString)(scratchOrgInfoRequestResult, 'id'));
+    const scratchOrgInfoId = (0, ts_types_1.ensureString)(scratchOrgInfoRequestResult.id);
     const cache = await scratchOrgCache_1.ScratchOrgCache.create();
     cache.set(scratchOrgInfoId, {
         hubUsername: hubOrg.getUsername(),

package/lib/org/scratchOrgInfoApi.js

@@ -8,16 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateRevisionCounterToZero = exports.resolveUrl = exports.deploySettings = exports.pollForScratchOrgInfo = exports.requestScratchOrgCreation = exports.authorizeScratchOrg = exports.queryScratchOrgInfo = void 0;
 const kit_1 = require("@salesforce/kit");
-const ts_types_1 = require("@salesforce/ts-types");
 const ts_retry_promise_1 = require("ts-retry-promise");
 const logger_1 = require("../logger");
-const mapKeys_1 = require("../util/mapKeys");
 const messages_1 = require("../messages");
 const sfError_1 = require("../sfError");
 const sfdcUrl_1 = require("../util/sfdcUrl");
 const pollingClient_1 = require("../status/pollingClient");
 const myDomainResolver_1 = require("../status/myDomainResolver");
 const lifecycleEvents_1 = require("../lifecycleEvents");
+const mapKeys_1 = require("../util/mapKeys");
 const authInfo_1 = require("./authInfo");
 const org_1 = require("./org");
 const scratchOrgErrorCodes_1 = require("./scratchOrgErrorCodes");
@@ -195,7 +194,7 @@ const checkOrgDoesntExist = async (scratchOrgInfo) => {
     if (!usernameKey) {
         return;
     }
-    const username = (0, ts_types_1.getString)(scratchOrgInfo, usernameKey);
+    const username = scratchOrgInfo[usernameKey];
     if (username && username.length > 0) {
         try {
             await authInfo_1.AuthInfo.create({ username: username.toLowerCase() });

package/lib/org/user.js

@@ -86,16 +86,16 @@ async function retrieveUserFields(logger, username) {
     if (result.totalSize === 1) {
         const results = (0, kit_1.mapKeys)(result.records[0], (value, key) => (0, kit_1.lowerFirst)(key));
         const fields = {
-            id: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.id)),
+            id: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.id]),
             username,
-            alias: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.alias)),
-            email: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.email)),
-            emailEncodingKey: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.emailEncodingKey)),
-            languageLocaleKey: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.languageLocaleKey)),
-            localeSidKey: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.localeSidKey)),
-            profileId: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.profileId)),
-            lastName: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.lastName)),
-            timeZoneSidKey: (0, ts_types_1.ensure)((0, ts_types_1.getString)(results, exports.REQUIRED_FIELDS.timeZoneSidKey)),
+            alias: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.alias]),
+            email: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.email]),
+            emailEncodingKey: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.emailEncodingKey]),
+            languageLocaleKey: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.languageLocaleKey]),
+            localeSidKey: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.localeSidKey]),
+            profileId: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.profileId]),
+            lastName: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.lastName]),
+            timeZoneSidKey: (0, ts_types_1.ensureString)(results[exports.REQUIRED_FIELDS.timeZoneSidKey]),
         };
         return fields;
     }

package/lib/sfProject.js

@@ -68,13 +68,17 @@ class SfProjectJson extends configFile_1.ConfigFile {
         return contents;
     }
     async write(newContents) {
-        this.setContents(newContents);
+        if (newContents) {
+            this.setContents(newContents);
+        }
         this.validateKeys();
         await this.schemaValidate();
         return super.write();
     }
     writeSync(newContents) {
-        this.setContents(newContents);
+        if (newContents) {
+            this.setContents(newContents);
+        }
         this.validateKeys();
         this.schemaValidateSync();
         return super.writeSync();

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

@@ -25,18 +25,87 @@ export declare abstract class BaseOrgAccessor<T extends ConfigFile, P extends Co
     private configs;
     private contents;
     private logger;
+    /**
+     * Read the auth file for the given useranme. Once the file has been read, it can be reaccessed with the `get` method.
+     *
+     * @param username username to read
+     * @param decrypt if true, decrypt encrypted values
+     * @param throwOnNotFound throw if file is not found for username
+     */
     read(username: string, decrypt?: boolean, throwOnNotFound?: boolean): Promise<Nullable<P>>;
+    /**
+     * Read all the auth files under the global state directory
+     *
+     * @param decrypt if true, decrypt encrypted values
+     */
     readAll(decrypt?: boolean): Promise<P[]>;
+    /**
+     * Return the contents of the username's auth file from cache. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param username username to get
+     * @param decrypt if true, decrypt encrypted values
+     */
     get(username: string, decrypt?: boolean): Nullable<P>;
+    /**
+     * Return the contents of all the auth files from cache. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param decrypt if true, decrypt encrypted values
+     * @returns
+     */
     getAll(decrypt?: boolean): P[];
+    /**
+     * Returns true if the username has been cached.
+     *
+     * @param username
+     */
     has(username: string): boolean;
+    /**
+     * Returns true if there is an auth file for the given username. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param username
+     */
     exists(username: string): Promise<boolean>;
+    /**
+     * Return the file stats for a given userame's auth file.
+     *
+     * @param username
+     */
     stat(username: string): Promise<Nullable<fs.Stats>>;
+    /**
+     * Returns true if there is an auth file for the given username
+     *
+     * @param username
+     */
     hasFile(username: string): Promise<boolean>;
+    /**
+     * Return all auth files under the global state directory.
+     */
     list(): Promise<string[]>;
+    /**
+     * Set the contents for a given username.
+     *
+     * @param username
+     * @param org
+     */
     set(username: string, org: P): void;
+    /**
+     * Update the contents for a given username.
+     *
+     * @param username
+     * @param org
+     */
     update(username: string, org: Partial<P> & JsonMap): void;
+    /**
+     * Delete the auth file for a given username.
+     *
+     * @param username
+     */
     remove(username: string): Promise<void>;
+    /**
+     * Write the contents of the auth file for a given username.
+     *
+     * @param username
+     */
     write(username: string): Promise<Nullable<P>>;
     protected init(): Promise<void>;
     private getAllFiles;

package/lib/stateAggregator/accessors/orgAccessor.js

@@ -63,6 +63,13 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
         this.configs = new Map();
         this.contents = new Map();
     }
+    /**
+     * Read the auth file for the given useranme. Once the file has been read, it can be reaccessed with the `get` method.
+     *
+     * @param username username to read
+     * @param decrypt if true, decrypt encrypted values
+     * @param throwOnNotFound throw if file is not found for username
+     */
     async read(username, decrypt = false, throwOnNotFound = true) {
         try {
             const config = await this.initAuthFile(username, throwOnNotFound);
@@ -73,6 +80,11 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
             return null;
         }
     }
+    /**
+     * Read all the auth files under the global state directory
+     *
+     * @param decrypt if true, decrypt encrypted values
+     */
     async readAll(decrypt = false) {
         const fileChunks = chunk(await this.getAllFiles(), 50);
         for (const fileChunk of fileChunks) {
@@ -85,6 +97,12 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
         }
         return this.getAll(decrypt);
     }
+    /**
+     * Return the contents of the username's auth file from cache. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param username username to get
+     * @param decrypt if true, decrypt encrypted values
+     */
     get(username, decrypt = false) {
         const config = this.configs.get(username);
         if (config) {
@@ -92,23 +110,49 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
         }
         return this.contents.get(username);
     }
+    /**
+     * Return the contents of all the auth files from cache. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param decrypt if true, decrypt encrypted values
+     * @returns
+     */
     getAll(decrypt = false) {
         return [...this.configs.keys()].reduce((orgs, username) => {
             const org = this.get(username, decrypt);
             return org && !(0, kit_1.isEmpty)(org) ? orgs.concat([org]) : orgs;
         }, []);
     }
+    /**
+     * Returns true if the username has been cached.
+     *
+     * @param username
+     */
     has(username) {
         return this.contents.has(username);
     }
+    /**
+     * Returns true if there is an auth file for the given username. The `read` or `readAll` methods must be called first in order to populate the cache.
+     *
+     * @param username
+     */
     async exists(username) {
         const config = this.configs.get(username);
         return config ? await config.exists() : false;
     }
+    /**
+     * Return the file stats for a given userame's auth file.
+     *
+     * @param username
+     */
     async stat(username) {
         const config = this.configs.get(username);
         return config ? await config.stat() : null;
     }
+    /**
+     * Returns true if there is an auth file for the given username
+     *
+     * @param username
+     */
     async hasFile(username) {
         try {
             await fs.promises.access(this.parseFilename(username));
@@ -119,9 +163,18 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
             return false;
         }
     }
+    /**
+     * Return all auth files under the global state directory.
+     */
     async list() {
         return this.getAllFiles();
     }
+    /**
+     * Set the contents for a given username.
+     *
+     * @param username
+     * @param org
+     */
     set(username, org) {
         var _a, _b;
         const config = this.configs.get(username);
@@ -137,17 +190,33 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
             this.contents.set(username, org);
         }
     }
+    /**
+     * Update the contents for a given username.
+     *
+     * @param username
+     * @param org
+     */
     update(username, org) {
         const existing = this.get(username) || {};
         const merged = Object.assign({}, existing, org);
         return this.set(username, merged);
     }
+    /**
+     * Delete the auth file for a given username.
+     *
+     * @param username
+     */
     async remove(username) {
         var _a;
         await ((_a = this.configs.get(username)) === null || _a === void 0 ? void 0 : _a.unlink());
         this.configs.delete(username);
         this.contents.delete(username);
     }
+    /**
+     * Write the contents of the auth file for a given username.
+     *
+     * @param username
+     */
     async write(username) {
         const config = this.configs.get(username);
         if (config) {

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/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.4",
+  "version": "3.22.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -49,7 +49,7 @@
     "form-data": "^4.0.0",
     "graceful-fs": "^4.2.9",
     "js2xmlparser": "^4.0.1",
-    "jsforce": "2.0.0-beta.13",
+    "jsforce": "2.0.0-beta.14",
     "jsonwebtoken": "8.5.1",
     "mkdirp": "1.0.4",
     "ts-retry-promise": "^0.6.0"
@@ -63,6 +63,7 @@
     "@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