Added loadDhModules util to simplify standard usage (DH-19067)

Author: bmingles

package-lock.json

@@ -1,8 +1,7 @@
 # @deephaven/jsapi-nodejs
 
-Deephaven utils for consuming Jsapi from a server from a nodejs app. It can 
-optionally convert the server module format from `ESM` -> `CJS` or `CJS` -> `ESM` 
-if the server and consumer don't use the same module format.
+Deephaven utils for consuming Jsapi from a server from a nodejs app. The jsapi
+can be downloaded as an `ESM` or `CJS` module.
 
 ## Install
 
@@ -16,17 +15,14 @@ npm install --save @deephaven/jsapi-nodejs
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { loadModules } from '@deephaven/jsapi-nodejs';
+import { loadDhModules } from '@deephaven/jsapi-nodejs';
 
 const tmpDir = path.join(__dirname, 'tmp');
 
-// Download jsapi `ESM` files from DH Community server and export as `CJS` module.
-const dhc = await loadModules({
+// Download jsapi from a Deephaven server
+const dhc = await loadDhModules({
   serverUrl: new URL('http://localhost:10000'),
-  serverPaths: ['jsapi/dh-core.js', 'jsapi/dh-internal.js'],
-  download: true,
   storageDir: tmpDir,
-  sourceModuleType: 'esm',
-  targetModuleType: 'cjs',
+  targetModuleType: 'esm', // set to `cjs` to download as a CommonJS module
 });
 ```

packages/jsapi-nodejs/README.md

@@ -21,6 +21,7 @@
     "build:babel": "babel ./src --out-dir ./dist --extensions \".ts,.tsx,.js,.jsx\" --source-maps --root-mode upward"
   },
   "dependencies": {
+    "@deephaven/jsapi-types": "^1.0.0-dev0.37.2",
     "@deephaven/log": "file:../log",
     "@deephaven/utils": "file:../utils",
     "ws": "^8.18.0"

packages/jsapi-nodejs/package.json

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import type { dh as DhType } from '@deephaven/jsapi-types';
 
 import { downloadFromURL, urlToDirectoryName } from './serverUtils.js';
 import { polyfillWs } from './polyfillWs.js';
@@ -84,4 +85,65 @@ export async function loadModules<TMainModule>({
   return require(mainModulePath);
 }
 
-export default loadModules;
+/**
+ * Load `jsapi/dh-core.js` and `jsapi/dh-internal.js` modules from a Core Server.
+ * @param serverUrl The URL of the server to load from.
+ * @param storageDir The directory to store the downloaded modules.
+ * @param targetModuleType The type of module to load. Can be either 'esm' or 'cjs'.
+ * @returns The default export the `jsapi/dh-core.js` module.
+ */
+export async function loadDhModules({
+  serverUrl,
+  storageDir,
+  targetModuleType,
+}: Pick<
+  LoadModuleOptions,
+  'serverUrl' | 'storageDir' | 'targetModuleType'
+>): Promise<typeof DhType> {
+  if (targetModuleType === 'esm') {
+    // These will not be needed if we ever update the JSAPI to not rely on
+    // `window` and `self`.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    globalThis.self = globalThis;
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    globalThis.window = globalThis;
+  }
+
+  const coreModule = await loadModules<
+    typeof DhType & { default?: typeof DhType }
+  >({
+    serverUrl,
+    serverPaths: ['jsapi/dh-core.js', 'jsapi/dh-internal.js'],
+    storageDir,
+    targetModuleType,
+    download:
+      targetModuleType === 'esm'
+        ? // ESM does not need any transformation since the server modules are already ESM.
+          true
+        : // CJS needs a post-download transform to convert the ESM modules to CJS.
+          (serverPath, content) => {
+            if (serverPath === 'jsapi/dh-core.js') {
+              return content
+                .replace(
+                  `import {dhinternal} from './dh-internal.js';`,
+                  `const {dhinternal} = require("./dh-internal.js");`
+                )
+                .replace(`export default dh;`, `module.exports = dh;`);
+            }
+
+            if (serverPath === 'jsapi/dh-internal.js') {
+              return content.replace(
+                `export{__webpack_exports__dhinternal as dhinternal};`,
+                `module.exports={dhinternal:__webpack_exports__dhinternal};`
+              );
+            }
+
+            return content;
+          },
+  });
+
+  // ESM uses `default` export. CJS does not.
+  return coreModule.default ?? coreModule;
+}