@salesforce/core 3.21.5 → 3.22.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.1](https://github.com/forcedotcom/sfdx-core/compare/v3.22.0...v3.22.1) (2022-06-28)
+
+### Bug Fixes
+
+- encrypted key regex tests will no longer be stateful ([06b7fa2](https://github.com/forcedotcom/sfdx-core/commit/06b7fa2f41401155b472c84f13cbf5608150a43e))
+- update dev-scripts so yarn build won't change line endings for LICENSE.txt on Windows ([ec5e48e](https://github.com/forcedotcom/sfdx-core/commit/ec5e48ee1dab2b3999f630aa56c53d353baa717e))
+
+## [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

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/config/configStore.js

@@ -346,5 +346,6 @@ class BaseConfigStore extends kit_1.AsyncOptionalCreatable {
     }
 }
 exports.BaseConfigStore = BaseConfigStore;
+// If encryptedKeys is an array of RegExps, they should not contain the /g (global) or /y (sticky) flags to avoid stateful issues.
 BaseConfigStore.encryptedKeys = [];
 //# sourceMappingURL=configStore.js.map

package/lib/config/tokensConfig.js

@@ -24,5 +24,5 @@ class TokensConfig extends configFile_1.ConfigFile {
     }
 }
 exports.TokensConfig = TokensConfig;
-TokensConfig.encryptedKeys = [/token/gi, /password/gi, /secret/gi];
+TokensConfig.encryptedKeys = [/token/i, /password/i, /secret/i];
 //# sourceMappingURL=tokensConfig.js.map

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) {