Merge pull request #2311 from microsoft/copilot/add-symbol-based-mechanism

Implement Symbol.for("debug.properties") for custom property replacement in debugger

Author: hediet

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 This changelog records changes to stable releases since 1.50.2. "TBA" changes here may be available in the [nightly release](https://github.com/microsoft/vscode-js-debug/#nightly-extension) before they're in stable. Note that the minor version (`v1.X.0`) corresponds to the VS Code version js-debug is shipped in, but the patch version (`v1.50.X`) is not meaningful.
 
+## Unreleased
+
+- feat: add `Symbol.for("debug.properties")` for custom property replacement in debugger ([vscode#102181](https://github.com/microsoft/vscode/issues/102181))
+
 ## 1.105 (September 2025)
 
 - fix: slow sourcemap parsing for minified code ([#2265](https://github.com/microsoft/vscode-js-debug/issues/2265))

src/adapter/templates/getStringyProps.ts

@@ -4,11 +4,13 @@
 
 import { remoteFunction, templateFunction } from '.';
 
-const enum DescriptionSymbols {
+export const enum DescriptionSymbols {
   // Our generic symbol
   Generic = 'debug.description',
   // Node.js-specific symbol that is used for some Node types https://nodejs.org/api/util.html#utilinspectcustom
   Node = 'nodejs.util.inspect.custom',
+  // Symbol for custom property replacement
+  Properties = 'debug.properties',
 
   // Depth for `nodejs.util.inspect.custom`
   Depth = 2,
@@ -20,7 +22,11 @@ const enum DescriptionSymbols {
  * use them inside the description functions.
  */
 export const getDescriptionSymbols = remoteFunction(function() {
-  return [Symbol.for(DescriptionSymbols.Generic), Symbol.for(DescriptionSymbols.Node)];
+  return [
+    Symbol.for(DescriptionSymbols.Generic),
+    Symbol.for(DescriptionSymbols.Node),
+    Symbol.for(DescriptionSymbols.Properties),
+  ];
 });
 
 declare const runtimeArgs: [symbol[]];
@@ -34,6 +40,7 @@ export const getStringyProps = templateFunction(function(
   maxLength: number,
   customToString: (defaultRepr: string) => unknown,
 ) {
+  let customProps = false;
   const out: Record<string, string> = {};
   const defaultPlaceholder = '<<default preview>>';
   if (typeof this !== 'object' || !this) {
@@ -63,7 +70,7 @@ export const getStringyProps = templateFunction(function(
 
     if (typeof value === 'object' && value) {
       let str: string | undefined;
-      for (const sym of runtimeArgs[0]) {
+      for (const sym of runtimeArgs[0].slice(0, 2)) {
         if (typeof value[sym] !== 'function') {
           continue;
         }
@@ -85,7 +92,14 @@ export const getStringyProps = templateFunction(function(
     }
   }
 
-  return out;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    customProps = typeof (this as any)[runtimeArgs[0][2]] === 'function';
+  } catch {
+    // ignored
+  }
+
+  return { out, customProps };
 });
 
 export const getToStringIfCustom = templateFunction(function(
@@ -133,3 +147,33 @@ export const getToStringIfCustom = templateFunction(function(
     }
   }
 });
+
+/**
+ * Checks if the object has a custom properties function via Symbol.for("debug.properties")
+ * and returns the replacement object if it does. Returns undefined otherwise.
+ * The symbols array is passed via runtimeArgs[0], with properties symbol at index 2.
+ */
+export const getCustomProperties = templateFunction(function(this: unknown) {
+  const propertiesSymbol: symbol = (runtimeArgs as unknown as [symbol[]])[0][2];
+
+  if (typeof this !== 'object' || !this) {
+    return undefined;
+  }
+
+  // Check if the object has the debug.properties symbol
+  if (typeof (this as Record<symbol, () => unknown>)[propertiesSymbol] !== 'function') {
+    return undefined;
+  }
+
+  try {
+    const result = (this as Record<symbol, () => unknown>)[propertiesSymbol]();
+    // Only return if we got a valid object back
+    if (typeof result === 'object' && result !== null) {
+      return result;
+    }
+  } catch {
+    // If the function throws, we'll just return undefined and use default properties
+  }
+
+  return undefined;
+});