fix(compass-web): bundle type definitions COMPASS-9733 (#7227)

nbbeeken · gribnoysup · web-flow · commit 5a26679343d2 · 2025-08-27T17:36:01.000-04:00
Co-authored-by: Sergey Petushkov &lt;petushkov.sergey@gmail.com&gt;
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/compass-connections/src/stores/store-context.tsx b/packages/compass-connections/src/stores/store-context.tsx
@@ -117,7 +117,7 @@ function getConnectionsActions(dispatch: ConnectionsStore['dispatch']) {
       return dispatch(saveEditedConnectionInfo(connectionInfo));
     },
     cancelEditConnection: (connectionId: ConnectionId) => {
-      return dispatch(cancelEditConnection(connectionId));
+      dispatch(cancelEditConnection(connectionId));
     },
     toggleFavoritedConnectionStatus: (connectionId: ConnectionId) => {
       return dispatch(toggleConnectionFavoritedStatus(connectionId));
diff --git a/packages/compass-web/.eslintignore b/packages/compass-web/.eslintignore
@@ -1,2 +1,3 @@
 .nyc-output
 dist
+test/types
diff --git a/packages/compass-web/api-extractor.json b/packages/compass-web/api-extractor.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "./dist/index.d.ts",
+  "newlineKind": "lf",
+  "bundledPackages": [
+    "@mongodb-js/*",
+    "@mongodb-js/mdb-experiment-js",
+    "@mongodb-js/connection-info",
+    "bson-transpilers",
+    "compass-e2e-tests",
+    "compass-preferences-model",
+    "hadron-build",
+    "hadron-document",
+    "hadron-ipc",
+    "hadron-type-checker",
+    "mongodb-instance-model",
+    "mongodb-explain-compat",
+    "mongodb-query-util",
+    "mongodb-data-service",
+    "mongodb-database-model",
+    "mongodb-collection-model",
+    "mongodb-compass"
+  ],
+  "compiler": {
+    "tsconfigFilePath": "./tsconfig-build.json"
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+  },
+  "apiReport": {
+    "enabled": false
+  },
+  "docModel": {
+    "enabled": false
+  }
+}
diff --git a/packages/compass-web/package.json b/packages/compass-web/package.json
@@ -33,13 +33,18 @@
     ".": "./src/index.tsx",
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
+  "types": "./dist/compass-web.d.ts",
   "scripts": {
+    "bootstrap": "npm run postcompile",
     "prepublishOnly": "npm run compile && compass-scripts check-exports-exist",
     "compile": "npm run webpack -- --mode production",
     "webpack": "webpack-compass",
     "postcompile": "npm run typescript",
     "typescript": "tsc -p tsconfig-build.json --emitDeclarationOnly",
+    "posttypescript": "npm run api-extractor",
+    "api-extractor": "api-extractor run --local",
+    "postapi-extractor": "node scripts/clean-dts.mjs",
+    "test-types": "cd test/types && npm install && npm test",
     "prestart": "npm run compile -w @mongodb-js/webpack-config-compass",
     "start": "electron ./scripts/electron-proxy.js",
     "analyze": "npm run webpack -- --mode production --analyze",
@@ -51,6 +56,7 @@
     "lint": "npm run eslint . && npm run prettier -- --check .",
     "depcheck": "depcheck",
     "check": "npm run typecheck && npm run lint && npm run depcheck",
+    "postcheck": "npm run test-types",
     "check-ci": "npm run check",
     "test": "mocha",
     "test-cov": "nyc --compact=false --produce-source-map=false -x \"**/*.spec.*\" --reporter=lcov --reporter=text --reporter=html npm run test",
@@ -63,6 +69,7 @@
     "react-dom": "^17.0.2"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.52.11",
     "@mongodb-js/atlas-service": "^0.56.0",
     "@mongodb-js/compass-aggregations": "^9.73.0",
     "@mongodb-js/compass-app-registry": "^9.4.20",
@@ -88,6 +95,7 @@
     "@mongodb-js/compass-telemetry": "^1.14.0",
     "@mongodb-js/compass-welcome": "^0.69.0",
     "@mongodb-js/compass-workspaces": "^0.52.0",
+    "@mongodb-js/connection-info": "^0.17.2",
     "@mongodb-js/connection-storage": "^0.46.0",
     "@mongodb-js/devtools-proxy-support": "^0.5.2",
     "@mongodb-js/eslint-config-compass": "^1.4.7",
diff --git a/packages/compass-web/scripts/clean-dts.mjs b/packages/compass-web/scripts/clean-dts.mjs
@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import url from 'node:url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const distDir = path.join(__dirname, '..', 'dist');
+
+await Promise.all(
+  (
+    await fs.readdir(distDir)
+  )
+    .filter((file) => file.endsWith('.d.ts') || file.endsWith('.d.ts.map'))
+    .filter((file) => file !== 'compass-web.d.ts')
+    .map((file) => fs.unlink(path.join(distDir, file)))
+);
diff --git a/packages/compass-web/src/entrypoint.tsx b/packages/compass-web/src/entrypoint.tsx
@@ -3,10 +3,14 @@ import AppRegistry, {
   AppRegistryProvider,
   GlobalAppRegistryProvider,
 } from '@mongodb-js/compass-app-registry';
-import type { ConnectionInfo } from '@mongodb-js/compass-connections/provider';
+import type { AtlasClusterMetadata } from '@mongodb-js/connection-info';
 import { useConnectionActions } from '@mongodb-js/compass-connections/provider';
 import { CompassInstanceStorePlugin } from '@mongodb-js/compass-app-stores';
-import type { OpenWorkspaceOptions } from '@mongodb-js/compass-workspaces';
+import type {
+  CollectionTabInfo,
+  OpenWorkspaceOptions,
+  WorkspaceTab,
+} from '@mongodb-js/compass-workspaces';
 import WorkspacesPlugin, {
   WorkspacesProvider,
 } from '@mongodb-js/compass-workspaces';
@@ -63,6 +67,7 @@ import {
   CompassAssistantProvider,
 } from '@mongodb-js/compass-assistant';
 
+/** @public */
 export type TrackFunction = (
   event: string,
   properties: Record<string, any>
@@ -91,7 +96,8 @@ type CompassWorkspaceProps = Pick<
     'onOpenConnectViaModal'
   >;
 
-type CompassWebProps = {
+/** @public */
+export type CompassWebProps = {
   /**
    * App name to be passed with the connection string when connection to a
    * cluster (default: "Compass Web")
@@ -131,9 +137,12 @@ type CompassWebProps = {
    * communicate current workspace back to the parent component for example to
    * sync router with the current active workspace
    */
-  onActiveWorkspaceTabChange: React.ComponentProps<
-    typeof WorkspacesPlugin
-  >['onActiveWorkspaceTabChange'];
+  onActiveWorkspaceTabChange<WS extends WorkspaceTab>(
+    ws: WS | null,
+    collectionInfo: WS extends { type: 'Collection' }
+      ? CollectionTabInfo | null
+      : never
+  ): void;
 
   /**
    * Set of initial preferences to override default values
@@ -159,9 +168,7 @@ type CompassWebProps = {
    * when the action is selected from the sidebar actions. Should be used to
    * show the Atlas Cloud "Connect" modal
    */
-  onOpenConnectViaModal?: (
-    atlasMetadata: ConnectionInfo['atlasMetadata']
-  ) => void;
+  onOpenConnectViaModal?: (atlasMetadata?: AtlasClusterMetadata) => void;
 
   /**
    * Callback prop called when connections fail to load
@@ -259,6 +266,7 @@ const connectedContainerStyles = css({
   display: 'flex',
 });
 
+/** @public */
 const CompassWeb = ({
   appName,
   orgId,
diff --git a/packages/compass-web/src/index.tsx b/packages/compass-web/src/index.tsx
@@ -1,8 +1,14 @@
 export { CompassWeb } from './entrypoint';
+export type { CompassWebProps, TrackFunction } from './entrypoint';
 export * from './url-builder';
 export type {
   OpenWorkspaceOptions,
   WorkspaceTab,
 } from '@mongodb-js/compass-workspaces';
 
 export { CompassExperimentationProvider } from '@mongodb-js/compass-telemetry';
+
+export type { CollectionTabInfo } from '@mongodb-js/compass-workspaces';
+export type { AllPreferences } from 'compass-preferences-model/provider';
+export type { AtlasClusterMetadata } from '@mongodb-js/connection-info';
+export type { LogFunction, LogMessage, DebugFunction } from './logger';
diff --git a/packages/compass-web/src/logger.tsx b/packages/compass-web/src/logger.tsx
@@ -4,6 +4,7 @@ import type { Writable } from 'stream';
 import { mongoLogId } from '@mongodb-js/compass-logging/provider';
 import { useRef } from 'react';
 
+/** @public */
 export type LogMessage = {
   id: number;
   t: { $date: string };
@@ -13,8 +14,11 @@ export type LogMessage = {
   msg: string;
   attr?: any;
 };
+
+/** @public */
 export type LogFunction = (message: LogMessage) => void;
 
+/** @public */
 export type DebugFunction = (...args: any[]) => void;
 
 type Debugger = Logger['debug'];
diff --git a/packages/compass-web/src/url-builder.ts b/packages/compass-web/src/url-builder.ts
@@ -49,6 +49,7 @@ function getRouteFromCollectionSubTab(subTab: CollectionSubtab): string {
   }
 }
 
+/** @public */
 export function getWorkspaceTabFromRoute(
   route: string
 ): OpenWorkspaceOptions | null {
@@ -85,6 +86,7 @@ function buildAbsoluteURL(...parts: string[]) {
   );
 }
 
+/** @public */
 export function getRouteFromWorkspaceTab(tab: WorkspaceTab | null) {
   let route: string;
   switch (tab?.type) {
diff --git a/packages/compass-web/test/types/index.test-d.ts b/packages/compass-web/test/types/index.test-d.ts
@@ -0,0 +1,32 @@
+import { expectError } from 'tsd';
+import { CompassWeb } from '@mongodb-js/compass-web';
+
+// Test basic props structure
+const basicProps = {
+  orgId: 'test-org',
+  projectId: 'test-project',
+  onActiveWorkspaceTabChange: () => {},
+  onFailToLoadConnections: () => {},
+};
+
+// Test that the component can be called with basic props
+void CompassWeb(basicProps);
+
+// Test preference property validation
+// This should work - optInGenAIFeatures is the correct external property name
+void CompassWeb({
+  ...basicProps,
+  initialPreferences: {
+    optInGenAIFeatures: true,
+  },
+});
+
+// This should cause an error - optInDataExplorerGenAIFeatures is an old name
+expectError(
+  CompassWeb({
+    ...basicProps,
+    initialPreferences: {
+      optInDataExplorerGenAIFeatures: true,
+    },
+  })
+);
diff --git a/packages/compass-web/test/types/package.json b/packages/compass-web/test/types/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "@mongodb-js/compass-web-types-test",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Test package to verify compass-web types work correctly for external consumers",
+  "scripts": {
+    "test": "tsd --typings ./node_modules/@mongodb-js/compass-web/dist/compass-web.d.ts --files ./*.test-d.ts"
+  },
+  "dependencies": {
+    "@mongodb-js/compass-web": "file:../../",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  },
+  "devDependencies": {
+    "@types/react": "^17.0.2",
+    "@types/react-dom": "^17.0.2",
+    "tsd": "^0.31.0",
+    "typescript": "^5.0.0"
+  }
+}
diff --git a/packages/compass-web/test/types/readme.md b/packages/compass-web/test/types/readme.md
@@ -0,0 +1,21 @@
+# Compass Web Type Tests
+
+Type tests for `@mongodb-js/compass-web` using [tsd](https://github.com/SamVerschueren/tsd).
+
+## Why a separate package?
+
+This directory is structured as its own npm package to **simulate an external consumer environment**. The main `compass-web` package has access to all internal dependencies, but real consumers only get the bundled `compass-web.d.ts` file.
+
+This setup ensures our type definitions are truly standalone and don't accidentally depend on internal types that consumers won't have access to.
+
+## Running tests
+
+From main compass-web directory:
+
+```bash
+npm run test-types
+```
+
+Also runs after: `npm run check`
+
+Tests validate that the bundled types work correctly for external consumers without requiring internal Compass dependencies.
diff --git a/packages/compass-web/test/types/tsconfig.json b/packages/compass-web/test/types/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": false,
+    "noEmit": true,
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "include": ["**/*.test-d.ts"]
+}
diff --git a/packages/compass-web/tsconfig-lint.json b/packages/compass-web/tsconfig-lint.json
@@ -1,5 +1,5 @@
 {
   "extends": "./tsconfig.json",
   "include": ["**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "test/types"]
 }

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`.nyc-output`
`2`	`2`	`dist`
	`3`	`+test/types`
Original file line number	Diff line number	Diff line change
`@@ -49,6 +49,7 @@ function getRouteFromCollectionSubTab(subTab: CollectionSubtab): string {`
`49`	`49`	`}`
`50`	`50`	`}`
`51`	`51`
	`52`	`+/** @public */`
`52`	`53`	`export function getWorkspaceTabFromRoute(`
`53`	`54`	`route: string`
`54`	`55`	`): OpenWorkspaceOptions \| null {`
`@@ -85,6 +86,7 @@ function buildAbsoluteURL(...parts: string[]) {`
`85`	`86`	`);`
`86`	`87`	`}`
`87`	`88`
	`89`	`+/** @public */`
`88`	`90`	`export function getRouteFromWorkspaceTab(tab: WorkspaceTab \| null) {`
`89`	`91`	`let route: string;`
`90`	`92`	`switch (tab?.type) {`