Get rid of WindowOrWorkerGlobalScope without splitting the entries

[foolip]

Filing an issue for a problem raised in #7849 (comment) and #8929 (comment).

When getting rid of mixins, the default outcome would be replacing api.WindowOrWorkerGlobalScope.fetch with api.Window.fetch + api.WorkerGlobalScope.fetch, but that doesn't seem great.

It's an accident of how Web IDL works that the exposure set of interfaces like Request is defined using [Exposed=(Window,Worker)] while the exposure set of methods like fetch is defined using partial interface mixin WindowOrWorkerGlobalScope.

I think we should find a common way to represent the worker exposure. Many different approaches could work, but my first suggestion would be api.WindowOrWorkerGlobalScope.fetch → api.fetch and working through the many consequences of that.

[saschanaz]

Do you intend to file an issue in Web IDL, because it kinda makes sense to me?

[foolip]

I hadn't planned on that, no. That would require new syntax for putting methods, attributes and constants on the global object, and I'm not sure what that would look like? I guess something like this?

[Exposed=Window]
Promise<Response> fetch(...);

Maybe that would be nice?

But I think it need not inform how we deal with this in BCD, it would be changing the syntax of Web IDL but not what the resulting JS environment is like.

[saschanaz]

[Exposed=Window]
global Promise<Response> fetch(...);
[Exposed=Window]
global attribute Navigator navigator;

I guess this form would be easier to read both for machines and humans. But yeah, it's not a blocker for BCD of course.

[foolip]

WindowOrWorkerGlobalScope is now one of a few remaining mixins in #8929.

I still think that we should have a single entry for these things, but I'm not sure if it should be api.fetch, api.builtins.fetch (like javascript.builtins.*) or something else. There's a similar question for the MDN structure.

@ddbeck @Elchi3 do you agree that we should keep single entries here? If it's only a matter of picking the structure, do you have any preferences? I would be happy with almost anything that unblocks #8929 :)

[ddbeck]

api.fetch would be the first thing i would try. I don't think we need to follow the builtins example. JS is a bit of a special case, since we also track a bunch of things which aren't in a real namespace (e.g., syntax features).

[Elchi3]

In #9125 (comment) @teoli2003 proposes to split. What you think about it, @foolip?

[foolip]

@Elchi3 that issue is about WorkerLocation and WorkerNavigator which aren't mixins and I think the solution might be different for those than for WindowOrWorkerGlobalScope. I'll comment over there though.

[Elchi3]

To understand better what we are trying to achieve here, I opened two draft PRs:

• Split Window and WorkerGlobalScope #11517
• Move WindowOrWorkerGlobalScope features to api.* (_globals folder) #11518

The first one (that proposes to split) felt more naturally fitting into BCD to me, but I'm happy to hear feedback. Also, let me know if I misunderstood what exactly was meant by not splitting this mixin.

[foolip]

#11518 matches what I had in mind, and I like what I'm seeing there. If the MDN pages are also merged, there would be a single place to learn about, for example, isSecureContext, and where it can be used. To my eye, it's a good thing that syntax and examples would be pushed in the direction of working in either context, so that developers can copy it regardless of where their code is running.

[Elchi3]

Yes, I think the unified approach has benefits for MDN readers. I will work on refining that PR further so we can see how it would go.

Does anyone else have thoughts on how a unified approach would break a bit an exact mapping from Web IDL to BCD paths? Is that a thing people care about?

[saschanaz]

Does anyone else have thoughts on how a unified approach would break a bit an exact mapping from Web IDL to BCD paths? Is that a thing people care about?

It matters in https://github.com/microsoft/TypeScript-DOM-lib-generator. I hope it should be easy enough to remap, but since the mapping is breaking further and further, I'll probably write a new library that represents exact mapping 🤔

[saschanaz]

but since the mapping is breaking further and further, I'll probably write a new library that represents exact mapping 🤔

For anyone interested: I published https://www.npmjs.com/package/bcd-idl-mapper

[foolip]

@saschanaz do you have an example of how to use bcd-idl-mapper together with a bunch of IDL and BCD? From the docs it sounds like it's just a BCD-like object, but I'm not quite sure how to use it.

[saschanaz]

It's basically same as getting the corresponding data from BCD. Say the wanted item is about WindowOrWorkerGlobalScope's setTimeout, it's (await import("bcd-idl-mapper")).default.__mixins.WindowOrWorkerGlobalScope.setTimeout.

[foolip]

I see, so it seems like bcd-idl-mapper is actually a reorganized version of BCD, I assumed based on the name that it would provide some mapping (IDL to BCD path) and not the BCD data directly. And it seems like as long as BCD still has some mixin data, bcd-idl-mapper is going to be a mix of styles, like __mixins.WindowOrWorkerGlobalScope.setTimeout (no .Window.) but __mixins.CanvasDrawImage.drawImage.CanvasRenderingContext2D.

[foolip]

@Elchi3 can you give a post-vacation refresher of the status and plans for this? I favor the approach in #11518 and would be happy to do some reviewing work to make it happen, but I'm not sure what it's blocked on.

[Elchi3]

I guess we need to make a call which route we want to go:

• Split Window and WorkerGlobalScope #11517 or
• Move WindowOrWorkerGlobalScope features to api.* (_globals folder) #11518

It seems like the _globals folder has more traction, so we could go down that path. Objections?

[foolip]

No objections, strong support! :)

[ddbeck]

The recap a discussion yesterday, we're in agreement on the _globals approach. Some things that need to happen for this issue and PR #11518:

• Propose a guideline for when features should be added to _globals. I think @foolip volunteered himself for this.
• Make corresponding content changes on MDN. @Elchi3 has volunteered to investigate this, to find out if it's something that could be done in a single PR or if it's a bigger effort than that.
• Coordinate merges on BCD and mdn/content and subsequent deployment. I'll be doing this part, when the previous steps are satisfied, since I handled the v4.0.0 coordination with the MDN dev team.

[Elchi3]

I believe mdn/content#8351 and #11518 fixed this.

[ddbeck]

Propose a guideline for when features should be added to _globals.

@Elchi3 I still don't think we have docs for when to use globals. Unless I've missed something. I think we should keep this open until it's done.

[Elchi3]

Oh yes, sorry. I'm assigning this to @foolip then.

[foolip]

I have "Guideline for _globals" written on a piece of paper here, so one day :)

[queengooborg]

The guidelines have been added in #12652, so I think it's safe to close this issue now!