Merge pull request #1221 from forcedotcom/sm/org-browser-web-bundling

W-19183667 feat: web bundling, virtual fs

Author: shetzel

CHANGELOG.md

@@ -13,6 +13,7 @@
     "./config": "./lib/config/config.js",
     "./configAggregator": "./lib/config/configAggregator.js",
     "./envVars": "./lib/config/envVars.js",
+    "./fs": "./lib/fs/fs.js",
     "./lifecycle": "./lib/lifecycleEvents.js",
     "./logger": "./lib/logger/logger.js",
     "./messages": "./lib/messages.js",
@@ -56,7 +57,7 @@
     "@jsforce/jsforce-node": "^3.10.0",
     "@salesforce/kit": "^3.2.2",
     "@salesforce/schemas": "^1.9.1",
-    "@salesforce/ts-types": "^2.0.10",
+    "@salesforce/ts-types": "^2.0.11",
     "ajv": "^8.17.1",
     "change-case": "^4.1.2",
     "fast-levenshtein": "^3.0.0",
@@ -65,6 +66,7 @@
     "js2xmlparser": "^4.0.1",
     "jsonwebtoken": "9.0.2",
     "jszip": "3.10.1",
+    "memfs": "^4.30.1",
     "pino": "^9.7.0",
     "pino-abstract-transport": "^1.2.0",
     "pino-pretty": "^11.3.0",

package.json

@@ -1,14 +1,14 @@
 /*
- * Copyright (c) 2020, salesforce.com, inc.
+ * Copyright (c) 2025, 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
  */
 
 import { dirname as pathDirname, join as pathJoin } from 'node:path';
-import * as fs from 'node:fs';
-import { keyBy, parseJsonMap } from '@salesforce/kit';
 import { Dictionary, ensure, isString, Nullable } from '@salesforce/ts-types';
+import { keyBy, parseJsonMap } from '@salesforce/kit';
+import { fs } from '../fs/fs';
 import { Global } from '../global';
 import { Logger } from '../logger/logger';
 import { Messages } from '../messages';

src/config/config.ts

@@ -5,11 +5,11 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import * as fs from 'node:fs';
-import { constants as fsConstants, Stats as fsStats } from 'node:fs';
 import { homedir as osHomedir } from 'node:os';
 import { join as pathJoin } from 'node:path';
+import { constants as fsConstants, Stats as fsStats } from 'node:fs';
 import { parseJsonMap } from '@salesforce/kit';
+import { fs } from '../fs/fs';
 import { Global } from '../global';
 import { Logger } from '../logger/logger';
 import { SfError } from '../sfError';
@@ -34,7 +34,7 @@ import { stateFromContents } from './lwwMap';
  * const myConfig = await MyConfig.create({
  *   isGlobal: true
  * });
- * myConfig.set('mykey', 'myvalue');
+ * myConfig.set('myKey', 'myValue');
  * await myConfig.write();
  * ```
  */
@@ -446,5 +446,5 @@ const getNsTimeStampSync = (filePath: string): bigint =>
   getNsTimeStampFromStatus(fs.statSync(filePath, { bigint: true }));
 
 /** in browser environment, memfs is missing the bigInt ns timestamp, so we generate it from the ms */
-const getNsTimeStampFromStatus = (stats: fs.BigIntStats): bigint =>
-  stats.mtimeNs ?? BigInt(stats.mtimeMs) * BigInt(1_000_000);
+const getNsTimeStampFromStatus = (stats: Awaited<ReturnType<typeof fs.promises.stat>>): bigint =>
+  'mtimeNs' in stats ? stats.mtimeNs : BigInt(stats.mtimeMs) * BigInt(1_000_000);

src/config/configFile.ts

@@ -423,9 +423,7 @@ export class Crypto extends AsyncOptionalCreatable<CryptoOptions> {
   }
 
   private async getKeyChain(platform: string): Promise<KeyChain> {
-    if (!this.options.keychain) {
-      this.options.keychain = await retrieveKeychain(platform);
-    }
+    this.options.keychain ??= await retrieveKeychain(platform);
     return this.options.keychain;
   }
 }

src/crypto/crypto.ts

@@ -6,21 +6,20 @@
  */
 
 import * as childProcess from 'node:child_process';
-import * as nodeFs from 'node:fs';
-import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { homedir } from 'node:os';
 import * as path from 'node:path';
 import { asString, ensureString, Nullable } from '@salesforce/ts-types';
 import { parseJsonMap } from '@salesforce/kit';
+import { fs } from '../fs/fs';
 import { Global } from '../global';
 import { SfError } from '../sfError';
 import { Messages } from '../messages';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/core', 'encryption');
 
-export type FsIfc = Pick<typeof nodeFs, 'statSync'>;
+export type FsIfc = Pick<typeof fs, 'statSync'>;
 
 const GET_PASSWORD_RETRY_COUNT = 3;
 
@@ -329,7 +328,7 @@ const linuxImpl: OsImpl = {
   setCommandFunc(opts, fn) {
     const secretTool = fn(linuxImpl.getProgram(), linuxImpl.setProgramOptions(opts));
     if (secretTool.stdin) {
-      secretTool.stdin.write(`${opts.password}\n`);
+      secretTool.stdin.write(`${opts.password ?? ''}\n`);
     }
     return secretTool;
   },
@@ -592,8 +591,8 @@ export const keyChainImpl = {
   generic_unix: new GenericUnixKeychainAccess(),
   // eslint-disable-next-line camelcase
   generic_windows: new GenericWindowsKeychainAccess(),
-  darwin: new KeychainAccess(darwinImpl, nodeFs),
-  linux: new KeychainAccess(linuxImpl, nodeFs),
+  darwin: new KeychainAccess(darwinImpl, fs),
+  linux: new KeychainAccess(linuxImpl, fs),
   validateProgram: _validateProgram,
 };
 

src/crypto/keyChainImpl.ts

@@ -143,8 +143,8 @@ export class DeviceOauthService extends AsyncCreatable<OAuth2Config> {
 
   protected async init(): Promise<void> {
     this.logger = await Logger.child(this.constructor.name);
-    this.logger.debug(`this.options.clientId: ${this.options.clientId}`);
-    this.logger.debug(`this.options.loginUrl: ${this.options.loginUrl}`);
+    this.logger.debug(`this.options.clientId: ${this.options.clientId ?? '<undefined>'}`);
+    this.logger.debug(`this.options.loginUrl: ${this.options.loginUrl ?? '<undefined>'}`);
   }
 
   private getLoginOptions(url: string): HttpRequest {

src/deviceOauthService.ts

@@ -0,0 +1,21 @@
+# Isomorphic filesystem support
+
+We want to support web and nodejs use of this library.
+
+fs.ts is meant to work in both scenarios.
+
+memfs is a **nearly** drop-in replacement for node:fs, with some inconsistencies.
+
+VirtualFS type should be an intersection type (the commonality between node:fs and memfs).
+
+- it can be more restrictive or more open as needed
+
+Then we can provide any overrides necessary to deal with the inconsistencies.
+
+That way, consumers can use import our `fs` module instead of `node:fs` and use it comfortably. So other libraries can then become isomorphic without a lot of work
+
+We, as a library, should handle the type complexity so that it's solid and reliable for consumers. minimal complexity is OK in the library, especially in types, since they are dev-time only.
+
+## ruled out
+
+Any kind of use of Proxy

src/fs/README.md

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2023, 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
+ */
+
+import * as nodeFs from 'node:fs';
+// yes, we're going to import it even though it might not be used.
+// the alternatives were all worse without top-level await (iife, runtime errors from something trying to use it before it's initialized)
+import * as memfs from 'memfs';
+import type { VirtualFs } from './types';
+
+export let fs: VirtualFs;
+
+const isWeb = (): boolean => process.env.FORCE_MEMFS === 'true' || 'window' in globalThis || 'self' in globalThis;
+
+export const getVirtualFs = (memfsVolume?: memfs.Volume): VirtualFs => {
+  if (isWeb()) {
+    const memfsInstance = memfs.createFsFromVolume(memfsVolume ?? new memfs.Volume());
+
+    // Start with memfs instance and only override problematic methods
+    const webFs = {
+      ...memfsInstance,
+
+      // Override only the methods that have incompatible signatures
+      promises: {
+        ...memfsInstance.promises,
+        writeFile: async (
+          file: string,
+          data: string | Buffer,
+          options?: BufferEncoding | { encoding?: BufferEncoding; mode?: string | number }
+        ): Promise<void> => {
+          const finalOptions = typeof options === 'string' ? { encoding: options } : options;
+          await memfsInstance.promises.writeFile(file, data, finalOptions);
+        },
+        readFile: async (path: string, encoding?: BufferEncoding): Promise<string | Buffer> => {
+          const result = await memfsInstance.promises.readFile(path, encoding);
+          return encoding === 'utf8' ? String(result) : Buffer.from(result);
+        },
+      },
+
+      readFileSync: (path: string, encoding?: BufferEncoding): string | Buffer => {
+        const result = memfsInstance.readFileSync(path, encoding);
+        return encoding === 'utf8' ? String(result) : Buffer.from(result);
+      },
+
+      writeFileSync: (file: string, data: string | Buffer, encoding?: BufferEncoding): void => {
+        memfsInstance.writeFileSync(file, data, { encoding });
+      },
+    } as unknown as VirtualFs;
+
+    return webFs;
+  }
+
+  return nodeFs as unknown as VirtualFs;
+};
+
+export const setFs = (providedFs: VirtualFs): void => {
+  fs = providedFs;
+};
+
+export const resetFs = (): void => {
+  fs = getVirtualFs();
+};
+
+// Initialize fs at module load time
+fs = getVirtualFs();

src/fs/fs.ts

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023, 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
+ */
+import type * as nodeFs from 'node:fs';
+import type { IFs as MemFs } from 'memfs';
+
+// Get the types for both node:fs and memfs
+type NodeFs = typeof nodeFs;
+
+// Find keys that exist in both types
+type CommonKeys<T, U> = keyof T & keyof U;
+
+// Create intersection type - be more specific for compatible methods
+type IntersectionType<T, U> = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [K in CommonKeys<T, U>]: T[K] extends (...args: any[]) => any
+    ? T[K] extends U[K]
+      ? T[K] // If signatures are compatible, use the more specific type
+      : U[K] extends T[K]
+      ? U[K] // If memfs signature is more specific, use that
+      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        any // Only use any for genuinely incompatible signatures
+    : T[K] extends U[K]
+    ? T[K]
+    : U[K] extends T[K]
+    ? U[K]
+    : T[K]; // Default to node:fs for non-functions
+};
+
+// Base intersection type
+type BaseVirtualFs = IntersectionType<NodeFs, MemFs>;
+
+// VirtualFs with specific overrides for methods we know the behavior of
+export type VirtualFs = Omit<
+  BaseVirtualFs,
+  'writeFileSync' | 'readFileSync' | 'statSync' | 'promises' | 'mkdtempSync' | 'createWriteStream' | 'mkdirSync'
+> & {
+  // Override promises object with specific types for methods we override
+  promises: Omit<BaseVirtualFs['promises'], 'writeFile' | 'readFile'> & {
+    writeFile: (
+      file: string,
+      data: string | Buffer,
+      options?: BufferEncoding | { encoding?: BufferEncoding; mode?: string | number }
+    ) => Promise<void>;
+    readFile: {
+      (path: string): Promise<Buffer>;
+      (path: string, encoding: BufferEncoding): Promise<string>;
+    };
+  };
+
+  // Override sync methods with specific types
+  readFileSync: {
+    (path: string): Buffer;
+    (path: string, encoding: BufferEncoding): string;
+  };
+  writeFileSync: (file: string, data: string | Buffer, encoding?: BufferEncoding) => void;
+  /** there are some differences between node:fs and memfs for statSync around bigint stats.  Be careful if using those */
+  statSync: typeof nodeFs.statSync;
+  mkdtempSync: typeof nodeFs.mkdtempSync;
+  createWriteStream: typeof nodeFs.createWriteStream;
+  mkdirSync: typeof nodeFs.mkdirSync;
+};