For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/stage/1/proposal-inspector.md.
TC39 Atlas
  • English

      • Inspector S1

      Proposal details
      Proposal overview

      This proposal aims to provide a native, human-friendly way to inspect and compare values, addressing the limitations of current manual string interpolation in error messages. It proposes a standard mechanism that can offer special access to internal details like proxies and internal slots, potentially benefiting test runners and pattern matching.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Proposal: Inspector

      Champions:

      • @JakobJingleheimer
      • @gibson042

      Authors:

      • @JakobJingleheimer

      Stage

      Current: 1 (30 May 2025)

      The Problem

      Detailed inspection information in a human-friendly way, such as when comparing (diffing) values.

      In the context of Comparisons, merely knowing A is unexpected is almost useless when you can't see what A and B are.

      examples (current native capability)

      Annoying:

      if (A !== B) throw new Error('A does not equal B');
// Error: A does not equal B

      Better

      if (A !== B) throw new Error(`${A} does not equal ${B}`);
// Error: 1 does not equal 2

      But brittle

      if (A !== B) throw new Error(`${A} does not equal ${B}`);
// Error: [object Object] does not equal [object Object]
      examples (the general desire) 
      const result = compare(A, B);

{
  pretty: `{
    …
  ✓     qux: 'a',
  ✗     qux: 'b',
    …
  }`,
  paths: ['foo.bar.qux'],
  expected: 'a',
  actual: 'b',
}

      Reasons to provide natively:

      • Very expensive for userland to compose (the vast majority of test runner execution time)
        • Pretty printing
      • Special access (requires Modes - will not be available in "production"):
        • Proxies
        • Constituents of expressions (compiler)
        • Constituents of structure (diff)
        • Internal slots
      • Broadly applicable: can be used by more than Comparisons (e.g. Pattern Matching could leverage this; it could be used entirely on its own).

      Ecosystem today

      Currently, there are several libraries in userland that provide this functionality in varying ways.

      Runtimes (can offer special access):

      Libraries (cannot offer special access):

      Prior to stage 2

      • Consider customisation/extensibility (public symbols?)
        • This is potentially especially important for frameworks that may want to utilise Inspector under the hood and want to tweak only a very small piece.
      • Determine what information to provide, how, and under what cicumstances.
      • Modes as a requirement to offer "special access".