feat!: jsforce-node, top-level exports, improved sfError

BREAKING CHANGE: top-level exports will prevent imports from @salesforce/core/lib/etc
BREAKING CHANGE: uses jsforce-node in place of jsforce
BREAKING CHANGE: type changes for SFError
BREAKING CHANGE: remove previously deprecated  checkLightningDomain, aliasAccessor

* feat: sfError

* chore: tsconfig changes to get es2022 error.cause (node 18+)

* refactor: no mutate params, no NamedError

* feat: let cause be unknown for constructor, create (like wrap)

* chore: wrap an Error (so cause can be the original error)

* chore: tsconfig for postcompile (doc)

* docs: migrating

* chore: top-level export of config

* refactor: interface => type

* refactor: simplify exports, add stateAggregator

* chore: import default on messageTransformer

* refactor: typing for sfError.getObject, omit undefined props

* refactor: restore param mutation/side-effects

---------

Co-authored-by: svc-cli-bot <[email protected]>

.eslintrc.cjs

@@ -10,6 +10,5 @@
 
 module.exports = {
   extends: ['eslint-config-salesforce-typescript', 'eslint-config-salesforce-license'],
-  rules: {},
   root: true,
 };

.sfdevrc.json

@@ -9,6 +9,12 @@
       "output": ["lib/**", "*.tsbuildinfo"],
       "clean": "if-file-deleted"
     },
+    "build": {
+      "dependencies": ["compile", "lint"]
+    },
+    "compile-typedoc": {
+      "command": "tsc -p typedocExamples"
+    },
     "link-check": {
       "command": "node -e \"process.exit(process.env.CI ? 0 : 1)\" || linkinator \"./*.md\" --skip \"examples/README.md|CHANGELOG.md|node_modules|test/|confluence.internal.salesforce.com|my.salesforce.com|%s\" --markdown --retry --directory-listing --verbosity error",
       "files": ["./*.md", "./examples/**/*.md", "./messages/**/*.md", "./!(CHANGELOG).md"],

MIGRATING_V6-V7.md

@@ -0,0 +1,79 @@
+# Migrating `@salesforce/core` from v6 to v7
+
+v7 replaces `jsforce` with the new `@jsforce/jsforce-node`. It's a much smaller library. See https://github.com/jsforce/jsforce/issues/1374.
+
+If you use `@salesforce/core` AND jsforce together, you should switch to using `@jsforce/jsforce-node`.
+
+If you use another library that is using jsforce modules or types, be sure to update to a version of that library which uses `@jsforce/jsforce-node`
+
+## Interfaces=>Type
+
+We're going to standardize on Types instead of interfaces. They're almost identical except where they aren't. You probably won't notice.
+
+## Breaking changes to AliasAccessor
+
+Alias accessor had previously deprecated methods that are removed by this PR.
+
+- `set`
+- `unset`
+- `unsetAll`
+- `write` (has been a no-op since v6)
+
+If you use these, typically via StateAggregator, update your code to use `setAndSave` or `unsetAndSave`
+
+## SfError
+
+SfError previously had a `cause` that conflicted with the more recent ES2022 native Error.cause
+
+SfError has some new convenience methods. SfError.create (pass in props instead of setting 5 via params and others via instance methods).  
+SfError.wrap and the `cause` prop of SfError.create are now typed as `unknown` for convenience (throw the `unknown` from a catch block without having to worry about types!).
+SfError.data is now constrained to be AnyJson (some sort of JSON/primitive or collection of that).
+
+## Top-level exports
+
+v7 exports more top-level modules. If you had previously imported via `@salesforce/core/lib/foo` you may be able to import them from the top-level. See the package.json for what's available now.
+
+everything that was previously available via `import ____ from '@salesforce/core'` is still available the same way.
+
+```
+"./messages": {
+      "types": "./lib/messages.d.ts",
+      "require": "./lib/messages.js",
+      "import": "./lib/messages.js"
+    },
+    "./logger": {
+      "types": "./lib/logger.d.ts",
+      "require": "./lib/logger.js",
+      "import": "./lib/logger.js"
+    },
+    "./project": {
+      "types": "./lib/project.d.ts",
+      "require": "./lib/project.js",
+      "import": "./lib/project.js"
+    },
+    "./sfError": {
+      "types": "./lib/sfError.d.ts",
+      "require": "./lib/sfError.js",
+      "import": "./lib/sfError.js"
+    },
+    "./stateAggregator": {
+      "types": "./lib/stateAggregator/stateAggregator.d.ts",
+      "require": "./lib/stateAggregator/stateAggregator.js",
+      "import": "./lib/stateAggregator/stateAggregator.js"
+    },
+    "./configAggregator": {
+      "types": "./lib/config/configAggregator.d.ts",
+      "require": "./lib/config/configAggregator.js",
+      "import": "./lib/config/configAggregator.js"
+    },
+    "./lifecycle": {
+      "types": "./lib/lifecycleEvents.d.ts",
+      "require": "./lib/lifecycleEvents.js",
+      "import": "./lib/lifecycleEvents.js"
+    },
+    "./envVars": {
+      "types": "./lib/config/envVars.d.ts",
+      "require.js": "./lib/config/envVars.js",
+      "import": "./lib/config/envVars.js"
+    },
+```

TEST_SETUP.md

@@ -39,7 +39,7 @@ 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';
+import { QueryResult } from '@jsforce/jsforce-node';
 
 describe('Mocking a force server call', () => {
   const $$ = new TestContext();

package.json

@@ -1,13 +1,26 @@
 {
   "name": "@salesforce/core",
-  "version": "6.7.6",
+  "version": "6.7.7-qa.1",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",
   "license": "BSD-3-Clause",
   "engines": {
     "node": ">=18.0.0"
   },
+  "exports": {
+    ".": "./lib/index.js",
+    "./testSetup": "./lib/testSetup.js",
+    "./messages": "./lib/messages.js",
+    "./sfError": "./lib/sfError.js",
+    "./lifecycle": "./lib/lifecycleEvents.js",
+    "./logger": "./lib/logger/logger.js",
+    "./configAggregator": "./lib/config/configAggregator.js",
+    "./stateAggregator": "./lib/stateAggregator/stateAggregator.js",
+    "./config": "./lib/config/config.js",
+    "./project": "./lib/sfProject.js",
+    "./messageTransformer": "./lib/messageTransformer.js"
+  },
   "scripts": {
     "build": "wireit",
     "clean": "sf-clean",
@@ -18,7 +31,6 @@
     "link-check": "wireit",
     "lint": "wireit",
     "lint-fix": "yarn sf-lint --fix",
-    "postcompile": "tsc -p typedocExamples",
     "prepack": "sf-prepack",
     "prepare": "sf-install",
     "test": "wireit",
@@ -39,6 +51,7 @@
     "messageTransformer/messageTransformer.ts"
   ],
   "dependencies": {
+    "@jsforce/jsforce-node": "^3.1.0",
     "@salesforce/kit": "^3.1.0",
     "@salesforce/schemas": "^1.7.0",
     "@salesforce/ts-types": "^2.0.9",
@@ -47,7 +60,6 @@
     "faye": "^1.4.0",
     "form-data": "^4.0.0",
     "js2xmlparser": "^4.0.1",
-    "jsforce": "^2.0.0-beta.29",
     "jsonwebtoken": "9.0.2",
     "jszip": "3.10.1",
     "pino": "^8.19.0",
@@ -58,7 +70,7 @@
     "ts-retry-promise": "^0.7.1"
   },
   "devDependencies": {
-    "@salesforce/dev-scripts": "^8.4.2",
+    "@salesforce/dev-scripts": "^8.5.0",
     "@salesforce/ts-sinon": "^1.4.19",
     "@types/benchmark": "^2.1.5",
     "@types/chai-string": "^1.4.5",
@@ -160,6 +172,9 @@
         "./!(CHANGELOG).md"
       ],
       "output": []
+    },
+    "compile-typedoc": {
+      "command": "tsc -p typedocExamples"
     }
   }
 }

src/config/config.ts

@@ -29,7 +29,7 @@ const CONFIG_FILE_NAME = 'config.json';
 /**
  * Interface for meta information about config properties
  */
-export interface ConfigPropertyMeta {
+export type ConfigPropertyMeta = {
   /**
    * The config property name.
    */
@@ -65,12 +65,12 @@ export interface ConfigPropertyMeta {
    * Is only used if deprecated is set to true.
    */
   newKey?: string;
-}
+};
 
 /**
  * Config property input validation
  */
-export interface ConfigPropertyMetaInput {
+export type ConfigPropertyMetaInput = {
   /**
    * Tests if the input value is valid and returns true if the input data is valid.
    *
@@ -82,7 +82,7 @@ export interface ConfigPropertyMetaInput {
    * The message to return in the error if the validation fails.
    */
   failedMessage: string | ((value: ConfigValue) => string);
-}
+};
 
 export enum SfConfigProperties {
   /**

src/config/configAggregator.ts

@@ -18,7 +18,7 @@ const messages = Messages.loadMessages('@salesforce/core', 'config');
 /**
  * Information about a config property.
  */
-export interface ConfigInfo {
+export type ConfigInfo = {
   /**
    * key The config key.
    */
@@ -57,7 +57,7 @@ export interface ConfigInfo {
    * True if the config property is deprecated.
    */
   deprecated?: boolean;
-}
+};
 
 /**
  * Aggregate global and local project config files, as well as environment variables for

src/config/configFile.ts

@@ -406,7 +406,7 @@ export namespace ConfigFile {
   /**
    * The interface for Config options.
    */
-  export interface Options extends BaseConfigStore.Options {
+  export type Options = {
     /**
      * The root folder where the config file is stored.
      */
@@ -435,5 +435,5 @@ export namespace ConfigFile {
      * Indicates if init should throw if the corresponding config file is not found.
      */
     throwOnNotFound?: boolean;
-  }
+  } & BaseConfigStore.Options;
 }

src/config/configStore.ts

@@ -17,7 +17,7 @@ import { ConfigContents, ConfigEntry, ConfigValue, Key } from './configStackType
 /**
  * An interface for a config object with a persistent store.
  */
-export interface ConfigStore<P extends ConfigContents = ConfigContents> {
+export type ConfigStore<P extends ConfigContents = ConfigContents> = {
   // Map manipulation methods
   entries(): ConfigEntry[];
   // NEXT_RELEASE: update types to specify return can be P[K] | undefined
@@ -40,7 +40,7 @@ export interface ConfigStore<P extends ConfigContents = ConfigContents> {
 
   // Content methods
   getContents(): P;
-}
+};
 
 /**
  * An abstract class that implements all the config management functions but
@@ -144,18 +144,19 @@ export abstract class BaseConfigStore<
    * @param value The value.
    */
   public set<K extends Key<P>>(key: K, value: P[K]): void {
+    let resolvedValue = value;
     if (this.hasEncryption()) {
-      if (isJsonMap(value)) {
-        value = this.recursiveEncrypt(value, key as string) as P[K];
+      if (isJsonMap(resolvedValue)) {
+        resolvedValue = this.recursiveEncrypt(resolvedValue, key as string) as P[K];
       } else if (this.isCryptoKey(key as string)) {
-        value = this.encrypt(value) as P[K];
+        resolvedValue = this.encrypt(resolvedValue) as P[K];
       }
     }
     // set(key, undefined) means unset
-    if (value === undefined) {
+    if (resolvedValue === undefined) {
       this.unset(key);
     } else {
-      this.contents.set(key, value);
+      this.contents.set(key, resolvedValue);
     }
   }
 
@@ -276,10 +277,8 @@ export abstract class BaseConfigStore<
    * @param contents The contents.
    */
   protected setContents(contents: P = {} as P): void {
-    if (this.hasEncryption()) {
-      contents = this.recursiveEncrypt(contents);
-    }
-    entriesOf(contents).map(([key, value]) => {
+    const maybeEncryptedContents = this.hasEncryption() ? this.recursiveEncrypt(contents) : contents;
+    entriesOf(maybeEncryptedContents).map(([key, value]) => {
       this.contents.set(key, value);
     });
   }
@@ -420,6 +419,8 @@ export abstract class BaseConfigStore<
         this.recursiveCrypto(method, [...keyPaths, key, newKey], value);
       }
     } else if (this.isCryptoKey(key)) {
+      // I think this side effect is intentional
+      // eslint-disable-next-line no-param-reassign
       data[key] = method(value);
     }
   }
@@ -432,7 +433,7 @@ export namespace BaseConfigStore {
   /**
    * Options for the config store.
    */
-  export interface Options {
+  export type Options = {
     /**
      * Keys to encrypt.
      *
@@ -442,5 +443,5 @@ export namespace BaseConfigStore {
      * defining a new class.
      */
     encryptedKeys?: Array<string | RegExp>;
-  }
+  };
 }

src/config/orgUsersConfig.ts

@@ -46,10 +46,10 @@ export namespace OrgUsersConfig {
   /**
    * The config file options.
    */
-  export interface Options extends ConfigFile.Options {
+  export type Options = {
     /**
      * The org id associated with this user.
      */
     orgId: string;
-  }
+  } & ConfigFile.Options;
 }

src/config/sandboxOrgConfig.ts

@@ -42,12 +42,12 @@ export namespace SandboxOrgConfig {
   /**
    * The config file options.
    */
-  export interface Options extends ConfigFile.Options {
+  export type Options = {
     /**
      * The org id associated with this sandbox.
      */
     orgId: string;
-  }
+  } & ConfigFile.Options;
 
   export enum Fields {
     /**

src/crypto/crypto.ts

@@ -113,10 +113,10 @@ const detectCryptoVersion = (pwd?: string): void => {
 Messages.importMessagesDirectory(pathJoin(__dirname));
 const messages = Messages.loadMessages('@salesforce/core', 'encryption');
 
-interface CredType {
+type CredType = {
   username: string;
   password: string;
-}
+};
 
 const makeSecureBuffer = (password: string, encoding: CryptoEncoding): SecureBuffer<string> => {
   const newSb = new SecureBuffer<string>();
@@ -179,12 +179,12 @@ const keychainPromises = {
   },
 };
 
-interface CryptoOptions {
+type CryptoOptions = {
   keychain?: KeyChain;
   platform?: string;
   retryStatus?: string;
   noResetOnClose?: boolean;
-}
+};
 
 /**
  * Class for managing encrypting and decrypting private auth information.