@salesforce/core 4.0.0 → 4.1.0

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2022, Salesforce.com, Inc.
+Copyright (c) 2023, 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:

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,37 +23,25 @@ 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.
 
 ```typescript
 import { strictEqual } from 'assert';
-import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
+import { MockTestOrgData, TestContext } from '@salesforce/core/lib/testSetup';
 import { AuthInfo } from '@salesforce/core';
 
-const $$ = testSetup();
-
 describe('Mocking Auth data', () => {
+  const $$ = new TestContext();
   it('example', async () => {
     const testData = new MockTestOrgData();
-    $$.setConfigStubContents('GlobalInfo', {
-      contents: {
-        orgs: {
-          [testData.username]: await testData.getConfig(),
-        },
-      },
-    });
-    const auth: AuthInfo = await AuthInfo.create({ username: testData.username });
+    await $$.stubAuths(testData);
+    const auth = await AuthInfo.create({ username: testData.username });
     strictEqual(auth.getUsername(), testData.username);
   });
 });
@@ -52,58 +50,86 @@ describe('Mocking Auth data', () => {
 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, SfdxError } from '@salesforce/core';
-import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
+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';
 
-const $$ = testSetup();
-
 describe('Mocking a force server call', () => {
+  const $$ = new TestContext();
   it('example', async () => {
     const records: AnyJson = { records: ['123456', '234567'] };
     const testData = new MockTestOrgData();
-    $$.setConfigStubContents('GlobalInfo', {
-      contents: {
-        orgs: {
-          [testData.username]: await testData.getConfig(),
-        },
-      },
-    });
+    await $$.stubAuths(testData);
     $$.fakeConnectionRequest = (request: AnyJson): Promise<AnyJson> => {
-      const _request: JsonMap = ensureJsonMap(request);
+      const _request = ensureJsonMap(request);
       if (request && ensureString(_request.url).includes('Account')) {
         return Promise.resolve(records);
       } else {
-        return Promise.reject(new SfdxError(`Unexpected request: ${_request.url}`));
+        return Promise.reject(new SfError(`Unexpected request: ${_request.url}`));
       }
     };
-    const connection: Connection = await Connection.create({
+    const connection = await Connection.create({
       authInfo: await AuthInfo.create({ username: testData.username }),
     });
-    const result: QueryResult<{}> = await connection.query('select Id From Account');
+    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, 'myAlias');
+  });
+});
+
+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:
+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 { TestContext } from '@salesforce/core/lib/testSetup';
 import * as os from 'os';
 
-const $$ = testSetup();
-
 describe('Using the built in Sinon sandbox.', () => {
+  const $$ = new TestContext();
   it('example', async () => {
     const unsupportedOS = 'LEO';
     $$.SANDBOX.stub(os, 'platform').returns(unsupportedOS);
@@ -117,13 +143,13 @@ describe('Using the built in Sinon sandbox.', () => {
 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 { SfdxError } from '@salesforce/core';
+import { SfError } from '@salesforce/core';
 import { shouldThrow } from '@salesforce/core/lib/testSetup';
 import { strictEqual } from 'assert';
 
 class TestObject {
   public static async method() {
-    throw new SfdxError('Error', 'ExpectedError');
+    throw new SfError('Error', 'ExpectedError');
   }
 }
 
@@ -138,17 +164,39 @@ 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.
 
 ```typescript
 import { Logger, LogLine } from '@salesforce/core';
-import { testSetup } from '@salesforce/core/lib/testSetup';
+import { TestContext } from '@salesforce/core/lib/testSetup';
 import { strictEqual } from 'assert';
 
-const $$ = testSetup();
-
 const TEST_STRING = 'foo was here';
 
 class TestObject {
@@ -162,10 +210,11 @@ class TestObject {
 }
 
 describe('Testing log lines', () => {
+  const $$ = new TestContext();
   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/authInfoConfig.d.ts

@@ -0,0 +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;
+}

package/lib/config/authInfoConfig.js

@@ -0,0 +1,35 @@
+"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.AuthInfoConfig = void 0;
+const configFile_1 = require("./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));
+ * ```
+ */
+class AuthInfoConfig extends configFile_1.ConfigFile {
+    /**
+     * Gets the config options for a given org ID.
+     *
+     * @param username The username for the org.
+     */
+    static getOptions(username) {
+        return {
+            isGlobal: true,
+            isState: true,
+            filename: `${username}.json`,
+        };
+    }
+}
+exports.AuthInfoConfig = AuthInfoConfig;
+AuthInfoConfig.encryptedKeys = [/token/i, /password/i, /secret/i];
+//# sourceMappingURL=authInfoConfig.js.map

package/lib/config/config.d.ts

@@ -1,4 +1,4 @@
-import { JsonPrimitive } from '@salesforce/ts-types';
+import { JsonPrimitive, Nullable } from '@salesforce/ts-types';
 import { OrgConfigProperties } from '../org/orgConfigProperties';
 import { ConfigFile } from './configFile';
 import { ConfigContents, ConfigValue } from './configStore';
@@ -51,94 +51,137 @@ export interface ConfigPropertyMetaInput {
      */
     failedMessage: string | ((value: ConfigValue) => string);
 }
+export declare enum SfConfigProperties {
+    /**
+     * Disables telemetry reporting
+     */
+    DISABLE_TELEMETRY = "disable-telemetry"
+}
+export declare const SF_ALLOWED_PROPERTIES: {
+    key: SfConfigProperties;
+    description: string;
+    input: {
+        validator: (value: ConfigValue) => boolean;
+        failedMessage: string;
+    };
+}[];
 export declare enum SfdxPropertyKeys {
     /**
      * Username associated with the default dev hub org.
      *
      * @deprecated Replaced by OrgConfigProperties.TARGET_DEV_HUB in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     * will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
      */
     DEFAULT_DEV_HUB_USERNAME = "defaultdevhubusername",
     /**
      * Username associate with the default org.
      *
      * @deprecated Replaced by OrgConfigProperties.TARGET_ORG in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     * will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
      */
     DEFAULT_USERNAME = "defaultusername",
     /**
      * The sid for the debugger configuration.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_ISV_DEBUGGER_SID in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     ISV_DEBUGGER_SID = "isvDebuggerSid",
     /**
      * The url for the debugger configuration.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_ISV_DEBUGGER_URL in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     ISV_DEBUGGER_URL = "isvDebuggerUrl",
     /**
      * The api version
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_API_VERSION in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     API_VERSION = "apiVersion",
     /**
      * Disables telemetry reporting
+     *
+     * @deprecated Replaced by SfPropertyKeys.DISABLE_TELEMETRY in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     DISABLE_TELEMETRY = "disableTelemetry",
     /**
      * Custom templates repo or local location.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_CUSTOM_METADATA_TEMPLATES in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     CUSTOM_ORG_METADATA_TEMPLATES = "customOrgMetadataTemplates",
     /**
      * allows users to override the 10,000 result query limit
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_MAX_QUERY_LIMIT in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     MAX_QUERY_LIMIT = "maxQueryLimit",
-    /** */
+    /**
+     * @deprecated
+     */
     REST_DEPLOY = "restDeploy",
-    /** */
+    /**
+     * @deprecated Replaced by OrgConfigProperties.ORG_INSTANCE_URL in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     */
     INSTANCE_URL = "instanceUrl"
 }
 export declare const SFDX_ALLOWED_PROPERTIES: ({
     key: SfdxPropertyKeys;
     description: string;
+    newKey: OrgConfigProperties;
+    deprecated: boolean;
     input: {
         validator: (value: ConfigValue) => boolean;
         failedMessage: string;
     };
+    encrypted?: undefined;
     hidden?: undefined;
-    newKey?: undefined;
-    deprecated?: undefined;
+} | {
+    key: SfdxPropertyKeys;
+    newKey: OrgConfigProperties;
+    deprecated: boolean;
+    description: string;
+    input?: undefined;
     encrypted?: undefined;
+    hidden?: undefined;
 } | {
     key: SfdxPropertyKeys;
+    newKey: OrgConfigProperties;
+    deprecated: boolean;
     description: string;
-    hidden: boolean;
+    encrypted: boolean;
     input: {
         validator: (value: ConfigValue) => boolean;
         failedMessage: string;
     };
-    newKey?: undefined;
-    deprecated?: undefined;
-    encrypted?: undefined;
+    hidden?: undefined;
 } | {
     key: SfdxPropertyKeys;
-    newKey: OrgConfigProperties;
+    newKey: SfConfigProperties;
     deprecated: boolean;
     description: string;
-    input?: undefined;
-    hidden?: undefined;
+    input: {
+        validator: (value: ConfigValue) => boolean;
+        failedMessage: string;
+    };
     encrypted?: undefined;
+    hidden?: undefined;
 } | {
     key: SfdxPropertyKeys;
     description: string;
-    encrypted: boolean;
+    hidden: boolean;
+    newKey: string;
+    deprecated: boolean;
     input: {
         validator: (value: ConfigValue) => boolean;
         failedMessage: string;
     };
-    hidden?: undefined;
-    newKey?: undefined;
-    deprecated?: undefined;
+    encrypted?: undefined;
 })[];
 export declare const SfProperty: {
     [index: string]: ConfigPropertyMeta;
 };
-export declare type ConfigProperties = {
+export type ConfigProperties = {
     [index: string]: JsonPrimitive;
 };
 /**
@@ -186,6 +229,7 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
      * Clear all the configured properties both local and global.
      */
     static clear(): Promise<void>;
+    static getPropertyConfigMeta(propertyName: string): Nullable<ConfigPropertyMeta>;
     private static propertyConfigMap;
     /**
      * Read, assign, and return the config contents.
@@ -202,7 +246,7 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
      * DO NOT CALL - The config file needs to encrypt values which can only be done asynchronously.
      * Call {@link SfdxConfig.write} instead.
      *
-     * **Throws** *{@link SfdxError}{ name: 'InvalidWriteError' }* Always.
+     * **Throws** *{@link SfError}{ name: 'InvalidWriteError' }* Always.
      *
      * @param newContents Contents to write
      */
@@ -210,8 +254,8 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
     /**
      * Sets a value for a property.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
-     * **Throws** *{@link SfdxError}{ name: 'InvalidConfigValueError' }* If the input validator fails.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'InvalidConfigValueError' }* If the input validator fails.
      *
      * @param key The property to set.
      * @param value The value of the property.
@@ -220,7 +264,7 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
     /**
      * Unsets a value for a property.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* If the input validator fails.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* If the input validator fails.
      *
      * @param key The property to unset.
      */
@@ -228,7 +272,7 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
     /**
      * Get an individual property config.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
      *
      * @param propertyName The name of the property.
      */
@@ -244,3 +288,24 @@ export declare class Config extends ConfigFile<ConfigFile.Options, ConfigPropert
      */
     private cryptProperties;
 }
+export declare class SfdxConfig {
+    private options;
+    private config;
+    private sfdxPath;
+    constructor(options: ConfigFile.Options, config: Config);
+    /**
+     * If Global.SFDX_INTEROPERABILITY is enabled, merge the sfdx config into the sf config
+     */
+    merge(config: ConfigProperties): ConfigProperties | undefined;
+    write(config?: import("@salesforce/ts-types").JsonMap): Promise<void>;
+    private readSync;
+    private getSfdxPath;
+    /**
+     * If toNew is specified: migrate all deprecated configs with a newKey to the newKey.
+     * - For example, defaultusername will be renamed to target-org.
+     *
+     * If toOld is specified: migrate all deprecated configs back to their original key.
+     * - For example, target-org will be renamed to defaultusername.
+     */
+    private translate;
+}