Debug IDs Proposal: Should We Define a JavaScript API?

[lforst]

This issue relates to the Debug ID proposal.

While we’ve made good progress in defining how Debug IDs should be represented in generated artifacts through the debugId field and //# debugId=... comments, we are still slightly blocked on the part of the proposal that suggests how engines and languages should interact with Debug IDs.

When superficially looking at implementing a JS API in various engines, a fundamental question came up: Should we even propose and specify a runtime API?

Considerations

1. Scope of the Source Map Spec
   First up, there is the issue of the Source Map Spec technically being entirely separate from the ECMAScript and HTML Specs. It feels somewhat nonsensical to put a specification for a runtime API into the Source Map Spec, especially since the Spec is mostly language agnostic.

2. Challenges in API Design
   When exploring potential designs for a JavaScript API, several complications arise:

   • Approach 1: getDebugIdForUrl(url: string): string | null;
     A straightforward idea is to create an API like getDebugIdForUrl(), which, given a file URL, retrieves the corresponding Debug ID. For example, upon encountering an error, we could parse the stack trace, extract each frame’s file URL, and pass it to getDebugIdForUrl() to obtain its Debug ID.

     However, this approach has a critical flaw: the Error.stack property, which would be necessary for parsing the stack trace, is not formally specified. This makes it unreliable as a foundation for a standardized API, since it relies on non-standardized conventions across engines.

   • Approach 2: Error.getDebugIdsForError(err: Error): (string | null)[];
     Having established that relying on Error.stack is not great, an alternative would be a static API Error.getDebugIdsForError(), which, when passed an error object, returns an array of Debug IDs for each stack frame, with null indicating a missing Debug ID. This approach is a bit more functional it abstracts away the specifics of stack trace parsing and Debug ID retrieval.

     However, this API also comes with engine-specific challenges. In V8 it seems doable with a reasonable and lazy evaluation. In JavaScriptCore it becomes a bit harder because the stack is captured at Exception-Time and we would probably have to grab the Debug IDs at that point in time too. For Spidermonkey it will likely work out similar to JSC. Because for 2 out of 3 engines, this implementation would have a non-trivial runtime impact, lending itself to an opt-in situation (Error.captureDebugIds = true), it may again be hard to find a standardized specification.

Open Question: Advancing the Proposal Without a Runtime API?

Considering that it may become quite hard to find a common denominator for a specification here, and considering that the Source Map Spec is likely the wrong place for a specification anyhow I want to ask the following question: Would it make sense to advance the proposal even without a runtime API?

I have a feeling that we may end up in a situation like with Error.stack, where it is a de-facto standard but there are minor differences in implementation and ergonomics. In my personal opinion, this would be fine and still represent a meaningful improvement to the ecosystem.