@salesforce/core 3.30.14 → 3.31.7

package/LICENSE.txt

@@ -1,12 +1,12 @@
-Copyright (c) 2022, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
+Copyright (c) 2022, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,227 +1,222 @@
-[![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 Salesforce CLI plugins comes from this library. You can use this functionality in your plugins too.
-
-# Usage
-
-See the [API documentation](https://forcedotcom.github.io/sfdx-core/).
-
-## Contributing
-
-If you are interested in contributing, please take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.
-
-# 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 Authorizations
-
-Here you can mock authorization for a Salesforce scratch org.
-
-```typescript
-import { strictEqual } from 'assert';
-import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
-import { AuthInfo } from '@salesforce/core';
-
-const $$ = testSetup();
-
-describe('Mocking Auth data', () => {
-  it('example', async () => {
-    const testData = new MockTestOrgData();
-    await $$.stubAuths(testData);
-    const auth = await AuthInfo.create({ username: testData.username });
-    strictEqual(auth.getUsername(), testData.username);
-  });
-});
-```
-
-After having a valid AuthInfo object you can then create fake connections to a Salesforce.com scratch org. This allows for writing tests that can validate result responses for SOQL queries and REST endpoints.
-
-```typescript
-import { AuthInfo, Connection, SfError } from '@salesforce/core';
-import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
-import { AnyJson, ensureJsonMap, JsonMap } from '@salesforce/ts-types';
-import { ensureString } from '@salesforce/ts-types';
-import { deepStrictEqual } from 'assert';
-import { QueryResult } from 'jsforce';
-
-const $$ = testSetup();
-
-describe('Mocking a force server call', () => {
-  it('example', async () => {
-    const records: AnyJson = { records: ['123456', '234567'] };
-    const testData = new MockTestOrgData();
-    await $$.stubAuths(testData);
-    $$.fakeConnectionRequest = (request: AnyJson): Promise<AnyJson> => {
-      const _request = ensureJsonMap(request);
-      if (request && ensureString(_request.url).includes('Account')) {
-        return Promise.resolve(records);
-      } else {
-        return Promise.reject(new SfError(`Unexpected request: ${_request.url}`));
-      }
-    };
-    const connection = await Connection.create({
-      authInfo: await AuthInfo.create({ username: testData.username }),
-    });
-    const result = await connection.query('select Id From Account');
-    deepStrictEqual(result, records);
-  });
-});
-```
-
-## 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 its sandboxing concept you can find more information here:
-https://sinonjs.org/
-Sinon `stub`s and `spy`s must be cleaned up after test invocations. To ease the use of Sinon with sfdx core we've exposed our sandbox in TestSetup. After adding your own `stub`s and/or `spy`s they will automatically be cleaned up after each test using mocha's afterEach method.
-
-```typescript
-import { strictEqual } from 'assert';
-
-import { testSetup } from '@salesforce/core/lib/testSetup';
-import * as os from 'os';
-
-const $$ = testSetup();
-
-describe('Using the built in Sinon sandbox.', () => {
-  it('example', async () => {
-    const unsupportedOS = 'LEO';
-    $$.SANDBOX.stub(os, 'platform').returns(unsupportedOS);
-    strictEqual(os.platform(), unsupportedOS);
-  });
-});
-```
-
-## Testing Expected Failures
-
-It's important to have negative tests that ensure proper error handling. With `shouldThrow` it's easy to test for expected async rejections.
-
-```typescript
-import { SfError } from '@salesforce/core';
-import { shouldThrow } from '@salesforce/core/lib/testSetup';
-import { strictEqual } from 'assert';
-
-class TestObject {
-  public static async method() {
-    throw new SfError('Error', 'ExpectedError');
-  }
-}
-
-describe('Testing for expected errors', () => {
-  it('example', async () => {
-    try {
-      await shouldThrow(TestObject.method());
-    } catch (e) {
-      strictEqual(e.name, 'ExpectedError');
-    }
-  });
-});
-```
-
-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.
-
-```typescript
-import { Logger, LogLine } from '@salesforce/core';
-import { testSetup } from '@salesforce/core/lib/testSetup';
-import { strictEqual } from 'assert';
-
-const $$ = testSetup();
-
-const TEST_STRING = 'foo was here';
-
-class TestObject {
-  constructor(private logger: Logger) {
-    this.logger = logger.child('TestObject');
-  }
-
-  public method() {
-    this.logger.error(TEST_STRING);
-  }
-}
-
-describe('Testing log lines', () => {
-  it('example', async () => {
-    const obj = new TestObject($$.TEST_LOGGER);
-    obj.method();
-    const records = $$.TEST_LOGGER.getBufferedRecords();
-    strictEqual(records.length, 1);
-    strictEqual(records[0].msg, TEST_STRING);
-  });
-});
-```
+[![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 Salesforce CLI plugins comes from this library. You can use this functionality in your plugins too.
+
+# Usage
+
+See the [API documentation](https://forcedotcom.github.io/sfdx-core/).
+
+## Contributing
+
+If you are interested in contributing, please take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.
+
+# 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 Authorizations
+
+Here you can mock authorization for a Salesforce scratch org.
+
+```typescript
+import { strictEqual } from 'assert';
+import { MockTestOrgData, TestContext } from '@salesforce/core/lib/testSetup';
+import { AuthInfo } from '@salesforce/core';
+
+describe('Mocking Auth data', () => {
+  const $$ = new TestContext();
+  it('example', async () => {
+    const testData = new MockTestOrgData();
+    await $$.stubAuths(testData);
+    const auth = await AuthInfo.create({ username: testData.username });
+    strictEqual(auth.getUsername(), testData.username);
+  });
+});
+```
+
+After having a valid AuthInfo object you can then create fake connections to a Salesforce.com scratch org. This allows for writing tests that can validate result responses for SOQL queries and REST endpoints.
+
+```typescript
+import { AuthInfo, Connection, SfError } from '@salesforce/core';
+import { MockTestOrgData, TestContext } from '@salesforce/core/lib/testSetup';
+import { AnyJson, ensureJsonMap, JsonMap } from '@salesforce/ts-types';
+import { ensureString } from '@salesforce/ts-types';
+import { deepStrictEqual } from 'assert';
+import { QueryResult } from 'jsforce';
+
+describe('Mocking a force server call', () => {
+  const $$ = new TestContext();
+  it('example', async () => {
+    const records: AnyJson = { records: ['123456', '234567'] };
+    const testData = new MockTestOrgData();
+    await $$.stubAuths(testData);
+    $$.fakeConnectionRequest = (request: AnyJson): Promise<AnyJson> => {
+      const _request = ensureJsonMap(request);
+      if (request && ensureString(_request.url).includes('Account')) {
+        return Promise.resolve(records);
+      } else {
+        return Promise.reject(new SfError(`Unexpected request: ${_request.url}`));
+      }
+    };
+    const connection = await Connection.create({
+      authInfo: await AuthInfo.create({ username: testData.username }),
+    });
+    const result = await connection.query('select Id From Account');
+    deepStrictEqual(result, records);
+  });
+});
+```
+
+## Mocking Config Files
+
+You can mock the contents of various config files
+
+```typescript
+import { strictEqual } from 'assert';
+import { MockTestOrgData, TestContext } from '@salesforce/core/lib/testSetup';
+import { StateAggregator, OrgConfigProperties } from '@salesforce/core';
+
+describe('Mocking Aliases', () => {
+  const $$ = new TestContext();
+  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 its sandboxing concept you can find more information here:
+https://sinonjs.org/
+Sinon `stub`s and `spy`s must be cleaned up after test invocations. To ease the use of Sinon with sfdx core we've exposed our sandbox in TestSetup. After adding your own `stub`s and/or `spy`s they will automatically be cleaned up after each test using mocha's afterEach method.
+
+```typescript
+import { strictEqual } from 'assert';
+
+import { TestContext } from '@salesforce/core/lib/testSetup';
+import * as os from 'os';
+
+describe('Using the built in Sinon sandbox.', () => {
+  const $$ = new TestContext();
+  it('example', async () => {
+    const unsupportedOS = 'LEO';
+    $$.SANDBOX.stub(os, 'platform').returns(unsupportedOS);
+    strictEqual(os.platform(), unsupportedOS);
+  });
+});
+```
+
+## Testing Expected Failures
+
+It's important to have negative tests that ensure proper error handling. With `shouldThrow` it's easy to test for expected async rejections.
+
+```typescript
+import { SfError } from '@salesforce/core';
+import { shouldThrow } from '@salesforce/core/lib/testSetup';
+import { strictEqual } from 'assert';
+
+class TestObject {
+  public static async method() {
+    throw new SfError('Error', 'ExpectedError');
+  }
+}
+
+describe('Testing for expected errors', () => {
+  it('example', async () => {
+    try {
+      await shouldThrow(TestObject.method());
+    } catch (e) {
+      strictEqual(e.name, 'ExpectedError');
+    }
+  });
+});
+```
+
+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.
+
+```typescript
+import { Logger, LogLine } from '@salesforce/core';
+import { TestContext } from '@salesforce/core/lib/testSetup';
+import { strictEqual } from 'assert';
+
+const TEST_STRING = 'foo was here';
+
+class TestObject {
+  constructor(private logger: Logger) {
+    this.logger = logger.child('TestObject');
+  }
+
+  public method() {
+    this.logger.error(TEST_STRING);
+  }
+}
+
+describe('Testing log lines', () => {
+  const $$ = new TestContext();
+  it('example', async () => {
+    const obj = new TestObject($$.TEST_LOGGER);
+    obj.method();
+    const records = $$.TEST_LOGGER.getBufferedRecords();
+    strictEqual(records.length, 1);
+    strictEqual(records[0].msg, TEST_STRING);
+  });
+});
+```

package/lib/config/aliasesConfig.d.ts

@@ -1,12 +1,12 @@
-import { ConfigGroup } from './configGroup';
-import { ConfigContents, ConfigValue } from './configStore';
-/**
- * Different groups of aliases. Currently only support orgs.
- */
-export declare enum AliasGroup {
-    ORGS = "orgs"
-}
-export declare class AliasesConfig extends ConfigGroup<ConfigGroup.Options> {
-    static getDefaultOptions(): ConfigGroup.Options;
-    protected setMethod(contents: ConfigContents, key: string, value?: ConfigValue): void;
-}
+import { ConfigGroup } from './configGroup';
+import { ConfigContents, ConfigValue } from './configStore';
+/**
+ * Different groups of aliases. Currently only support orgs.
+ */
+export declare enum AliasGroup {
+    ORGS = "orgs"
+}
+export declare class AliasesConfig extends ConfigGroup<ConfigGroup.Options> {
+    static getDefaultOptions(): ConfigGroup.Options;
+    protected setMethod(contents: ConfigContents, key: string, value?: ConfigValue): void;
+}

package/lib/config/aliasesConfig.js

@@ -1,28 +1,28 @@
-"use strict";
-/*
- * Copyright (c) 2022, 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.AliasesConfig = exports.AliasGroup = void 0;
-const configGroup_1 = require("./configGroup");
-/**
- * Different groups of aliases. Currently only support orgs.
- */
-var AliasGroup;
-(function (AliasGroup) {
-    AliasGroup["ORGS"] = "orgs";
-})(AliasGroup = exports.AliasGroup || (exports.AliasGroup = {}));
-class AliasesConfig extends configGroup_1.ConfigGroup {
-    static getDefaultOptions() {
-        return { ...configGroup_1.ConfigGroup.getOptions(AliasGroup.ORGS, 'alias.json'), isGlobal: true, isState: true };
-    }
-    // eslint-disable-next-line class-methods-use-this
-    setMethod(contents, key, value) {
-        contents[key] = value;
-    }
-}
-exports.AliasesConfig = AliasesConfig;
+"use strict";
+/*
+ * Copyright (c) 2022, 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.AliasesConfig = exports.AliasGroup = void 0;
+const configGroup_1 = require("./configGroup");
+/**
+ * Different groups of aliases. Currently only support orgs.
+ */
+var AliasGroup;
+(function (AliasGroup) {
+    AliasGroup["ORGS"] = "orgs";
+})(AliasGroup = exports.AliasGroup || (exports.AliasGroup = {}));
+class AliasesConfig extends configGroup_1.ConfigGroup {
+    static getDefaultOptions() {
+        return { ...configGroup_1.ConfigGroup.getOptions(AliasGroup.ORGS, 'alias.json'), isGlobal: true, isState: true };
+    }
+    // eslint-disable-next-line class-methods-use-this
+    setMethod(contents, key, value) {
+        contents[key] = value;
+    }
+}
+exports.AliasesConfig = AliasesConfig;
 //# sourceMappingURL=aliasesConfig.js.map

package/lib/config/authInfoConfig.d.ts

@@ -1,19 +1,19 @@
-import { AuthFields } from '../org';
-import { ConfigFile } from './configFile';
-/**
- * An auth config file that stores information such as access tokens, usernames, etc.,
- * in the global sfdx directory (~/.sfdx).
- *
- * ```
- * const authInfo = await AuthInfoConfig.create(AuthInfoConfig.getOptions(username));
- * ```
- */
-export declare class AuthInfoConfig extends ConfigFile<ConfigFile.Options, AuthFields> {
-    protected static encryptedKeys: RegExp[];
-    /**
-     * Gets the config options for a given org ID.
-     *
-     * @param username The username for the org.
-     */
-    static getOptions(username: string): ConfigFile.Options;
-}
+import { AuthFields } from '../org';
+import { ConfigFile } from './configFile';
+/**
+ * An auth config file that stores information such as access tokens, usernames, etc.,
+ * in the global sfdx directory (~/.sfdx).
+ *
+ * ```
+ * const authInfo = await AuthInfoConfig.create(AuthInfoConfig.getOptions(username));
+ * ```
+ */
+export declare class AuthInfoConfig extends ConfigFile<ConfigFile.Options, AuthFields> {
+    protected static encryptedKeys: RegExp[];
+    /**
+     * Gets the config options for a given org ID.
+     *
+     * @param username The username for the org.
+     */
+    static getOptions(username: string): ConfigFile.Options;
+}