Use ranges with human readable sizes

Author: dinfuehr

docs/tool-reference.md

@@ -546,9 +546,9 @@ in the DevTools Elements panel (if any).
 - **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
 - **nodeId** (number) **(required)**: The node ID to get outgoing edges for.
 - **excludePrimitives** (boolean) _(optional)_: Whether to exclude primitive target nodes. Default is true.
-- **minRetainedSize** (number) _(optional)_: Minimum retained size in bytes for target nodes.
 - **pageIdx** (number) _(optional)_: The page index for pagination.
 - **pageSize** (number) _(optional)_: The page size for pagination.
+- **retainedSize** (string) _(optional)_: Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.
 - **sortBy** (enum: "retainedSize", "selfSize", "name") _(optional)_: Sort order for edges. Default is retainedSize.
 
 ---
@@ -603,21 +603,19 @@ in the DevTools Elements panel (if any).
 
 ### `query_heapsnapshot_objects`
 
-**Description:** Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)
+**Description:** Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)
 
 **Parameters:**
 
 - **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
 - **className** (string) _(optional)_: Optional regex or text matching object class name.
 - **isDetached** (boolean) _(optional)_: Whether to filter for detached DOM nodes.
-- **maxRetainedSize** (number) _(optional)_: Maximum retained size in bytes.
-- **maxSelfSize** (number) _(optional)_: Maximum self size in bytes.
-- **minRetainedSize** (number) _(optional)_: Minimum retained size in bytes.
-- **minSelfSize** (number) _(optional)_: Minimum self size in bytes.
 - **nodeType** (string) _(optional)_: Optional V8 node type filter (e.g. object, closure, string, array, code).
 - **pageIdx** (number) _(optional)_: The page index for pagination.
 - **pageSize** (number) _(optional)_: The page size for pagination.
 - **propertyName** (string) _(optional)_: Optional property name filter for outgoing reference edges.
+- **retainedSize** (string) _(optional)_: Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.
+- **selfSize** (string) _(optional)_: Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.
 - **sortBy** (enum: "retainedSize", "selfSize", "id") _(optional)_: Sort order for results. Default is retainedSize.
 
 ---

src/config/cli-options.ts

@@ -518,10 +518,11 @@ export const commands: Commands = {
         required: false,
         enum: ['retainedSize', 'selfSize', 'name'],
       },
-      minRetainedSize: {
-        name: 'minRetainedSize',
-        type: 'number',
-        description: 'Minimum retained size in bytes for target nodes.',
+      retainedSize: {
+        name: 'retainedSize',
+        type: 'string',
+        description:
+          'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.',
         required: false,
       },
       excludePrimitives: {
@@ -1102,7 +1103,7 @@ export const commands: Commands = {
   },
   query_heapsnapshot_objects: {
     description:
-      'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)',
+      'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)',
     category: 'Memory',
     args: {
       filePath: {
@@ -1131,28 +1132,18 @@ export const commands: Commands = {
           'Optional V8 node type filter (e.g. object, closure, string, array, code).',
         required: false,
       },
-      minRetainedSize: {
-        name: 'minRetainedSize',
-        type: 'number',
-        description: 'Minimum retained size in bytes.',
-        required: false,
-      },
-      maxRetainedSize: {
-        name: 'maxRetainedSize',
-        type: 'number',
-        description: 'Maximum retained size in bytes.',
-        required: false,
-      },
-      minSelfSize: {
-        name: 'minSelfSize',
-        type: 'number',
-        description: 'Minimum self size in bytes.',
+      retainedSize: {
+        name: 'retainedSize',
+        type: 'string',
+        description:
+          'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
         required: false,
       },
-      maxSelfSize: {
-        name: 'maxSelfSize',
-        type: 'number',
-        description: 'Maximum self size in bytes.',
+      selfSize: {
+        name: 'selfSize',
+        type: 'string',
+        description:
+          'Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
         required: false,
       },
       isDetached: {

src/telemetry/tool_call_metrics.json

@@ -831,11 +831,16 @@
       },
       {
         "name": "min_retained_size",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       },
       {
         "name": "exclude_primitives",
         "argType": "boolean"
+      },
+      {
+        "name": "retained_size_length",
+        "argType": "number"
       }
     ]
   },
@@ -1000,19 +1005,23 @@
       },
       {
         "name": "min_retained_size",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       },
       {
         "name": "max_retained_size",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       },
       {
         "name": "min_self_size",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       },
       {
         "name": "max_self_size",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       },
       {
         "name": "is_detached",
@@ -1029,6 +1038,14 @@
       {
         "name": "page_size",
         "argType": "number"
+      },
+      {
+        "name": "retained_size_length",
+        "argType": "number"
+      },
+      {
+        "name": "self_size_length",
+        "argType": "number"
       }
     ]
   }

src/tools/memory.ts

@@ -5,6 +5,7 @@
  */
 
 import {zod} from '../third_party/index.js';
+import {parseByteSizeRange} from '../utils/bytes.js';
 
 import {ToolCategory} from './categories.js';
 import {definePageTool, defineTool} from './ToolDefinition.js';
@@ -19,6 +20,23 @@ const HEAP_SNAPSHOT_FILTERS: readonly [string, ...string[]] = [
   'attributedToSpecificNativeContext',
 ];
 
+function byteSizeRangeSchema(description: string) {
+  return zod
+    .string()
+    .superRefine((value, context) => {
+      try {
+        parseByteSizeRange(value);
+      } catch (error) {
+        context.addIssue({
+          code: zod.ZodIssueCode.custom,
+          message:
+            error instanceof Error ? error.message : 'Invalid byte size range',
+        });
+      }
+    })
+    .describe(description);
+}
+
 export const takeHeapSnapshot = definePageTool({
   name: 'take_heapsnapshot',
   description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
@@ -305,10 +323,9 @@ export const getHeapSnapshotEdges = defineTool({
       .enum(['retainedSize', 'selfSize', 'name'])
       .optional()
       .describe('Sort order for edges. Default is retainedSize.'),
-    minRetainedSize: zod
-      .number()
-      .optional()
-      .describe('Minimum retained size in bytes for target nodes.'),
+    retainedSize: byteSizeRangeSchema(
+      'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.',
+    ).optional(),
     excludePrimitives: zod
       .boolean()
       .optional()
@@ -317,12 +334,17 @@ export const getHeapSnapshotEdges = defineTool({
     pageSize: zod.number().optional().describe('The page size for pagination.'),
   },
   handler: async (request, response, context) => {
+    const retainedSize =
+      request.params.retainedSize === undefined
+        ? undefined
+        : parseByteSizeRange(request.params.retainedSize);
     const edges = await context.getHeapSnapshotEdges(
       request.params.filePath,
       request.params.nodeId,
       {
         sortBy: request.params.sortBy ?? 'retainedSize',
-        minRetainedSize: request.params.minRetainedSize,
+        // DevTools currently only supports a lower retained-size bound here.
+        minRetainedSize: retainedSize?.min,
         excludePrimitives: request.params.excludePrimitives ?? true,
       },
     );
@@ -469,7 +491,7 @@ export const getHeapSnapshotObjectDetails = defineTool({
 export const queryHeapSnapshotObjects = defineTool({
   name: 'query_heapsnapshot_objects',
   description:
-    'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, minRetainedSize, maxRetainedSize, minSelfSize, isDetached, sortBy).',
+    'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy).',
   annotations: {
     category: ToolCategory.MEMORY,
     readOnlyHint: true,
@@ -493,22 +515,12 @@ export const queryHeapSnapshotObjects = defineTool({
       .describe(
         'Optional V8 node type filter (e.g. object, closure, string, array, code).',
       ),
-    minRetainedSize: zod
-      .number()
-      .optional()
-      .describe('Minimum retained size in bytes.'),
-    maxRetainedSize: zod
-      .number()
-      .optional()
-      .describe('Maximum retained size in bytes.'),
-    minSelfSize: zod
-      .number()
-      .optional()
-      .describe('Minimum self size in bytes.'),
-    maxSelfSize: zod
-      .number()
-      .optional()
-      .describe('Maximum self size in bytes.'),
+    retainedSize: byteSizeRangeSchema(
+      'Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
+    ).optional(),
+    selfSize: byteSizeRangeSchema(
+      'Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.',
+    ).optional(),
     isDetached: zod
       .boolean()
       .optional()
@@ -521,16 +533,24 @@ export const queryHeapSnapshotObjects = defineTool({
     pageSize: zod.number().optional().describe('The page size for pagination.'),
   },
   handler: async (request, response, context) => {
+    const retainedSize =
+      request.params.retainedSize === undefined
+        ? undefined
+        : parseByteSizeRange(request.params.retainedSize);
+    const selfSize =
+      request.params.selfSize === undefined
+        ? undefined
+        : parseByteSizeRange(request.params.selfSize);
     const range = await context.queryHeapSnapshotObjects(
       request.params.filePath,
       {
         className: request.params.className,
         propertyName: request.params.propertyName,
         nodeType: request.params.nodeType,
-        minRetainedSize: request.params.minRetainedSize,
-        maxRetainedSize: request.params.maxRetainedSize,
-        minSelfSize: request.params.minSelfSize,
-        maxSelfSize: request.params.maxSelfSize,
+        minRetainedSize: retainedSize?.min,
+        maxRetainedSize: retainedSize?.max,
+        minSelfSize: selfSize?.min,
+        maxSelfSize: selfSize?.max,
         isDetached: request.params.isDetached,
         sortBy: request.params.sortBy,
       },